Span Kinds

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

LLM

EMBEDDING

CHAIN

RETRIEVER

RERANKER

TOOL

AGENT

GUARDRAIL

EVALUATOR

PROMPT

Span Kind Summary

Next Steps

Attributes

Traces

Documentation Index

​LLM

​EMBEDDING

​CHAIN

​RETRIEVER

​RERANKER

​TOOL

​AGENT

​GUARDRAIL

​EVALUATOR

​PROMPT

​Span Kind Summary

​Next Steps

Attributes

Traces

LLM

EMBEDDING

CHAIN

RETRIEVER

RERANKER

TOOL

AGENT

GUARDRAIL

EVALUATOR

PROMPT

Span Kind Summary

Next Steps