SpecificationSemantic Conventions

General

Attributes

Span Conventions

Messages and Content

Feedback

Configuration

Semantic Conventions

The semantic conventions define the keys and values that describe commonly observed concepts and operations in AI applications. They populate the attributes of spans and span events. This page lists every OpenInference attribute, grouped by namespace. All OpenInference tracing SDKs MUST support these attributes. The span conventions say which attributes a span of each kind carries, and Attribute Conventions explains how names, types, and lists are encoded.

Types marked “List of objects” are flattened with zero-based indices, e.g. llm.input_messages.0.message.role.

OpenInference

Attribute Type Description Examples
openinference.span.kind String Required for all OpenInference spans. Identifies the type of operation. See Span Kinds. "LLM", "EMBEDDING", "CHAIN", "RETRIEVER", "RERANKER", "TOOL", "AGENT", "GUARDRAIL", "EVALUATOR", "PROMPT", "DECISION"

Input and Output

Valid on spans of any kind.

Attribute Type Description Examples
input.value String The input value to an operation "{'query': 'What is the weather today?'}"
input.mime_type String MIME type representing the format of input.value "text/plain", "application/json"
input.images List of objects Image inputs to an operation, independent of span kind, e.g. input.images.0.image.url. See Multimodal Content [{"image.url": "https://sample-link-to-image.jpg"}]
input.documents List of objects File document (e.g. PDF) inputs to an operation, independent of span kind, e.g. input.documents.0.document.url. See Multimodal Content [{"document.url": "https://example.com/report.pdf", "document.mime_type": "application/pdf"}]
output.value String The output value of an operation "Hello, World!"
output.mime_type String MIME type representing the format of output.value "text/plain", "application/json"
output.images List of objects Image outputs of an operation, independent of span kind, e.g. output.images.0.image.url. See Multimodal Content [{"image.url": "data:image/png;base64,iVBORw0KGgo..."}]
output.documents List of objects File document (e.g. PDF) outputs of an operation, independent of span kind, e.g. output.documents.0.document.url. See Multimodal Content [{"document.url": "https://example.com/filled-form.pdf", "document.mime_type": "application/pdf"}]

Context

Usually set through the instrumentation context API, which attaches them to every span in scope. See Context Attributes.

Attribute Type Description Examples
session.id String Unique identifier for a session "26bcd3d2-cad2-443d-a23c-625e47f3324a"
user.id String Unique identifier for a user "9328ae73-7141-4f45-a044-8e06192aa465"
metadata JSON String Metadata associated with a span "{'author': 'John Doe', 'date': '2023-09-09'}"
tag.tags List of strings List of tags to give the span a category ["shopping", "travel"]

LLM

Model Identification

See LLM Spans for how these attributes relate.

Attribute Type Description Examples
llm.system String The AI product as identified by the client or server instrumentation. See well-known values "anthropic", "openai"
llm.provider String The hosting provider of the LLM, e.g. azure. See well-known values "openai", "azure"
llm.model_name String The name of the language model being utilized "gpt-3.5-turbo"
llm.request.model_name String The model requested by the caller, as sent in the request. May differ from llm.response.model_name when the provider routes the request to a different model. "claude-opus-5"
llm.response.model_name String The model that actually generated the response, as reported by the provider. May differ from llm.request.model_name when the provider routes the request to a different model. "claude-opus-4-8"

Invocation

Attribute Type Description Examples
llm.invocation_parameters JSON String Parameters used during the invocation of an LLM or API "{model_name: 'gpt-3', temperature: 0.7}"
llm.finish_reason String The reason the model stopped generating tokens. "stop", "length"
llm.function_call JSON String Deprecated: use message.tool_calls. Object recording details of a function call in models or APIs "{function_name: 'add', args: [1, 2]}"

Messages, Prompts, and Tools

Attribute Type Description Examples
llm.input_messages List of objects List of messages sent to the LLM in a chat API request, e.g. llm.input_messages.0.message.role. See Messages [{"message.role": "user", "message.content": "hello"}]
llm.output_messages List of objects List of messages received from the LLM in a chat API response, e.g. llm.output_messages.0.message.role. See Messages [{"message.role": "assistant", "message.content": "hello"}]
llm.prompts List of objects Prompts provided to a completions API, e.g. llm.prompts.0.prompt.text [{"prompt.text": "def fib(n):..."}]
llm.choices List of objects Text choices returned from a completions API, e.g. llm.choices.0.completion.text [{"completion.text": " + fib(n-3)..."}]
llm.tools List of objects List of tools that are advertised to the LLM to be able to call, e.g. llm.tools.0.tool.name, llm.tools.0.tool.description, llm.tools.0.tool.json_schema. See Tool Calling [{"tool.name": "get_weather", "tool.json_schema": "{\"type\": \"function\", \"function\": {\"name\": \"get_weather\"}}"}]

Prompt Template

Attribute Type Description Examples
llm.prompt_template.template String Template used to generate prompts (e.g., using {variable} placeholder syntax) "Weather forecast for {city} on {date}"
llm.prompt_template.variables JSON String JSON of key value pairs applied to the prompt template { context: "<context from retrieval>", subject: "math" }
llm.prompt_template.version String The version of the prompt template "v1.0"

Token Counts

All token counts are integers. The *_details.* values are sub-counts of their parent count; see LLM Spans.

Attribute Type Description Examples
llm.token_count.prompt Integer The number of tokens in the prompt 10
llm.token_count.prompt_details.audio Integer The number of audio input tokens presented in the prompt 10
llm.token_count.prompt_details.cache_input Integer The number of input tokens in the prompt that were cached 5
llm.token_count.prompt_details.cache_read Integer The number of prompt tokens successfully retrieved from cache (cache hits). Maps to cached_tokens in OpenAI responses 5
llm.token_count.prompt_details.cache_write Integer The number of prompt tokens not found in cache that were written to cache (cache misses). Maps to cache_write_tokens in OpenAI responses 0
llm.token_count.completion Integer The number of tokens in the completion 15
llm.token_count.completion_details.audio Integer The number of audio tokens generated by the model 10
llm.token_count.completion_details.reasoning Integer The number of tokens used for model reasoning 10
llm.token_count.total Integer Total number of tokens, including prompt and completion 20

Cost

All costs are floating point values in USD. See LLM Spans.

Attribute Type Description Examples
llm.cost.prompt Float Total cost of all input tokens sent to the LLM in USD 0.0021
llm.cost.prompt_details.input Float Total cost of input tokens in USD 0.0003
llm.cost.prompt_details.audio Float Cost of audio tokens in the prompt in USD 0.0003
llm.cost.prompt_details.cache_input Float Cost of input tokens in the prompt that were cached in USD 0.0006
llm.cost.prompt_details.cache_read Float Cost of prompt tokens read from cache in USD 0.0003
llm.cost.prompt_details.cache_write Float Cost of prompt tokens written to cache in USD 0.0006
llm.cost.completion Float Total cost of all output tokens generated by the LLM in USD 0.0045
llm.cost.completion_details.output Float Total cost of output tokens in USD 0.0009
llm.cost.completion_details.reasoning Float Cost of reasoning steps in the completion in USD 0.0024
llm.cost.completion_details.audio Float Cost of audio tokens in the completion in USD 0.0012
llm.cost.total Float Total cost of the LLM call in USD (prompt + completion) 0.0066

LLM System Values

Well-known values for llm.system:

Value Description
anthropic Anthropic
openai OpenAI
vertexai Vertex AI
cohere Cohere
mistralai Mistral AI
xai xAI (Grok)
deepseek DeepSeek
amazon Amazon Bedrock native
meta Meta (Llama)
ai21 AI21 Labs
typesafe TypeSafe AI

LLM Provider Values

Well-known values for llm.provider:

Value Description
anthropic Anthropic
openai OpenAI
cohere Cohere
mistralai Mistral AI
azure Azure
google Google (Vertex)
aws AWS Bedrock
xai xAI
deepseek DeepSeek
groq Groq
fireworks Fireworks AI
moonshot Moonshot AI
cerebras Cerebras
perplexity Perplexity
together Together AI
ollama Ollama
meta Meta AI
zai Z.ai (GLM)
minimax MiniMax
typesafe TypeSafe AI
oracle Oracle (OCI Generative AI)
ibm IBM (watsonx.ai)
doubleword Doubleword

Message

Items of llm.input_messages and llm.output_messages. See Messages.

Attribute Type Description Examples
message.role String Role of the entity in a message (e.g., user, system) "user", "system"
message.content String The content of a message in a chat "What's the weather today?"
message.contents List of objects The message contents to the LLM, an array of message_content objects. Use this form when a message has multiple content items or when item ordering matters. [{"message_content.type": "text", "message_content.text": "Hello"}]
message.name String The name of the function or tool that produced a tool/function role message. Used when message.role is "tool" or "function" to identify the origin. "multiply"
message.tool_calls List of objects List of tool calls (e.g. function calls) generated by the LLM, e.g. llm.output_messages.0.message.tool_calls.0.tool_call.id [{"tool_call.function.name": "get_current_weather"}]
message.tool_call_id String Tool call result identifier corresponding to tool_call.id "call_62136355"
message.function_call_name String Deprecated: use message.tool_calls. Function call function name "multiply"
message.function_call_arguments_json JSON String Deprecated: use message.tool_calls. The arguments to the function call in JSON "{ 'x': 2 }"

Message Content

Items of message.contents. See Multimodal Content and Reasoning Content.

Attribute Type Description Examples
message_content.type String The type of the content. Use "reasoning" for reasoning/thinking content, including Anthropic redacted_thinking blocks. Use "tool_use" when a provider returns a tool call as an ordered content part. "text", "image", "audio", "video", "document", "reasoning", "tool_use"
message_content.text String The text content of the message. Used when message_content.type is "text" or "reasoning" (visible reasoning or summary text). For OpenAI summary_text arrays, concatenate the array items into this single text value for now. "This is a sample text"
message_content.image Image Object The image content of the message, if the type is "image". {"image.url": "https://sample-link-to-image.jpg"}
message_content.audio Audio Object The audio content of the message, if the type is "audio". Nested leaves are audio.url and audio.transcript. {"audio.url": "https://example.com/audio.mp3"}
message_content.video Video Object The video content of the message, if the type is "video". The nested leaf is video.url. Consumers infer MIME type from the URL path extension or a data URI prefix. {"video.url": "gs://bucket/clip.mp4"}
message_content.document Document Object The document content of the message (e.g. a PDF, an uploaded file, or inline text), if the type is "document". Nested leaves are document.url, document.content, document.mime_type, document.id, and document.name. {"document.url": "data:application/pdf;base64,JVBERi0...", "document.mime_type": "application/pdf"}
message_content.id String Provider-assigned identifier for this message content item. For OpenAI Responses reasoning items, this maps to ResponseReasoningItem.id and should be preserved for stateless replay. "rs_abc123"
message_content.signature String Opaque vendor-issued signature captured verbatim. Maps to provider signature fields, and to Gemini thoughtSignature fields when the signature is attached to a non-tool content part such as text. "EuYBCkQYAiJA..."
message_content.data String Opaque vendor-issued data captured verbatim. Maps to Anthropic redacted_thinking.data. "EmwKAhgBEgy3..."
message_content.encrypted_content String OpenAI encrypted_content captured verbatim. "gAAAAA...=="

Prompt

Attribute Type Description Examples
prompt.text String The text of a prompt in a completions API request. Used under llm.prompts. "def fib(n):..."
prompt.vendor String The vendor or origin of the prompt, e.g. langsmith, portkey, arize-phoenix "langchain"
prompt.id String A vendor-specific id used to identify the prompt. "1234"
prompt.url String A vendor-specific URL used to locate the prompt via the web "https://smith.langchain.com/prompts/naive-prompt"

Completion

Attribute Type Description Examples
completion.text String The text of a choice returned from a completions API. Used under llm.choices. " + fib(n-3)..."

Tool

On a TOOL span, these attributes describe the tool being invoked; under llm.tools.<index>, an advertised tool definition. See Tool Calling.

Attribute Type Description Examples
tool.name String The name of the tool. On a TOOL span, the tool being invoked; under llm.tools.<index>, the name of an advertised tool definition "WeatherAPI"
tool.description String Description of the tool’s purpose and functionality. On a TOOL span, the tool being invoked; under llm.tools.<index>, an advertised tool definition "An API to get weather data."
tool.json_schema JSON String The JSON schema of a tool input "{'type': 'function', 'function': {'name': 'get_weather'}}"
tool.parameters JSON String The parameters definition for invoking the tool "{ 'a': 'int' }"
tool.id String The identifier for the result of the tool call (corresponding to tool_call.id) "call_62136355"

Tool Call

Items of message.tool_calls, and of message.contents when message_content.type is "tool_use". See Tool Calling.

Attribute Type Description Examples
tool_call.id String The id of a tool call (useful when there is more than one call at the same time) "call_62136355"
tool_call.function.name String The name of the function being invoked by a tool call "get_current_weather"
tool_call.function.arguments JSON String The arguments for the function being invoked by a tool call "{'city': 'London'}"
tool_call.reasoning_signature String Opaque vendor-issued reasoning echo token attached to a tool call. Used by Gemini, which puts thoughtSignature on functionCall parts rather than on the reasoning summary. "CiQB..."

Image

Composed under message_content.image and <input|output>.images. See Multimodal Content.

Attribute Type Description Examples
image.url String The link to the image or its base64 encoding "https://sample-link-to-image.jpg"

Audio

Composed under message_content.audio. See Multimodal Content.

Attribute Type Description Examples
audio.url String The URL of an audio file (e.g. cloud storage), or a base64 data URI "https://storage.com/buckets/1/file.wav"
audio.transcript String The transcript of the audio file (e.g. a Whisper transcription) "Hello, how are you?"
audio.mime_type String Legacy. Infer the type from audio.url instead; new instrumentors should not emit this. "audio/mpeg"

Video

Composed under message_content.video. See Multimodal Content.

Attribute Type Description Examples
video.url String The URL, object-store URI, or base64 data URI of a video. Consumers infer MIME type from the path extension (.mp4 to video/mp4, .webm to video/webm, .ogv to video/ogg, .avi to video/x-msvideo) or from a data URI prefix. "gs://bucket/clip.mp4"

Document

Items of retrieval.documents, reranker.input_documents, reranker.output_documents, and <input|output>.documents, and the leaves of message_content.document. See Document Content.

Attribute Type Description Examples
document.id String/Integer Unique identifier for a document: a retrieved document or chunk in a retrieval system, or the provider file id (e.g. an OpenAI or Anthropic Files API id) for a document passed to a model "1234", 1, "file-abc123"
document.content String The text content of a document: a retrieved passage, or an inline text document passed to a model (e.g. an Anthropic text source) "This is a sample document content."
document.score Float Score representing the relevance of a document 0.98
document.metadata JSON String Metadata associated with a document "{'author': 'John Doe', 'date': '2023-09-09'}"
document.url String The URL, object-store URI, or base64 data URI of a file document such as a PDF "https://example.com/report.pdf"
document.mime_type String The MIME type of a file document such as a PDF "application/pdf"
document.name String The name supplied with a document, copied verbatim: a file name (OpenAI filename) or a title (Anthropic title, Bedrock name, Gemini display_name); not a unique identifier "invoice.pdf"

Retrieval

Attribute Type Description Examples
retrieval.documents List of objects List of retrieved documents [{"document.id": "1", "document.score": 0.9, "document.content": "..."}]

Reranker

Attribute Type Description Examples
reranker.query String Query parameter of the reranker "How to format timestamp?"
reranker.model_name String Model name of the reranker "cross-encoder/ms-marco-MiniLM-L-12-v2"
reranker.top_k Integer Top K parameter of the reranker 3
reranker.input_documents List of objects List of documents as input to the reranker [{"document.id": "1", "document.score": 0.9, "document.content": "..."}]
reranker.output_documents List of objects List of documents outputted by the reranker [{"document.id": "1", "document.score": 0.9, "document.content": "..."}]

Embedding

See Embedding Spans.

Attribute Type Description Examples
embedding.model_name String Name of the embedding model used "BERT-base"
embedding.invocation_parameters JSON String Parameters used during the invocation of an embedding model or API (excluding input) "{\"model\": \"text-embedding-3-small\", \"encoding_format\": \"float\"}"
embedding.embeddings List of objects List of embedding objects including text and vector data [{"embedding.vector": [...], "embedding.text": "hello"}]
embedding.text String The text represented in the embedding "hello world"
embedding.vector List of floats The embedding vector consisting of a list of floats [0.123, 0.456, ...]

Decision

See Decision Spans.

Attribute Type Description Examples
decision.system String The decision API ecosystem the call conforms to, i.e. which request/response shape the client speaks, as identified by the client or server instrumentation: typesafe for the TypeSafe System One / Jev API, openai for the OpenAI Decisions API. A self-hosted vLLM server answering the Jev-compatible /v1/systemone shape is still typesafe. Distinct from decision.provider, which says who hosts the model. See the well-known values, which alias the matching llm.system values. "typesafe"
decision.provider String The hosting provider of the decision model: who runs the hardware that answered, e.g. typesafe when calling TypeSafe directly, openai for the OpenAI Decisions API, or the cloud or self-hosting provider for a model served elsewhere. Distinct from decision.system, which names the API shape. See the well-known values, which alias the matching llm.provider values. "typesafe"
decision.model_name String The name of the decision model being utilized. Mirrors llm.model_name for DECISION spans. "jev-1.13.0"
decision.request.model_name String The decision model requested by the caller, as sent in the request. May differ from decision.response.model_name when the provider resolves an alias or routes the request. "jev-latest"
decision.response.model_name String The decision model that actually produced the response, as reported by the provider. May differ from decision.request.model_name. "jev-1.13.0"
decision.token_count.input Integer The number of input tokens consumed by a decision model call: the state, questions, and candidate options. Maps to usage.input_tokens in TypeSafe System One responses. 412
decision.token_count.output Integer The number of output tokens produced by a decision model call. Decision models emit typed answers rather than text, so this is typically small. Maps to usage.output_tokens in TypeSafe System One responses. 2

Decision System and Provider Values

decision.system and decision.provider draw from the same identifier space as llm.system and llm.provider: the same string names the same vendor in both attribute families, and the semantic convention packages expose the decision values as aliases of the matching LLM values (for example OpenInferenceDecisionSystemValues.TYPESAFE is OpenInferenceLLMSystemValues.TYPESAFE). The decision lists are the subset of vendors currently known to offer a decision API. They are well-known values.

decision.system:

Value Description
typesafe TypeSafe AI System One / Jev API, including Jev-compatible servers such as vLLM’s /v1/systemone
openai OpenAI Decisions API

decision.provider:

Value Description
typesafe TypeSafe AI
openai OpenAI

vLLM’s native /v1/decisions API (RFC) does not yet have a well-known value; a custom value MAY be used until it is added.

Agent

Attribute Type Description Examples
agent.name String The name of the agent that this span represents. "researcher"

Graph

Attribute Type Description Examples
graph.node.id String The id of the node in the execution graph. This along with graph.node.parent_id are used to visualize the execution graph. "search_api_0"
graph.node.name String The name of the node in the execution graph. Use this to present a human readable name for the node. Optional "Search API"
graph.node.parent_id String 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. "router_0"

Annotation and Evaluation

Feedback from human, LLM, and code judges. The annotation.* and evaluation.* forms are equivalent; see Annotations and Evaluations.

Feedback Lists

Attribute Type Description Examples
annotations List of objects Span-scoped feedback using annotation terminology, flattened as annotations.0.annotation.* [{"annotation.name": "hallucination", "annotation.label": "hallucinated"}]
trace.annotations List of objects Trace-scoped feedback using annotation terminology, flattened as trace.annotations.0.annotation.* [{"annotation.name": "retrieval_quality", "annotation.score": 0.92}]
session.annotations List of objects Session-scoped feedback using annotation terminology, flattened as session.annotations.0.annotation.*; requires session.id [{"annotation.name": "conversational_coherence", "annotation.label": "coherent"}]
evaluations List of objects Span-scoped feedback using evaluation or eval terminology, flattened as evaluations.0.evaluation.* [{"evaluation.name": "relevance", "evaluation.score": 0.95}]
trace.evaluations List of objects Trace-scoped feedback using evaluation terminology, flattened as trace.evaluations.0.evaluation.* [{"evaluation.name": "retrieval_quality", "evaluation.score": 0.92}]
session.evaluations List of objects Session-scoped feedback using evaluation terminology, flattened as session.evaluations.0.evaluation.*; requires session.id [{"evaluation.name": "conversational_coherence", "evaluation.label": "coherent"}]

Result Fields

Each item carries these fields, under annotation.* or evaluation.*.

Attribute Type Description Examples
annotation.name, evaluation.name String Criterion or metric name "hallucination", "relevance"
annotation.score, evaluation.score Integer/Float Numeric result 1, 0.95
annotation.label, evaluation.label String Categorical result "hallucinated", "relevant"
annotation.explanation, evaluation.explanation String Reason or evidence for the result "The claim is not supported by the context."
annotation.annotator_kind, evaluation.annotator_kind String Judge kind: HUMAN, LLM, CODE, or custom. See Annotator Kinds "LLM", "HUMAN"
annotation.identifier, evaluation.identifier String Stable result ID for the same name and target "judge-v2", "reviewer-42"
annotation.metadata, evaluation.metadata JSON String Additional result or judge data "{\"evaluator\":\"judge-v2\"}"

Exception

These attributes are defined by OpenTelemetry’s exception semantic conventions and recorded on an exception span event.

Attribute Type Description Examples
exception.type String The type of exception that was thrown "NullPointerException"
exception.message String Detailed message describing the exception "Null value encountered"
exception.stacktrace String The stack trace of the exception "at app.main(app.java:16)"
exception.escaped Boolean Indicator if the exception has escaped the span’s scope true