Why does OpenTelemetry's GenAI semantic convention spec matter for choosing an observability stack?
Explain why OpenTelemetry's GenAI semantic convention spec matters for picking an observability stack, and what specifically you lose by instrumenting with a proprietary tracing SDK, such as LangSmith's native SDK and callbacks, instead.
OTel's GenAI conventions standardise LLM-trace attribute names so any conformant backend reads them. Instrument once, switch vendors via exporter config, avoid proprietary lock-in.
Imagine every electrician used a different colour code for live, neutral, and earth wires. To swap from one electrician to another, you'd have to rewire every socket in the house. Then everyone agreed on a shared colour code (black, red, green). Now any electrician can plug into any house and read the wires correctly. OpenTelemetry's GenAI conventions are that shared colour code for LLM traces. Once your code emits standard attribute names, any monitoring vendor that reads OpenTelemetry can use your traces. If you instead used a vendor whose colours only their own electricians can read, leaving them means rewiring the house.
Concept explanation~2 min read
Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example. Click to expand.
Concept explanation~2 min read
Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example. Click to expand.
Through 2023 and most of 2024, every LLM observability vendor (LangSmith, Helicone, Arize Phoenix, Langfuse, Datadog) had its own trace shape, its own SDK and its own dashboard. Switching vendors meant a re-instrumentation pass over the entire codebase.
The OpenTelemetry community has since defined GenAI semantic conventions, now in Development status in their own repository. The major LLM-observability vendors accept them. Choosing to emit those conventions, rather than a vendor's own format, is the observability decision that most affects later migration cost.
What the GenAI conventions standardise
The OTel GenAI semantic conventions define a vocabulary for LLM-related spans: which attribute names go on which span, what values they carry, what operations exist, and how prompt/completion content is captured.
The conventions are in Development status (not stable) and live in the open-telemetry/semantic-conventions-genai repository, so names can still change.
Core span attributes
gen_ai.provider.name. The provider identifier (for example openai or anthropic).gen_ai.request.model. The model id requested by the call (for example gpt-5.5, claude-sonnet-4-6, gemini-3.1-pro).gen_ai.response.model. The model id the provider actually served (sometimes differs after routing).gen_ai.request.max_tokens,gen_ai.request.temperature,gen_ai.request.top_p,gen_ai.request.frequency_penalty. Call parameters.gen_ai.usage.input_tokens,gen_ai.usage.output_tokens. Token accounting.gen_ai.response.finish_reasons. Array of finish reasons from the provider.gen_ai.response.id. The provider's response id, useful for correlating with provider-side logs.
Operation names
Spans set gen_ai.operation.name to a well-known value such as chat, text_completion, generate_content, embeddings, execute_tool, create_agent or invoke_agent. Backends use it to render the right per-operation views.
Content attributes
Prompt and completion content go in the gen_ai.system_instructions, gen_ai.input.messages and gen_ai.output.messages attributes (plus gen_ai.tool.definitions). These are Opt-In, so they are not captured by default. They replace the older per-message events such as gen_ai.user.message and gen_ai.choice.
OTel instrumentation libraries gate content capture behind a flag (for example OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT) so regulated workloads can keep it off without losing the structural traces.
Situations where this technique stops working.
2–4 min · Everything important, quickly.
# Emit OTel traces from LangChain without LangSmith lock-in
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from openinference.instrumentation.langchain import LangChainInstrumentor
provider = TracerProvider()
provider.add_span_processor(
BatchSpanProcessor(
OTLPSpanExporter(endpoint="https://your-backend/v1/traces")
)
)
trace.set_tracer_provider(provider)
# One line wires LangChain to emit OTel spans (OpenInference attributes) on every call
LangChainInstrumentor().instrument()
# Now switch backends by changing the exporter endpoint: Langfuse, Phoenix,
# Datadog, Honeycomb, Grafana Tempo all accept the same OTLP spans.| Aspect | OTel GenAI conventions | LangSmith (proprietary) |
|---|---|---|
| Trace format | Open spec, vendor-neutral | Proprietary run format (native SDK); LangSmith also accepts OTLP |
| Backend portability | Langfuse, Phoenix, Datadog, Honeycomb, Tempo | LangSmith only (native SDK traces) |
| Instrumentation effort | Once, with OTel SDK or OpenInference/OpenLLMetry | Automatic via LangChain callbacks once LangSmith env vars are set; traceable decorator elsewhere |
| Cost to switch backend | Exporter config change | Re-instrument native SDK calls |
| Best fit | Multi-vendor or open-source observability | Teams committed to LangChain + LangSmith ecosystem |
Real products, models, and research that use this idea.
- Langfuse ingests OTLP traces and maps the GenAI attributes (model, token counts, request parameters), as well as OpenInference attributes.
- Arize Phoenix is built on OpenTelemetry but uses its own OpenInference conventions. It converts OTel GenAI attributes to OpenInference at ingest.
What an interviewer would ask next. Try answering before peeking at the approach.
QHow would you migrate an existing LangChain + LangSmith codebase to OTel GenAI conventions?
Add OpenInference's LangChain instrumentor and point its exporter at your OTel collector. Run both LangSmith and OTel in parallel for validation. Then turn off LangSmith tracing (unset LANGSMITH_TRACING) once the OTel traces are validated.
Red flags & common mistakes
The phrases that signal junior thinking. Click to expand.
Red flags & common mistakes
The phrases that signal junior thinking. Click to expand.
Treating observability vendor choice as a dashboard decision rather than a trace-format decision. When migration is needed, the team discovers that the trace shape itself is the lock-in.
60 second bullets to scan on the way to the call.
What the GenAI conventions standardise (attribute names + operations + content attributes)
Five specific gen_ai.* attributes and what they carry
Primary sources. Browse if you want the original framing.
Same topic, related formats. Practice these next.