OpenTelemetry GenAI Semantic Conventions: The Definitive Reference Guide

As generative AI and autonomous agent applications move from experimental scripts into enterprise production, the need for standardized, vendor-neutral telemetry has never been more urgent. Proprietary SDKs create lock-in, make multi-model architectures fragile, and isolate AI logs from backend infrastructure telemetry.

To solve this, the OpenTelemetry Generative AI Semantic Conventions Working Group established the official standard for modeling LLM calls, embeddings, vector searches, and autonomous agent workflows.

This guide provides the complete technical reference for the OpenTelemetry GenAI Semantic Conventions, detailing attributes, span types, event structures, and OTLP payload formats.

1. Core Namespace Structure

OpenTelemetry organizes GenAI attributes under the gen_ai.* namespace hierarchy:

gen_ai.*
├── gen_ai.system                (Framework / Provider: "splyntra", "openai", "anthropic")
├── gen_ai.request.*             (Requested parameters: model, temperature, max_tokens)
├── gen_ai.response.*            (Returned metadata: model, finish_reasons, id)
├── gen_ai.usage.*               (Token counters: prompt_tokens, completion_tokens)
├── gen_ai.agent.*               (Agent primitives: name, step, goal, task_id)
└── gen_ai.tool.*                (Tool execution: name, call_id, parameters, status)

2. The Comprehensive GenAI Attribute Reference

3. Span Hierarchy & Operation Names

OpenTelemetry specifies consistent operation names for Generative AI spans:

Span: agent.workflow (Kind: SERVER / INTERNAL)
│
├── Span: gen_ai.chat (Kind: CLIENT)
│   ├── Attribute: gen_ai.system = "openai"
│   ├── Attribute: gen_ai.request.model = "gpt-4o"
│   └── Event: gen_ai.content.prompt (optional if sanitized)
│
├── Span: gen_ai.tool (Kind: INTERNAL)
│   ├── Attribute: gen_ai.tool.name = "fetch_weather"
│   └── Attribute: gen_ai.tool.parameters = "{\"city\": \"Tokyo\"}"
│
└── Span: gen_ai.embeddings (Kind: CLIENT)
    ├── Attribute: gen_ai.system = "openai"
    └── Attribute: gen_ai.request.model = "text-embedding-3-small"

4. Constructing Raw OTLP Payloads in JSON

When sending telemetry over HTTP to https://ingest.splyntra.com/v1/traces, spans are formatted using the standard protobuf/JSON OTLP schema:

{
  "resourceSpans": [
    {
      "resource": {
        "attributes": [
          { "key": "service.name", "value": { "stringValue": "customer-support-agent" } },
          { "key": "deployment.environment", "value": { "stringValue": "production" } }
        ]
      },
      "scopeSpans": [
        {
          "scope": { "name": "splyntra.genai.tracer", "version": "1.0.0" },
          "spans": [
            {
              "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
              "spanId": "00f067aa0ba902b7",
              "name": "gen_ai.chat",
              "kind": 3,
              "startTimeUnixNano": 1723632000000000000,
              "endTimeUnixNano": 1723632000650000000,
              "attributes": [
                { "key": "gen_ai.system", "value": { "stringValue": "openai" } },
                { "key": "gen_ai.request.model", "value": { "stringValue": "gpt-4o" } },
                { "key": "gen_ai.usage.prompt_tokens", "value": { "intValue": 1820 } },
                { "key": "gen_ai.usage.completion_tokens", "value": { "intValue": 290 } },
                { "key": "splyntra.cost_usd", "value": { "doubleValue": 0.00745 } },
                { "key": "splyntra.risk_score", "value": { "doubleValue": 0.02 } }
              ],
              "status": { "code": 1 }
            }
          ]
        }
      ]
    }
  ]
}

5. Standardized GenAI Metrics

In addition to distributed traces, the OpenTelemetry working group specifies standard Prometheus/OTel metric instruments:

• gen_ai.client.token.usage (Histogram): Measures prompt and completion token counts per request.
• gen_ai.client.operation.duration (Histogram): Measures end-to-end latency of LLM and tool calls.
• gen_ai.client.time_to_first_token (Histogram): Measures TTFT for streaming completions.
• gen_ai.agent.step_count (Histogram): Measures iteration distribution across agent runs.

Next Steps & Related Technical Guides

• How to Monitor AI Agents with OpenTelemetry — Code-complete setup guide.
• How to Trace AI Agents with OpenTelemetry — Distributed context propagation across multi-agent graphs.
• AI Agent Observability: What You Need to Monitor in Production — Pillar guide to production telemetry.
• AI Agent Monitoring: Metrics You Should Track — 12 Golden Signals for agents.