{
 "id": "otel-genai-semconv",
 "name": "OpenTelemetry GenAI Semantic Conventions (agents and MCP)",
 "acronym": "",
 "aliases": [
  "OTel GenAI semconv",
  "gen_ai.* attributes",
  "semantic-conventions-genai"
 ],
 "collisions": [],
 "step": "account",
 "parties": [
  "agent-site",
  "agent-agent"
 ],
 "form": "document-format",
 "track": "linux-foundation",
 "scope": "general",
 "question": "What span, metric and attribute names should agent frameworks and MCP clients and servers emit, so traces of agent runs and tool calls line up across vendors?",
 "analog": "A common log format (like the web server combined log), for agent traces",
 "origin": {
  "org": "OpenTelemetry (CNCF)",
  "date": null
 },
 "governance": "OpenTelemetry project (backed by the CNCF); developed in the open-telemetry/semantic-conventions-genai repository, which extends the core OpenTelemetry Semantic Conventions",
 "native_status": "Status: Development (OpenTelemetry document status) on both the agent-spans and MCP documents; the repository has no tagged release",
 "phase": "draft",
 "implementation": "prototype",
 "adoption": {
  "level": "unmeasured",
  "by": null,
  "probe_run": null
 },
 "version": {
  "label": "Development (unreleased; repository has no tags); builds on core semantic conventions v1.44.0",
  "date": "2026-10-19"
 },
 "spec_url": "https://github.com/open-telemetry/semantic-conventions-genai/blob/main/docs/gen-ai/gen-ai-agent-spans.md",
 "discovery": {
  "mechanism": "None at the web layer; the conventions name attributes on OpenTelemetry spans and metrics that an agent's own instrumentation exports to its operator's tracing backend",
  "path": null
 },
 "probe": {
  "method": "NONE",
  "path": "",
  "parse": "",
  "on_absent": "Telemetry naming lives inside an operator's tracing pipeline; nothing can be observed from a site's public endpoints."
 },
 "evidence": [
  {
   "claim": "gen-ai-agent-spans.md, Status: Development, defines spans for create_agent, invoke_agent (client and internal), invoke workflow, plan, execute_tool, load skill, read skill resource and command execution, using gen_ai.* attributes such as gen_ai.operation.name and gen_ai.agent.name.",
   "date": "2026-10-19",
   "label": "VERIFIED",
   "url": "https://github.com/open-telemetry/semantic-conventions-genai/blob/main/docs/gen-ai/gen-ai-agent-spans.md"
  },
  {
   "claim": "mcp.md, Status: Development, defines MCP client and server spans with context propagation, the metrics mcp.client.operation.duration, mcp.server.operation.duration, mcp.client.session.duration and mcp.server.session.duration, and examples for stdio and Streamable HTTP transports; it links core semantic conventions v1.44.0.",
   "date": "2026-10-19",
   "label": "VERIFIED",
   "url": "https://github.com/open-telemetry/semantic-conventions-genai/blob/main/docs/gen-ai/mcp.md"
  },
  {
   "claim": "The repository (Apache-2.0, created 2026-05-05, last pushed 2026-10-19, no tags) says it extends the core OpenTelemetry Semantic Conventions with GenAI, MCP and provider-specific conventions, generated from YAML models with Weaver, and keeps reference implementations under reference/.",
   "date": "2026-10-19",
   "label": "VERIFIED",
   "url": "https://github.com/open-telemetry/semantic-conventions-genai"
  }
 ],
 "summary_md": "OpenTelemetry's GenAI semantic conventions give agent frameworks and MCP implementations a shared vocabulary for telemetry: the names of spans, metrics and `gen_ai.*` attributes to emit when an agent is created or invoked, plans, runs a workflow, calls a tool, loads a skill or runs a command [1]. A separate MCP document defines client and server spans, how trace context is propagated over MCP, and four duration metrics for operations and sessions on each side [2]. With the same names, a trace that crosses frameworks and MCP servers can be followed and audited in one tracing backend.\n\nThe conventions live in their own repository, open-telemetry/semantic-conventions-genai (Apache-2.0, created 2026-05-05), which extends the core OpenTelemetry Semantic Conventions and keeps reference implementations alongside the spec [3]. Both documents read here are marked Development, OpenTelemetry's least stable document status, and the repository has no tagged release, so names may still change [1][2][3].\n\nThis is an account-step record: it does not decide who an agent is or what it may do, only how what it did is recorded. Nothing is exposed at a website origin, so there is no probe. Which frameworks emit these conventions today was not counted in this pass.",
 "part_of": null,
 "group": null,
 "use_cases": [
  "audit-agent-actions"
 ],
 "audience": [
  "agent-builder",
  "platform"
 ],
 "pairs_with": [
  "mcp",
  "agent-audit-trail"
 ],
 "prerequisites": [],
 "dispute": null,
 "last_verified": "2026-10-20",
 "history": [
  {
   "date": "2026-10-20",
   "note": "added from gap scout 2026-10-20; verified against open-telemetry/semantic-conventions-genai (docs/gen-ai/gen-ai-agent-spans.md, docs/gen-ai/mcp.md, README and repository metadata)"
  }
 ],
 "watch": [
  {
   "type": "github",
   "repo": "open-telemetry/semantic-conventions-genai",
   "mode": "tag",
   "version": false
  },
  {
   "type": "page",
   "url": "https://github.com/open-telemetry/semantic-conventions-genai/blob/main/docs/gen-ai/gen-ai-agent-spans.md",
   "selector": "main",
   "cadence": "weekly"
  },
  {
   "type": "page",
   "url": "https://github.com/open-telemetry/semantic-conventions-genai/blob/main/docs/gen-ai/mcp.md",
   "selector": "main",
   "cadence": "weekly"
  }
 ],
 "freshness": "current"
}