OTEP: Agent Telemetry Semantic Conventions (ATSC) by thegoo · Pull Request #4959 · open-telemetry/opentelemetry-specification

thegoo · 2026-03-18T02:41:39Z

This PR proposes Agent Telemetry Semantic Conventions (ATSC) — a vendor-neutral semantic layer for AI agent observability that sits above OTel GenAI Semantic Conventions.

Every ATSC span is a valid OTel span ingestible by any OTLP receiver without custom plugins.

Draft spec and JSON Schema are available at ATSC for reference and community feedback.

Known v0.1.0 limitations before you fire:

Completed spans only. No buffering model — assembling start/end events into complete spans is on the implementor.
PII and sensitive data scrubbing is the responsibility of the telemetry generator. The spec does not define a redaction pipeline.

Originally posted on Reddit r/OpenTelemetry on 16 March 2026 for community feedback. @mhausenblas suggested submitting as an OTEP.

I am currently working on POC bridge adapter pattern to receive raw telemetry from source (e.g.: LangFuse), normalize to ATSC span structure, and emit spans via OTLP for compatible receivers. I will update with a link to the repo when that is completed.

Appreciate the discussion and opportunity to discuss this! Thanks!

linux-foundation-easycla · 2026-03-18T02:41:45Z

The committers listed above are authorized under a signed CLA.

✅ login: thegoo / name: Jesse Williams (2940f3c, 5bf9b78, b068771, dfb17e9)

…ry-semantic-conventions.md

reyang · 2026-03-18T03:57:28Z

+
+## Motivation
+
+AI agent systems present observability requirements that general-purpose distributed tracing specifications do not address. The OpenTelemetry base specification defines spans, traces, metrics, and logs. The OTel GenAI Semantic Conventions define attributes for LLM calls. Neither covers what happens at the agent level.


The OTel GenAI Semantic Conventions

Maybe link to https://github.com/open-telemetry/semantic-conventions/tree/main/model/gen-ai or the published version?

reyang · 2026-03-18T03:59:20Z

+
+AI agent systems present observability requirements that general-purpose distributed tracing specifications do not address. The OpenTelemetry base specification defines spans, traces, metrics, and logs. The OTel GenAI Semantic Conventions define attributes for LLM calls. Neither covers what happens at the agent level.
+
+Current gaps include:


Are these gaps something that the OTel GenAI semantic convention group wants to cover in the future, or folks decided that these are out of scope?

reyang · 2026-03-18T04:01:51Z

+
+Without a shared standard, every observability platform (Langfuse, LangSmith, Arize Phoenix) defines its own schema. Every agent framework (LangGraph, Microsoft Agent Framework, AutoGen, Semantic Kernel) emits incompatible telemetry shapes. Enterprises running multiple frameworks and multiple observability backends are forced to maintain bespoke translation layers.
+
+This proposal defines Agent Telemetry Semantic Conventions (ATSC) — a vendor-neutral semantic layer that sits above OTel GenAI Semantic Conventions in the same way that GenAI SemConv sits above the OTel base specification.


I think we normally call such thing "Semantic Conventions for Xyz" rather than "Xyz Telemetry Semantic Conventions". Take database for example, we call it https://github.com/open-telemetry/semantic-conventions/tree/main/docs/db#semantic-conventions-for-database-calls-and-systems

reyang · 2026-03-18T04:05:44Z

+| `human.override` | INTERNAL | Human modified or overrode agent output. |
+| `guardrail.check` | INTERNAL | A guardrail evaluated as a discrete operation. |
+| `evaluation.run` | INTERNAL | An evaluation or scoring operation. |
+| `infra.cache` | CLIENT | A cache read or write operation. |


Why is this CLIENT? What's the criteria when deciding what SpanKind should be used?
Do we follow https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#spankind or we need to update the SpanKind definition or provide some supplementary guideline?

trask · 2026-03-18T04:47:36Z

hi @thegoo!

In case you haven't looked at the GenAI Semantic Conventions recently, I believe these things in your proposal already exist today:

Agent invocation/creation (invoke_agent, create_agent, gen_ai.agent.*)
Tool execution (execute_tool, gen_ai.tool.*)
MCP calls (mcp.client/mcp.server spans)
Retrieval/RAG (gen_ai.retrieval.client, gen_ai.data_source.id)
Conversation tracking (gen_ai.conversation.id)
Token usage metrics (gen_ai.client.token.usage)
Evaluation (gen_ai.evaluation.* attributes and gen_ai.evaluation.result event)
Embeddings (gen_ai.embeddings.client span)

And I think most(?) of the remaining things in your proposal have open discussions (and open PRs in two cases):

Reasoning steps / turns: Adding ReAct Iterations Spans in Reasoning-Acting Agents semantic-conventions-genai#81, Enhancing OTel GenAI Semantic Conventions with a User-Centric Entry Span semantic-conventions#3418
Multi-agent handoffs: Add semantic conventions for A2A (Agent-to-Agent) protocol semantic-conventions-genai#70 (A2A protocol), Add MultiAgent Semantic Conventions semantic-conventions-genai#24
Human-in-the-loop: Proposal: GenAI semantic event for pre-execution judgment and negative proof semantic-conventions-genai#72 (includes a human_in_loop attribute proposal)
Guardrails: gen-ai: add security guardian (apply_guardrail) span + finding event semantic-conventions#3233 (adds apply_guardrail span), Proposed semantic conventions for provider-side GenAI safety telemetry semantic-conventions#3356, GenAI conventions for safety settings/ratings semantic-conventions-genai#17, LLM: Standardized fields for LLM Security and protection [Discussion] semantic-conventions#1007
Agent memory: gen-ai: semantic conventions for memory operations semantic-conventions#3250, Semantic Conventions for Generative AI Agentic Systems (gen_ai.*) semantic-conventions-genai#35
Workflows/tasks: Add Workflows/Agents/Tasks to gen_ai semantic-conventions-genai#55, Semantic Conventions for Generative AI Tasks (gen_ai.task.*) semantic-conventions-genai#37, AI Agent framework Semantic Convention semantic-conventions-genai#11

It would be great if you could review the existing work and the open proposals and come to join our discussions in the GenAI SemConv SIG which meets Tuesdays 9am Pacific (except for next week due to KubeCon)!

reyang

I think we need to get a solid answer here #4959 (comment)

JeffLuoo · 2026-03-18T17:50:55Z

+
+Current gaps include:
+
+- No standard representation for agent reasoning cycles, tool invocations, or multi-agent handoffs


https://github.com/open-telemetry/semantic-conventions/blob/af46181baec13bd5fe5552b3ec8181743047ffae/docs/gen-ai/mcp.md

gen_ai.operation.name is set to execute_tool for tool invocations.

thegoo · 2026-03-19T01:35:40Z

Hey @trask! Thank you for taking the time to reply and map that out. Appreciate the feedback. I have some homework to do. I will review the existing GenAI SemConv and open PRs to get a lay of the land.

Noted on KubeCon next week. Will plan to attend the following Tuesday.

Thanks again. Talk soon.

lmolkova · 2026-04-01T15:18:34Z

@thegoo thanks for the contribution! Please let us know if you find any gaps in the existing / proposed GenAI conventions. https://github.com/open-telemetry/semantic-conventions would be the right place to create any follow up issues or PRs.

I'm going to close this one, but looking forward to more discussions in semantic conventions.

thegoo · 2026-04-01T15:22:40Z

@lmolkova - thank you! Will do. I have yet to finish reviewing, been tied up. I will post feedback over there. Appreciate the collaboration and talk soon.

OTEP: Agent Telemetry Semantic Conventions (ATSC)

b068771

thegoo requested review from a team as code owners March 18, 2026 02:41

thegoo added 3 commits March 17, 2026 22:44

Updated to include PR number in ATSC proposal md - 4959-agent-telemet…

2940f3c

…ry-semantic-conventions.md

Updated name and date typos.

dfb17e9

Removed 0000 file.

5bf9b78

reyang reviewed Mar 18, 2026

View reviewed changes

reyang requested changes Mar 18, 2026

View reviewed changes

thegoo force-pushed the atsc-agent-telemetry-semantic-conventions branch from 7fb7b7e to 5bf9b78 Compare March 18, 2026 14:54

JeffLuoo reviewed Mar 18, 2026

View reviewed changes

lmolkova closed this Apr 1, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

OTEP: Agent Telemetry Semantic Conventions (ATSC)#4959

OTEP: Agent Telemetry Semantic Conventions (ATSC)#4959
thegoo wants to merge 4 commits intoopen-telemetry:mainfrom
thegoo:atsc-agent-telemetry-semantic-conventions

thegoo commented Mar 18, 2026

Uh oh!

linux-foundation-easycla Bot commented Mar 18, 2026 •

edited

Loading

Uh oh!

reyang Mar 18, 2026

Uh oh!

reyang Mar 18, 2026

Uh oh!

reyang Mar 18, 2026 •

edited

Loading

Uh oh!

reyang Mar 18, 2026

Uh oh!

trask commented Mar 18, 2026

Uh oh!

reyang left a comment

Uh oh!

JeffLuoo Mar 18, 2026

Uh oh!

thegoo commented Mar 19, 2026

Uh oh!

lmolkova commented Apr 1, 2026

Uh oh!

thegoo commented Apr 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants


		## Motivation

		AI agent systems present observability requirements that general-purpose distributed tracing specifications do not address. The OpenTelemetry base specification defines spans, traces, metrics, and logs. The OTel GenAI Semantic Conventions define attributes for LLM calls. Neither covers what happens at the agent level.


		AI agent systems present observability requirements that general-purpose distributed tracing specifications do not address. The OpenTelemetry base specification defines spans, traces, metrics, and logs. The OTel GenAI Semantic Conventions define attributes for LLM calls. Neither covers what happens at the agent level.

		Current gaps include:


		Without a shared standard, every observability platform (Langfuse, LangSmith, Arize Phoenix) defines its own schema. Every agent framework (LangGraph, Microsoft Agent Framework, AutoGen, Semantic Kernel) emits incompatible telemetry shapes. Enterprises running multiple frameworks and multiple observability backends are forced to maintain bespoke translation layers.

		This proposal defines Agent Telemetry Semantic Conventions (ATSC) — a vendor-neutral semantic layer that sits above OTel GenAI Semantic Conventions in the same way that GenAI SemConv sits above the OTel base specification.


		Current gaps include:

		- No standard representation for agent reasoning cycles, tool invocations, or multi-agent handoffs

Conversation

thegoo commented Mar 18, 2026

Uh oh!

linux-foundation-easycla Bot commented Mar 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

reyang Mar 18, 2026

Choose a reason for hiding this comment

Uh oh!

reyang Mar 18, 2026

Choose a reason for hiding this comment

Uh oh!

reyang Mar 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

reyang Mar 18, 2026

Choose a reason for hiding this comment

Uh oh!

trask commented Mar 18, 2026

Uh oh!

reyang left a comment

Choose a reason for hiding this comment

Uh oh!

JeffLuoo Mar 18, 2026

Choose a reason for hiding this comment

Uh oh!

thegoo commented Mar 19, 2026

Uh oh!

lmolkova commented Apr 1, 2026

Uh oh!

thegoo commented Apr 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

linux-foundation-easycla Bot commented Mar 18, 2026 •

edited

Loading

reyang Mar 18, 2026 •

edited

Loading