{"id":1611,"library":"opentelemetry-semantic-conventions-ai","title":"OpenTelemetry Semantic Conventions for AI","description":"This library provides Python constants for OpenTelemetry semantic conventions specifically tailored for AI applications, including Large Language Models (LLMs) and Vector Databases. It defines standardized attribute names and values to ensure consistent and interoperable observability data across various AI services and tools. The current version is 0.5.1, and it maintains an active release cadence, typically releasing updates monthly or bi-monthly as conventions evolve.","status":"active","version":"0.5.1","language":"en","source_language":"en","source_url":"https://github.com/open-telemetry/semantic-conventions-ai-python","tags":["opentelemetry","ai","llm","observability","traces","semantic-conventions","vector-db"],"install":[{"cmd":"pip install opentelemetry-semantic-conventions-ai","lang":"bash","label":"Install core library"}],"dependencies":[{"reason":"Required for basic OpenTelemetry API interactions (e.g., obtaining a Tracer).","package":"opentelemetry-api","optional":false},{"reason":"Required for OpenTelemetry SDK functionalities (e.g., configuring TracerProvider, SpanProcessors).","package":"opentelemetry-sdk","optional":false}],"imports":[{"symbol":"SpanAttributes","correct":"from opentelemetry.semconv.ai import SpanAttributes"},{"symbol":"LLMRequestTypeValues","correct":"from opentelemetry.semconv.ai import LLMRequestTypeValues"},{"symbol":"VectorDBAttributes","correct":"from opentelemetry.semconv.ai import VectorDBAttributes"}],"quickstart":{"code":"import os\nfrom opentelemetry import trace\nfrom opentelemetry.sdk.resources import Resource\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor\nfrom opentelemetry.semconv.ai import SpanAttributes, LLMRequestTypeValues\n\n# Configure OpenTelemetry SDK\nresource = Resource.create(\n    {\n        \"service.name\": os.environ.get(\"OTEL_SERVICE_NAME\", \"my-llm-app\"),\n        \"service.instance.id\": \"instance-1\",\n    }\n)\nprovider = TracerProvider(resource=resource)\n# For demonstration, export spans to console\nprovider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))\ntrace.set_tracer_provider(provider)\n\n# Get a tracer\ntracer = trace.get_tracer(__name__)\n\n# Simulate an LLM API call and add semantic conventions\nwith tracer.start_as_current_span(\"llm.chat.completion\") as span:\n    span.set_attribute(SpanAttributes.LLM_VENDOR, \"OpenAI\")\n    span.set_attribute(SpanAttributes.LLM_MODEL_NAME, \"gpt-4\")\n    span.set_attribute(SpanAttributes.LLM_REQUEST_TYPE, LLMRequestTypeValues.CHAT.value)\n    span.set_attribute(SpanAttributes.LLM_PROMPT_MESSAGES, \n        [{'role': 'system', 'content': 'You are a helpful assistant.'},\n         {'role': 'user', 'content': 'Tell me a joke.'}])\n    span.set_attribute(SpanAttributes.LLM_RESPONSE_MODEL, \"gpt-4-0613\")\n    span.set_attribute(SpanAttributes.LLM_COMPLETIONS, \n        [{'role': 'assistant', 'content': 'Why did the scarecrow win an award? Because he was outstanding in his field!'}])\n    span.set_attribute(SpanAttributes.LLM_USAGE_TOTAL_TOKENS, 50)\n\nprint(\"Span with AI semantic conventions created and exported to console.\")","lang":"python","description":"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."},"warnings":[{"fix":"Update imports to use `opentelemetry.semconv.ai.*` for constants. If instrumentation is needed, look for dedicated instrumentation packages (e.g., `opentelemetry-instrumentation-langchain`).","message":"Version 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.","severity":"breaking","affected_versions":">=0.5.0"},{"fix":"Always 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.","message":"The 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Stay 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.","message":"As 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.","severity":"gotcha","affected_versions":"All 0.x.x versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}