Python APIopeninference-semantic-conventions

Core

Instrumentation

Python · Core

openinference-semantic-conventions

OpenInference Semantic Conventions

Module
openinference.semconv
Version
0.1.46
Python
>=3.10, <3.16

Install

pip install openinference-semantic-conventions

openinference.semconv.resource

ResourceAttributes

classSource ↗
class ResourceAttributes

Attributes

NameType and value
PROJECT_NAME'openinference.project.name'

openinference.semconv.trace

SpanAttributes

classSource ↗
class SpanAttributes

Attributes

NameType and value
ANNOTATIONS'annotations'

Feedback using annotation terminology.

EVALUATIONS'evaluations'

Feedback using evaluation or eval terminology.

TRACE_ANNOTATIONS'trace.annotations'

Trace-scoped feedback using annotation terminology.

TRACE_EVALUATIONS'trace.evaluations'

Trace-scoped feedback using evaluation or eval terminology.

SESSION_ANNOTATIONS'session.annotations'

Session-scoped feedback using annotation terminology.

SESSION_EVALUATIONS'session.evaluations'

Session-scoped feedback using evaluation or eval terminology.

OUTPUT_VALUE'output.value'
OUTPUT_MIME_TYPE'output.mime_type'

The type of output.value. If unspecified, the type is plain text by default. If type is JSON, the value is a string representing a JSON object.

INPUT_VALUE'input.value'
INPUT_MIME_TYPE'input.mime_type'

The type of input.value. If unspecified, the type is plain text by default. If type is JSON, the value is a string representing a JSON object.

INPUT_IMAGES'input.images'

A list of Image Objects that are inputs to an operation, independent of span kind. Flattened with indexed prefixes, e.g. input.images.0.image.url.

OUTPUT_IMAGES'output.images'

A list of Image Objects produced by an operation, independent of span kind. Flattened with indexed prefixes, e.g. output.images.0.image.url.

INPUT_DOCUMENTS'input.documents'

A list of Document Objects (e.g. PDFs) that are inputs to an operation, independent of span kind. Flattened with indexed prefixes, e.g. input.documents.0.document.url.

OUTPUT_DOCUMENTS'output.documents'

A list of Document Objects (e.g. PDFs) produced by an operation, independent of span kind. Flattened with indexed prefixes, e.g. output.documents.0.document.url.

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.

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_INVOCATION_PARAMETERS'llm.invocation_parameters'

Invocation parameters passed to the LLM or API, such as the model name, temperature, etc.

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_MODEL_NAME'llm.model_name'

The name of the model being used.

LLM_REQUEST_MODEL_NAME'llm.request.model_name'

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 (e.g. classifier-triggered fallback).

LLM_RESPONSE_MODEL_NAME'llm.response.model_name'

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 (e.g. classifier-triggered fallback).

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

DECISION_MODEL_NAME'decision.model_name'

The name of the decision model being used. Mirrors llm.model_name for DECISION spans. A decision model takes state plus typed questions and returns a typed, probabilistic answer per question instead of generated text; see https://github.com/Arize-ai/openinference/blob/main/spec/spans/decision.md for the convention and the decision model families it covers.

DECISION_REQUEST_MODEL_NAME'decision.request.model_name'

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 (e.g. jev-latest) or routes the request to a different model.

DECISION_RESPONSE_MODEL_NAME'decision.response.model_name'

The decision model that actually produced the response, as reported by the provider. May differ from decision.request.model_name.

DECISION_PROVIDER'decision.provider'

The hosting provider of the decision model: who runs the hardware that answered (e.g. “typesafe” when calling TypeSafe directly, or the cloud or self-hosting provider for a model served elsewhere). Distinct from decision.system, which names the API shape. Well-known values are OpenInferenceDecisionProviderValues, which alias the matching OpenInferenceLLMProviderValues.

DECISION_SYSTEM'decision.system'

The decision API ecosystem the call conforms to, i.e. which request and response shape the client speaks, as identified by the client or server: “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. Well-known values are OpenInferenceDecisionSystemValues, which alias the matching OpenInferenceLLMSystemValues.

DECISION_TOKEN_COUNT_INPUT'decision.token_count.input'

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.

DECISION_TOKEN_COUNT_OUTPUT'decision.token_count.output'

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.

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_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_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_COMPLETION'llm.token_count.completion'

Number of tokens in the completion (in tokens).

LLM_TOKEN_COUNT_COMPLETION_DETAILS_AUDIO'llm.token_count.completion_details.audio'

The number of audio tokens in the completion (in tokens).

LLM_TOKEN_COUNT_COMPLETION_DETAILS_REASONING'llm.token_count.completion_details.reasoning'

Number of tokens used for reasoning steps in the completion (in tokens).

LLM_TOKEN_COUNT_PROMPT'llm.token_count.prompt'

Number of tokens in the prompt.

LLM_TOKEN_COUNT_PROMPT_DETAILS'llm.token_count.prompt_details'

Key prefix for additional prompt token count details. Each detail should be a separate attribute with this prefix, e.g. llm.token_count.prompt_details.reasoning, llm.token_count.prompt_details.audio. All values should be in tokens.

LLM_TOKEN_COUNT_PROMPT_DETAILS_AUDIO'llm.token_count.prompt_details.audio'

The number of audio tokens in the prompt (in tokens).

LLM_TOKEN_COUNT_PROMPT_DETAILS_CACHE_INPUT'llm.token_count.prompt_details.cache_input'

Number of input tokens in the prompt that were cached (in tokens).

LLM_TOKEN_COUNT_PROMPT_DETAILS_CACHE_READ'llm.token_count.prompt_details.cache_read'

Number of tokens in the prompt that were read from cache (in tokens).

LLM_TOKEN_COUNT_PROMPT_DETAILS_CACHE_WRITE'llm.token_count.prompt_details.cache_write'

Number of tokens in the prompt that were written to cache (in tokens).

LLM_TOKEN_COUNT_TOTAL'llm.token_count.total'

Total number of tokens, including both prompt and completion (in tokens).

LLM_FINISH_REASON'llm.finish_reason'

The reason the model stopped generating tokens, e.g. "stop" or "length".

LLM_COST_COMPLETION'llm.cost.completion'

Total cost of all output tokens generated by the LLM in USD. This includes all tokens that were generated in response to the prompt, including the main response and any additional output.

LLM_COST_COMPLETION_DETAILS'llm.cost.completion_details'

Key prefix for additional completion cost details. Each detail should be a separate attribute with this prefix, e.g. llm.cost.completion_details.reasoning, llm.cost.completion_details.audio. All values should be in USD.

LLM_COST_COMPLETION_DETAILS_AUDIO'llm.cost.completion_details.audio'

Cost of audio tokens in the completion in USD.

LLM_COST_COMPLETION_DETAILS_OUTPUT'llm.cost.completion_details.output'

Total cost of output tokens in USD. This represents the cost of tokens that were generated as output by the model, which may be different from the completion cost if there are additional processing steps.

LLM_COST_COMPLETION_DETAILS_REASONING'llm.cost.completion_details.reasoning'

Cost of reasoning steps in the completion in USD.

LLM_COST_PROMPT'llm.cost.prompt'

Total cost of all input tokens sent to the LLM in USD. This includes all tokens that were processed as part of the prompt, including system messages, user messages, and any other input.

LLM_COST_PROMPT_DETAILS'llm.cost.prompt_details'

Key prefix for additional prompt cost details. Each detail should be a separate attribute with this prefix, e.g. llm.cost.prompt_details.reasoning, llm.cost.prompt_details.audio. All values should be in USD.

LLM_COST_PROMPT_DETAILS_AUDIO'llm.cost.prompt_details.audio'

Cost of audio tokens in the prompt in USD.

LLM_COST_PROMPT_DETAILS_CACHE_INPUT'llm.cost.prompt_details.cache_input'

Cost of input tokens in the prompt that were cached in USD.

LLM_COST_PROMPT_DETAILS_CACHE_READ'llm.cost.prompt_details.cache_read'

Cost of prompt tokens read from cache in USD.

LLM_COST_PROMPT_DETAILS_CACHE_WRITE'llm.cost.prompt_details.cache_write'

Cost of prompt tokens written to cache in USD.

LLM_COST_PROMPT_DETAILS_INPUT'llm.cost.prompt_details.input'

Total cost of input tokens in USD. This represents the cost of tokens that were used as input to the model, which may be different from the prompt cost if there are additional processing steps.

LLM_COST_TOTAL'llm.cost.total'

Total cost of the LLM call in USD (prompt + completion).

LLM_TOOLS'llm.tools'

List of tools that are advertised to the LLM to be able to call

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, e.g. see https://platform.openai.com/docs/guides/gpt/function-calling

TOOL_ID'tool.id'

The identifier for the result of the tool call (corresponding to tool_call.id).

RETRIEVAL_DOCUMENTS'retrieval.documents'
METADATA'metadata'

Metadata attributes are used to store user-defined key-value pairs. For example, LangChain uses metadata to store user-defined attributes for a chain.

TAG_TAGS'tag.tags'

Custom categorical tags for the span.

OPENINFERENCE_SPAN_KIND'openinference.span.kind'
SESSION_ID'session.id'

The id of the session

USER_ID'user.id'

The id of the user

AGENT_NAME'agent.name'

The name of the agent. Agents that perform the same functions should have the same name.

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'

The name of the node in the execution graph. Use this to present a human readable name for the node. Optional

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.

PROMPT_VENDOR'prompt.vendor'

The vendor or origin of the prompt, e.g. a prompt library, a specialized service, etc.

PROMPT_ID'prompt.id'

A vendor-specific id used to locate the prompt.

PROMPT_URL'prompt.url'

A vendor-specific url used to locate the prompt.

AnnotationAttributes

classSource ↗
class AnnotationAttributes

Attributes for feedback about a span.

Attributes

NameType and value
ANNOTATION_NAME'annotation.name'
ANNOTATION_SCORE'annotation.score'
ANNOTATION_LABEL'annotation.label'
ANNOTATION_EXPLANATION'annotation.explanation'
ANNOTATION_ANNOTATOR_KIND'annotation.annotator_kind'
ANNOTATION_IDENTIFIER'annotation.identifier'
ANNOTATION_METADATA'annotation.metadata'

EvaluationAttributes

classSource ↗
class EvaluationAttributes

Attributes for feedback using evaluation or eval terminology.

Attributes

NameType and value
EVALUATION_NAME'evaluation.name'
EVALUATION_SCORE'evaluation.score'
EVALUATION_LABEL'evaluation.label'
EVALUATION_EXPLANATION'evaluation.explanation'
EVALUATION_ANNOTATOR_KIND'evaluation.annotator_kind'
EVALUATION_IDENTIFIER'evaluation.identifier'
EVALUATION_METADATA'evaluation.metadata'

MessageAttributes

classSource ↗
class MessageAttributes

Attributes for a message sent to or from an LLM

Attributes

NameType and value
MESSAGE_ROLE'message.role'

The role of the message, such as “user”, “agent”, “function”.

MESSAGE_CONTENT'message.content'

The content of the message to or from the llm, must be a string.

MESSAGE_CONTENTS'message.contents'

The message contents to the llm, it is an array of message_content prefixed attributes.

MESSAGE_NAME'message.name'

The name of the message, often used to identify the function that was used to generate the message.

MESSAGE_TOOL_CALLS'message.tool_calls'

The tool calls generated by the model, such as function calls.

MESSAGE_FUNCTION_CALL_NAME'message.function_call_name'

The function name that is a part of the message list. This is populated for role ‘function’ or ‘agent’ as a mechanism to identify the function that was called during the execution of a tool.

MESSAGE_FUNCTION_CALL_ARGUMENTS_JSON'message.function_call_arguments_json'

The JSON string representing the arguments passed to the function during a function call.

MESSAGE_TOOL_CALL_ID'message.tool_call_id'

The id of the tool call.

MessageContentAttributes

classSource ↗
class MessageContentAttributes

Attributes for the contents of user messages sent to an LLM.

Attributes

NameType and value
MESSAGE_CONTENT_TYPE'message_content.type'

The type of the content, such as “text”, “image”, “audio”, “video”, “document”, “reasoning”, or “tool_use”.

MESSAGE_CONTENT_TEXT'message_content.text'

The text content of the message, if the type is “text” or “reasoning”.

MESSAGE_CONTENT_IMAGE'message_content.image'

The image content of the message, if the type is “image”. An image can be made available to the model by passing a link to the image or by passing the base64 encoded image directly in the request.

MESSAGE_CONTENT_AUDIO'message_content.audio'

The audio content of the message, if the type is “audio”. Nested leaves come from AudioAttributes.

MESSAGE_CONTENT_VIDEO'message_content.video'

The video content of the message, if the type is “video”. Nested leaves come from VideoAttributes.

MESSAGE_CONTENT_DOCUMENT'message_content.document'

The document content of the message (e.g. a PDF, an uploaded file, or inline text), if the type is “document”. Nested leaves come from DocumentAttributes.

MESSAGE_CONTENT_ID'message_content.id'

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.

MESSAGE_CONTENT_SIGNATURE'message_content.signature'

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.

MESSAGE_CONTENT_DATA'message_content.data'

Opaque vendor-issued data captured verbatim. Maps to Anthropic redacted_thinking.data.

MESSAGE_CONTENT_ENCRYPTED_CONTENT'message_content.encrypted_content'

OpenAI encrypted_content captured verbatim.

ImageAttributes

classSource ↗
class ImageAttributes

Attributes for images

Attributes

NameType and value
IMAGE_URL'image.url'

An http or base64 image url.

AudioAttributes

classSource ↗
class AudioAttributes

Attributes for audio

Attributes

NameType and value
AUDIO_URL'audio.url'

The url to an audio file

AUDIO_MIME_TYPE'audio.mime_type'

The mime type of the audio file

AUDIO_TRANSCRIPT'audio.transcript'

The transcript of the audio file

VideoAttributes

classSource ↗
class VideoAttributes

Attributes for video

Attributes

NameType and value
VIDEO_URL'video.url'

The URL, object-store URI, or base64 data URI of a video.

DocumentAttributes

classSource ↗
class DocumentAttributes

Attributes for a document.

Attributes

NameType and value
DOCUMENT_ID'document.id'

The id of the document: a retrieved document or chunk’s id in a retrieval system, or, for a document passed to a model, the provider’s file id (e.g. an OpenAI or Anthropic Files API id).

DOCUMENT_SCORE'document.score'

The score of the document

DOCUMENT_CONTENT'document.content'

The text content of the document: a retrieved passage, or an inline text document passed to a model.

DOCUMENT_METADATA'document.metadata'

The metadata of the document represented as a dictionary JSON string, e.g. "{ 'title': 'foo' }"

DOCUMENT_URL'document.url'

The URL, object-store URI, or base64 data URI of a file document such as a PDF.

DOCUMENT_MIME_TYPE'document.mime_type'

The MIME type of a document, e.g. application/pdf.

DOCUMENT_NAME'document.name'

The name supplied with a document, such as a file name or a title, e.g. invoice.pdf. Not a unique identifier.

RerankerAttributes

classSource ↗
class RerankerAttributes

Attributes for a reranker

Attributes

NameType and value
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

EmbeddingAttributes

classSource ↗
class EmbeddingAttributes

Attributes for an embedding

Attributes

NameType and value
EMBEDDING_TEXT'embedding.text'

The text represented by the embedding.

EMBEDDING_VECTOR'embedding.vector'

The embedding vector.

ToolCallAttributes

classSource ↗
class ToolCallAttributes

Attributes for a tool call

Attributes

NameType and value
TOOL_CALL_ID'tool_call.id'

The id of the tool call.

TOOL_CALL_FUNCTION_NAME'tool_call.function.name'

The name of function that is being called during a tool call.

TOOL_CALL_FUNCTION_ARGUMENTS_JSON'tool_call.function.arguments'

The JSON string representing the arguments passed to the function during a tool call.

TOOL_CALL_REASONING_SIGNATURE'tool_call.reasoning_signature'

Opaque vendor-issued reasoning echo token attached to a tool call. Maps to Gemini thoughtSignature when it is attached to a functionCall part.

PromptAttributes

classSource ↗
class PromptAttributes

Attributes for a prompt in the completions API

Attributes

NameType and value
PROMPT_TEXT'prompt.text'

The text of the prompt.

ChoiceAttributes

classSource ↗
class ChoiceAttributes

Attributes for a choice in the completions API

Attributes

NameType and value
COMPLETION_TEXT'completion.text'

The text of the completion choice.

ToolAttributes

classSource ↗
class ToolAttributes

Attributes for tools.

Attributes

NameType and value
TOOL_JSON_SCHEMA'tool.json_schema'

The json schema of a tool input, It is RECOMMENDED that this be in the OpenAI tool calling format: https://platform.openai.com/docs/assistants/tools

TOOL_NAME'tool.name'

The name of the tool, i.e. the identifier the model uses to call it.

TOOL_DESCRIPTION'tool.description'

The description of the tool, i.e. the text the model uses to decide whether to call it.

OpenInferenceSpanKindValues

enumSource ↗
class OpenInferenceSpanKindValues(Enum)

Members

NameValue
TOOL'TOOL'
CHAIN'CHAIN'
LLM'LLM'
RETRIEVER'RETRIEVER'
EMBEDDING'EMBEDDING'
AGENT'AGENT'
RERANKER'RERANKER'
UNKNOWN'UNKNOWN'
GUARDRAIL'GUARDRAIL'
EVALUATOR'EVALUATOR'
PROMPT'PROMPT'
DECISION'DECISION'

OpenInferenceAnnotatorKindValues

enumSource ↗
class OpenInferenceAnnotatorKindValues(Enum)

Members

NameValue
HUMAN'HUMAN'
LLM'LLM'
CODE'CODE'

OpenInferenceMimeTypeValues

enumSource ↗
class OpenInferenceMimeTypeValues(Enum)

Members

NameValue
TEXT'text/plain'
JSON'application/json'

OpenInferenceLLMSystemValues

enumSource ↗
class OpenInferenceLLMSystemValues(Enum)

Members

NameValue
OPENAI'openai'
ANTHROPIC'anthropic'
COHERE'cohere'
MISTRALAI'mistralai'
VERTEXAI'vertexai'
TYPESAFE'typesafe'

OpenInferenceLLMProviderValues

enumSource ↗
class OpenInferenceLLMProviderValues(Enum)

Members

NameValue
OPENAI'openai'
ANTHROPIC'anthropic'
COHERE'cohere'
MISTRALAI'mistralai'
GOOGLE'google'
AZURE'azure'
AWS'aws'
XAI'xai'
DEEPSEEK'deepseek'
GROQ'groq'
FIREWORKS'fireworks'
MOONSHOT'moonshot'
CEREBRAS'cerebras'
PERPLEXITY'perplexity'
TOGETHER'together'
OLLAMA'ollama'
META'meta'
ZAI'zai'
MINIMAX'minimax'
ORACLE'oracle'
IBM'ibm'
TYPESAFE'typesafe'
DOUBLEWORD'doubleword'

OpenInferenceDecisionSystemValues

enumSource ↗
class OpenInferenceDecisionSystemValues(Enum)

Well-known values for decision.system: the decision API ecosystem a DECISION span conforms to. Each member aliases the OpenInferenceLLMSystemValues member for the same vendor, so the same string names the same vendor on LLM and DECISION spans. The list is the subset of vendors currently known to offer a decision API.

Members

NameValue
TYPESAFEOpenInferenceLLMSystemValues.TYPESAFE.value

TypeSafe AI System One / Jev API, including Jev-compatible servers.

OPENAIOpenInferenceLLMSystemValues.OPENAI.value

OpenAI Decisions API.

OpenInferenceDecisionProviderValues

enumSource ↗
class OpenInferenceDecisionProviderValues(Enum)

Well-known values for decision.provider: who hosts the decision model that answered. Each member aliases the OpenInferenceLLMProviderValues member for the same vendor.