Span Kinds

All OpenInference span kinds with detailed descriptions and examples

The openinference.span.kind attribute is REQUIRED for all OpenInference spans and identifies the type of operation being traced. The span kind provides a hint to the tracing backend as to how the trace should be assembled and visualized.

The openinference.span.kind attribute is distinct from OpenTelemetry’s span_kind field. The OpenTelemetry span_kind is usually set to SPAN_KIND_INTERNAL, while openinference.span.kind provides AI-specific classification.

LLM

A span that represents a call to a Large Language Model (LLM).

Example use cases:

• Call to OpenAI for chat completions
• Call to Anthropic Claude
• Call to Llama for text generation
• Any language model API invocation

Required attributes:

• openinference.span.kind: "LLM"
• llm.system: The AI system/product (e.g., “openai”, “anthropic”)

Common attributes:

• llm.model_name: Model identifier (e.g., “gpt-4-0613”)
• llm.input_messages: Input messages array
• llm.output_messages: Output messages array
• llm.token_count.*: Token usage metrics
• llm.invocation_parameters: Model parameters (temperature, max_tokens, etc.)

Example

{
    "attributes": {
        "openinference.span.kind": "LLM",
        "llm.system": "openai",
        "llm.model_name": "gpt-4-0613",
        "llm.token_count.prompt": 229,
        "llm.token_count.completion": 21,
        "llm.token_count.total": 250
    }
}

View LLM span specification

See the LLM Spans specification for complete details on LLM-specific attributes.

---

EMBEDDING

A span that represents a call to an LLM or embedding service for generating embeddings.

Example use cases:

• Call to OpenAI to get text-embedding-3-small embeddings
• Call to Cohere for embedding generation
• Generating embeddings for retrieval or similarity search

Required attributes:

• openinference.span.kind: "EMBEDDING"

Common attributes:

• embedding.model_name: Embedding model name
• embedding.embeddings: Array of embedding objects
• embedding.invocation_parameters: Model parameters
• llm.token_count.prompt: Number of tokens in input

Example

{
    "attributes": {
        "openinference.span.kind": "EMBEDDING",
        "embedding.model_name": "text-embedding-3-small",
        "embedding.embeddings.0.embedding.text": "hello world",
        "embedding.embeddings.0.embedding.vector": [0.1, 0.2, 0.3],
        "llm.token_count.prompt": 2
    }
}

Unlike LLM spans, embedding spans use embedding.model_name instead of llm.system and llm.provider.

---

CHAIN

A span that represents a starting point or a link between different LLM application steps.

Example use cases:

• The beginning of a request to an LLM application
• Glue code that passes context from a retriever to an LLM call
• Orchestration logic connecting multiple operations
• Prompt formatting and post-processing
• Deterministic sequences of operations

Example

{
    "attributes": {
        "openinference.span.kind": "CHAIN",
        "input.value": "What is the weather in San Francisco?",
        "input.mime_type": "text/plain",
        "output.value": "The weather in San Francisco is 72°F and sunny.",
        "output.mime_type": "text/plain"
    }
}

CHAIN spans often serve as root spans for traces, representing the overall operation before breaking down into sub-operations.

---

RETRIEVER

A span that represents a data retrieval step.

Example use cases:

• Call to a vector store (Pinecone, Weaviate, Chroma)
• Query to a traditional database
• Search engine query
• Document or knowledge base lookup

Common attributes:

• retrieval.documents: Array of retrieved documents
• document.id: Document identifier
• document.content: Document text content
• document.score: Relevance score
• document.metadata: Additional document metadata

Example

{
    "attributes": {
        "openinference.span.kind": "RETRIEVER",
        "retrieval.documents.0.document.id": "doc_123",
        "retrieval.documents.0.document.content": "San Francisco weather data...",
        "retrieval.documents.0.document.score": 0.95,
        "retrieval.documents.1.document.id": "doc_456",
        "retrieval.documents.1.document.content": "California climate information...",
        "retrieval.documents.1.document.score": 0.87
    }
}

---

RERANKER

A span that represents the reranking of a set of input documents.

Example use cases:

• Cross-encoder computing relevance scores
• Reordering retrieved documents by relevance to a query
• Selecting top K documents from a larger candidate set

Common attributes:

• reranker.input_documents: Documents before reranking
• reranker.output_documents: Documents after reranking
• reranker.query: The query used for reranking
• reranker.model_name: Reranking model identifier
• reranker.top_k: Number of top documents to return

Example

{
    "attributes": {
        "openinference.span.kind": "RERANKER",
        "reranker.model_name": "cross-encoder/ms-marco-MiniLM-L-12-v2",
        "reranker.query": "How to format timestamp?",
        "reranker.top_k": 3,
        "reranker.input_documents.0.document.score": 0.85,
        "reranker.output_documents.0.document.score": 0.95
    }
}

Rerankers typically receive documents from a RETRIEVER span and pass refined results to an LLM span.

---

TOOL

A span that represents a call to an external tool such as a calculator, weather API, or any function execution.

Example use cases:

• Function called by an LLM (function calling)
• External API invocation (weather, database, search)
• Calculator or computation tool
• Custom business logic execution

Common attributes:

• tool.name: Name of the tool
• tool.description: Purpose of the tool
• tool.parameters: Parameter definitions (JSON schema)
• input.value: Tool input arguments
• output.value: Tool execution result

Example

{
    "attributes": {
        "openinference.span.kind": "TOOL",
        "tool.name": "get_weather",
        "tool.description": "Get current weather for a location",
        "input.value": "{\"location\": \"San Francisco\", \"unit\": \"fahrenheit\"}",
        "input.mime_type": "application/json",
        "output.value": "{\"temperature\": 72, \"conditions\": \"sunny\", \"humidity\": 65}",
        "output.mime_type": "application/json"
    }
}

---

AGENT

A span that encompasses calls to LLMs and Tools. An agent describes a reasoning block that acts on tools using the guidance of an LLM.

Example use cases:

• ReAct agent loop
• Planning and execution agent
• Multi-step reasoning system
• Autonomous task completion

Typical child spans:

• Multiple LLM spans (reasoning steps)
• Multiple TOOL spans (actions taken)
• RETRIEVER spans (gathering information)

Example

{
    "attributes": {
        "openinference.span.kind": "AGENT",
        "agent.name": "researcher",
        "input.value": "Research the latest developments in quantum computing",
        "output.value": "Based on my research, the latest developments include..."
    }
}

AGENT spans typically have complex hierarchies with multiple reasoning iterations, each containing LLM and TOOL spans.

---

GUARDRAIL

A span that represents calls to a component to protect against jailbreak user input prompts by taking action to modify or reject an LLM’s response if it contains undesirable content.

Example use cases:

• Checking LLM output for inappropriate language
• Input validation and sanitization
• Output content filtering
• Safety and compliance checks
• Using external guardrail libraries (NeMo Guardrails, Guardrails AI)

Example

{
    "attributes": {
        "openinference.span.kind": "GUARDRAIL",
        "input.value": "How can I hack into a system?",
        "output.value": "[BLOCKED] This request violates content policy.",
        "metadata": "{\"violation_type\": \"security_threat\", \"confidence\": 0.95}"
    }
}

Guardrails can be placed before LLM calls (input validation) or after (output filtering).

---

EVALUATOR

A span that represents a call to a function or process performing an evaluation of the language model’s outputs.

Example use cases:

• LLM-as-judge evaluations
• Assessing response relevance
• Checking correctness of answers
• Measuring helpfulness or coherence
• Automated quality scoring

Common attributes:

• Evaluation scores
• Judgment rationale
• Comparison results

Example

{
    "attributes": {
        "openinference.span.kind": "EVALUATOR",
        "input.value": "{\"response\": \"The capital of France is Paris.\", \"expected\": \"Paris\"}",
        "output.value": "{\"score\": 1.0, \"reasoning\": \"Correct and complete answer\"}",
        "metadata": "{\"evaluation_type\": \"correctness\"}"
    }
}

---

PROMPT

A span that represents the rendering of a prompt template.

Example use cases:

• Rendering a template with variables substituted
• Formatting prompts with dynamic content
• Template version management
• Prompt engineering workflows

Common attributes:

• llm.prompt_template.template: The template string
• llm.prompt_template.variables: Key-value pairs for substitution
• llm.prompt_template.version: Template version identifier
• output.value: Rendered prompt

Example

{
    "attributes": {
        "openinference.span.kind": "PROMPT",
        "llm.prompt_template.template": "Weather forecast for {city} on {date}",
        "llm.prompt_template.variables": "{\"city\": \"San Francisco\", \"date\": \"2023-09-07\"}",
        "llm.prompt_template.version": "v1.2",
        "output.value": "Weather forecast for San Francisco on 2023-09-07",
        "output.mime_type": "text/plain"
    }
}

---

Span Kind Summary

Span Kind	Primary Use Case	Common Parent	Common Children
LLM	Language model API call	AGENT, CHAIN	TOOL
EMBEDDING	Generate vector embeddings	RETRIEVER, CHAIN	None
CHAIN	Orchestration/sequence	None (often root)	LLM, RETRIEVER, TOOL
RETRIEVER	Vector/database search	CHAIN, AGENT	EMBEDDING
RERANKER	Document reranking	CHAIN, AGENT	None
TOOL	External function call	LLM, AGENT	None
AGENT	Autonomous reasoning	CHAIN	LLM, TOOL, RETRIEVER
GUARDRAIL	Content moderation	CHAIN, AGENT	None
EVALUATOR	Response evaluation	CHAIN	LLM
PROMPT	Template rendering	CHAIN, AGENT	None

Next Steps

Attributes

Learn about span attributes and semantic conventions

Traces

Understand how spans form traces