Skip to main content
The openinference-semantic-conventions package defines standardized attributes for tracing AI/ML applications using OpenTelemetry.

​
Installation

pip install openinference-semantic-conventions

​
SpanAttributes

The SpanAttributes class contains attribute keys for annotating spans with metadata about LLM calls, embeddings, retrievals, and more.

​
Import

from openinference.semconv.trace import SpanAttributes

​
Core Attributes

SpanAttributes.INPUT_VALUE = "input.value"
SpanAttributes.INPUT_MIME_TYPE = "input.mime_type"
SpanAttributes.OUTPUT_VALUE = "output.value"
SpanAttributes.OUTPUT_MIME_TYPE = "output.mime_type"

​
LLM Attributes

Attributes specific to Large Language Model operations: 
SpanAttributes.LLM_MODEL_NAME = "llm.model_name"
SpanAttributes.LLM_PROVIDER = "llm.provider"
SpanAttributes.LLM_SYSTEM = "llm.system"

​
Embedding Attributes

SpanAttributes.EMBEDDING_EMBEDDINGS = "embedding.embeddings"
SpanAttributes.EMBEDDING_MODEL_NAME = "embedding.model_name"
SpanAttributes.EMBEDDING_INVOCATION_PARAMETERS = "embedding.invocation_parameters"

​
Retrieval Attributes

SpanAttributes.RETRIEVAL_DOCUMENTS = "retrieval.documents"

​
Tool Attributes

SpanAttributes.TOOL_NAME = "tool.name"
SpanAttributes.TOOL_DESCRIPTION = "tool.description"
SpanAttributes.TOOL_PARAMETERS = "tool.parameters"

​
OpenInferenceSpanKindValues

The OpenInferenceSpanKindValues enum defines the types of operations in an AI application: 
from openinference.semconv.trace import OpenInferenceSpanKindValues

class OpenInferenceSpanKindValues(Enum):
    CHAIN = "CHAIN"           # Sequence of operations
    AGENT = "AGENT"           # Autonomous agent
    LLM = "LLM"               # Language model call
    RETRIEVER = "RETRIEVER"   # Document retrieval
    EMBEDDING = "EMBEDDING"   # Embedding generation
    TOOL = "TOOL"             # Tool execution
    RERANKER = "RERANKER"     # Document reranking
    GUARDRAIL = "GUARDRAIL"   # Safety/validation
    EVALUATOR = "EVALUATOR"   # Evaluation/scoring
    PROMPT = "PROMPT"         # Prompt formatting
    UNKNOWN = "UNKNOWN"       # Unknown operation

​
Usage Example

from openinference.semconv.trace import SpanAttributes, OpenInferenceSpanKindValues

# Set span kind
span.set_attribute(
    SpanAttributes.OPENINFERENCE_SPAN_KIND,
    OpenInferenceSpanKindValues.LLM.value
)

# Set model information
span.set_attribute(SpanAttributes.LLM_MODEL_NAME, "gpt-4")
span.set_attribute(SpanAttributes.LLM_PROVIDER, "openai")

# Set session and user
span.set_attribute(SpanAttributes.SESSION_ID, "session-123")
span.set_attribute(SpanAttributes.USER_ID, "user-456")

​
Message Attributes

For detailed message content: 
from openinference.semconv.trace import MessageAttributes

MessageAttributes.MESSAGE_ROLE = "message.role"
MessageAttributes.MESSAGE_CONTENT = "message.content"
MessageAttributes.MESSAGE_TOOL_CALLS = "message.tool_calls"
MessageAttributes.MESSAGE_FUNCTION_CALL_NAME = "message.function_call_name"

​
Document Attributes

For retrieval results: 
from openinference.semconv.trace import DocumentAttributes

DocumentAttributes.DOCUMENT_ID = "document.id"
DocumentAttributes.DOCUMENT_SCORE = "document.score"
DocumentAttributes.DOCUMENT_CONTENT = "document.content"
DocumentAttributes.DOCUMENT_METADATA = "document.metadata"

​
Additional Attribute Classes

  • MessageContentAttributes - Multi-modal message content (text, images)
  • ImageAttributes - Image URLs and data
  • AudioAttributes - Audio files and transcripts
  • EmbeddingAttributes - Individual embedding vectors
  • RerankerAttributes - Reranker inputs/outputs
  • ToolCallAttributes - Function call details
  • PromptAttributes - Completion API prompts
  • ChoiceAttributes - Completion API choices
See the full source code for complete attribute definitions.

Build docs developers (and LLMs) love

Get started for freeTalk to us