Spans
Supported Span Kinds and Span Data Format
A span represents a single unit of work, with an input, output, start time, and end time. A trace is composed of multiple spans that together represent the full journey of a request.
Span Kinds
Spans track specific operations such as a retriever, tool call, or LLM step. Each span is assigned a type, known as a span kind, which indicates the role of that operation.
Call to an LLM for a completion or chat
API or function invoked on behalf of an LLM
Root span which contains a set of LLM and tool invocations
Data retrieval query for context from a datastore
The starting point and link between application steps
Encoding of unstructured data
Validates LLM inputs/outputs for safety and compliance
Relevance based re-ordering of documents
Evaluation process, type, and results
This is the unknown
Span Data Format
If you're using auto instrumentation, these will get set up for you automatically!
If you're setting up tracing manually, you'll want to set these:
General Attributes for all Spans:
Here are the general (“for all spans”) reserved attribute keys from the OpenInference Semantic Conventions spec that apply across span kinds. Note: you only need to set ones relevant to your span
OPENINFERENCE_SPAN_KIND = "openinference.span.kind"
The span kind (e.g., “LLM”, “EMBEDDING”, “TOOL”, etc)
INPUT_VALUE = "input.value"
The type of input.value. If unspecified, the type is plain text by default.
INPUT_MIME_TYPE = "input.mime_type"
If type is JSON, the value is a string representing a JSON object.
OUTPUT_VALUE = "output.value"
The type of output.value. If unspecified, the type is plain text by default.
OUTPUT_MIME_TYPE = "output.mime_type"
If type is JSON, the value is a string representing a JSON object.
METADATA = "metadata"
Metadata attributes are used to store user-defined key-value pairs.
TAG_TAGS = "tag.tags"
Custom categorical tags for the span.
SESSION_ID = "session.id"
The id of the session
USER_ID = "user.id"
The id of the user
GRAPH_NODE_ID = "graph.node.id"
The id of the node in the execution graph. This along with graph.node.parent_id are used to visualize the execution graph.
GRAPH_NODE_NAME = "graph.node.name"
Optional: The name of the node in the execution graph. Use this to present a human readable name for the node.
GRAPH_NODE_PARENT_ID = "graph.node.parent_id"
This references the id of the parent node. Leaving this unset or set as empty string implies that the current span is the root node.
LLM Spans
LLM_MODEL_NAME = "llm.model_name"
The name of the model being used.
LLM_PROVIDER = "llm.provider"
The provider of the model, such as OpenAI, Azure, Google, etc.
LLM_SYSTEM = "llm.system"
The AI product as identified by the client or server
LLM_CHOICES = "llm.choices"
Text choices returned from a completions API. Use indexed format with nested structure. Maps to the 'choices' array in the response (e.g., response.choices[0].text). Use format: llm.choices.N.completion.text
LLM_INVOCATION_PARAMETERS = "llm.invocation_parameters"
Invocation parameters passed to the LLM or API, such as the model name, temperature, etc.
LLM_PROMPTS = "llm.prompts"
Prompts provided to a completions API. Use indexed format with nested structure. Maps to the 'prompt' field in the request (e.g., request.prompt or request.prompt[0]). Use format: llm.prompts.N.prompt.text
LLM_INPUT_MESSAGES = "llm.input_messages"
Messages provided to a chat API.
LLM_OUTPUT_MESSAGES = "llm.output_messages"
Messages received from a chat API.
LLM_FUNCTION_CALL = "llm.function_call"
For models and APIs that support function calling. Records attributes such as the function name and arguments to the called function.
LLM_TOOLS = "llm.tools"
List of tools that are advertised to the LLM to be able to call
LLM_PROMPT_TEMPLATE = "llm.prompt_template.template"
The prompt template as a Python f-string.
LLM_PROMPT_TEMPLATE_VARIABLES = "llm.prompt_template.variables"
A list of input variables to the prompt template.
LLM_PROMPT_TEMPLATE_VERSION = "llm.prompt_template.version"
The version of the prompt template being used.
LLM_TOKEN_COUNT_PROMPT = "llm.token_count.prompt"
Number of tokens in the prompt.
LLM_TOKEN_COUNT_COMPLETION = "llm.token_count.completion"
Number of tokens in the completion (in tokens).
LLM_TOKEN_COUNT_TOTAL = "llm.token_count.total"
Total number of tokens, including both prompt and completion (in tokens).
Tool Spans
OPENINFERENCE_SPAN_KIND = "TOOL"
Define the span kind: TOOL
TOOL_NAME = "tool.name"
Name of the tool being used.
TOOL_DESCRIPTION = "tool.description"
Description of the tool's purpose, typically used to select the tool.
TOOL_PARAMETERS = "tool.parameters"
Parameters of the tool represented a dictionary JSON string
Agent Span
OPENINFERENCE_SPAN_KIND = "AGENT"
Define the span kind: AGENT
AGENT_NAME = "agent.name"
The name of the agent. Agents that perform the same functions should have the same name.
Retriever Span
OPENINFERENCE_SPAN_KIND = "RETRIEVER"
Define the span kind: Retriever
RETRIEVAL_DOCUMENTS = "retrieval.documents"
A list attribute for documents retrieved
DOCUMENT_ID = "document.id"
The id of the document.
DOCUMENT_SCORE = "document.score"
The score of the document
DOCUMENT_CONTENT = "document.content"
The content of the document.
DOCUMENT_METADATA = "document.metadata"
The metadata of the document represented as a dictionary JSON string, e.g. "{ 'title': 'foo' }"
Chain Span
OPENINFERENCE_SPAN_KIND = "CHAIN"
Define the span kind: Chain
Embedding Span
OPENINFERENCE_SPAN_KIND = "EMBEDDING"
Define the span kind: Embedding
EMBEDDING_EMBEDDINGS = "embedding.embeddings"
A list of objects containing embedding data, including the vector and represented piece of text.
EMBEDDING_INVOCATION_PARAMETERS = "embedding.invocation_parameters"
Invocation parameters passed to the embedding model or API, such as the model name, encoding format, etc.
EMBEDDING_MODEL_NAME = "embedding.model_name"
The name of the embedding model.
EMBEDDING_TEXT = "embedding.text"
The text represented by the embedding.
EMBEDDING_VECTOR = "embedding.vector"
The embedding vector.
Guardrail Span
OPENINFERENCE_SPAN_KIND = "GUARDRAIL"
Define the span kind: Guardrail
Reranker Span
OPENINFERENCE_SPAN_KIND = "RERANKER"
Define the span kind: Reranker
RERANKER_INPUT_DOCUMENTS = "reranker.input_documents"
List of documents as input to the reranker
RERANKER_OUTPUT_DOCUMENTS = "reranker.output_documents"
List of documents as output from the reranker
RERANKER_QUERY = "reranker.query"
Query string for the reranker
RERANKER_MODEL_NAME = "reranker.model_name"
Model name of the reranker
RERANKER_TOP_K = "reranker.top_k"
Top K parameter of the reranker
Evaluator Span
OPENINFERENCE_SPAN_KIND = "EVALUATOR"
Define the span kind: Evaluator
Unknown Span
These are the default spans; If span kind is not defined, 'Unknown Span' will be applied.
OpenInference Guides
Full Python Guide:
Full TS Guide:
Last updated
Was this helpful?