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.| Span Kind | Description |
|---|---|
| LLM | Call to an LLM for a completion or chat |
| Tool | API or function invoked on behalf of an LLM |
| Agent | Root span which contains a set of LLM and tool invocations |
| Retriever | Data retrieval query for context from a datastore |
| Chain | The starting point and link between application steps |
| Embedding | Encoding of unstructured data |
| Guardrail | Validates LLM inputs/outputs for safety and compliance |
| Reranker | Relevance based re-ordering of documents |
| Evaluator | Evaluation process, type, and results |
| Unknown | 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| Code | Description |
|---|---|
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
| Code | Description |
|---|---|
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
| Code | Description |
|---|---|
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
| Code | Description |
|---|---|
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
| Code | Description |
|---|---|
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
| Code | Description |
|---|---|
OPENINFERENCE_SPAN_KIND = "CHAIN" | Define the span kind: Chain |
Embedding Span
| Code | Description |
|---|---|
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
| Code | Description |
|---|---|
OPENINFERENCE_SPAN_KIND = "GUARDRAIL" | Define the span kind: Guardrail |
Reranker Span
| Code | Description |
|---|---|
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
| Code | Description |
|---|---|
OPENINFERENCE_SPAN_KIND = "EVALUATOR" | Define the span kind: Evaluator |