Registry /
observability / opentelemetry-semantic-conventions-ai
Install & Compatibility
Where this runs
tested against v0.5.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 22MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.1s · import 0.000s · 22MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
SpanAttributes
✓ from opentelemetry.semantic_conventions.ai import SpanAttributes
✗ from opentelemetry.semantic_conventions.ai import SpanAttributes
This quickstart demonstrates how to set up a basic OpenTelemetry tracer and apply AI semantic conventions to a span, simulating an LLM chat completion. It uses `SpanAttributes` and `LLMRequestTypeValues` to standardize observability data for AI interactions, exporting the span to the console.
import os
from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor
from opentelemetry.semconv.ai import SpanAttributes, LLMRequestTypeValues
# Configure OpenTelemetry SDK
resource = Resource.create(
{
"service.name": os.environ.get("OTEL_SERVICE_NAME", "my-llm-app"),
"service.instance.id": "instance-1",
}
)
provider = TracerProvider(resource=resource)
# For demonstration, export spans to console
provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))
trace.set_tracer_provider(provider)
# Get a tracer
tracer = trace.get_tracer(__name__)
# Simulate an LLM API call and add semantic conventions
with tracer.start_as_current_span("llm.chat.completion") as span:
span.set_attribute(SpanAttributes.LLM_VENDOR, "OpenAI")
span.set_attribute(SpanAttributes.LLM_MODEL_NAME, "gpt-4")
span.set_attribute(SpanAttributes.LLM_REQUEST_TYPE, LLMRequestTypeValues.CHAT.value)
span.set_attribute(SpanAttributes.LLM_PROMPT_MESSAGES,
[{'role': 'system', 'content': 'You are a helpful assistant.'},
{'role': 'user', 'content': 'Tell me a joke.'}])
span.set_attribute(SpanAttributes.LLM_RESPONSE_MODEL, "gpt-4-0613")
span.set_attribute(SpanAttributes.LLM_COMPLETIONS,
[{'role': 'assistant', 'content': 'Why did the scarecrow win an award? Because he was outstanding in his field!'}])
span.set_attribute(SpanAttributes.LLM_USAGE_TOTAL_TOKENS, 50)
print("Span with AI semantic conventions created and exported to console.")
Debug
Known issues
breakingVersion 0.5.0 introduced a significant restructure, moving away from providing instrumentation utilities (like `langchain_monitor`). This library now solely provides semantic convention constants. If you previously used `opentelemetry.instrumentation.*` modules from this package, they are removed.fixUpdate imports to use `opentelemetry.semconv.ai.*` for constants. If instrumentation is needed, look for dedicated instrumentation packages (e.g., `opentelemetry-instrumentation-langchain`).
affects: >=0.5.0
gotchaThe semantic conventions are strict. Using incorrect attribute names, data types, or values for attributes will not typically raise an error but will result in non-compliant traces that may not be correctly interpreted by observability tools.fixAlways refer to the official OpenTelemetry AI semantic conventions documentation for precise attribute names, types, and allowed values. Ensure complex attributes like `LLM_PROMPT_MESSAGES` are formatted as JSON-serializable lists of dictionaries.
affects: All versions
gotchaAs a `0.x.x` version library, the underlying semantic conventions for AI are still evolving. This means attribute names, values, or structures might change in future minor versions, potentially requiring updates to your code.fixStay informed about release notes and the official OpenTelemetry AI semantic conventions specification. Plan for potential minor adjustments when upgrading to new minor versions of this library.
affects: All 0.x.x versions
Upgrade
Version history
0.5.1latest on PyPI · released Mar 26, 2026
Audit
Dependencies
opentelemetry-apirequiredRequired for basic OpenTelemetry API interactions (e.g., obtaining a Tracer).
opentelemetry-sdkrequiredRequired for OpenTelemetry SDK functionalities (e.g., configuring TracerProvider, SpanProcessors).