Good abstractions hide complexity, not evidence

The idea in brief

A shared platform for model access hides a lot on purpose: deployments, networking, credentials and provider APIs. The question this post looks at is narrower: which signals should still reach the teams calling it, so they can tell where a problem sits. Public standards from OpenTelemetry and the W3C already cover a good part of this.

A shared vocabulary from OpenTelemetry

OpenTelemetry's GenAI semantic conventions define standard names for telemetry about model calls, agent operations and tool execution. The OpenTelemetry project's own 2026 walkthrough of GenAI observability shows what this looks like in practice:

• Token usage is recorded on spans as gen_ai.usage.input_tokens and gen_ai.usage.output_tokens, and aggregated in the gen_ai.client.token.usage histogram.
• Latency is recorded in the gen_ai.client.operation.duration histogram, which can be split by gen_ai.request.model.
• Tool calls appear as execute_tool spans nested under an invoke_agent span, next to the model call spans.

Mapped to the questions an application team is likely to ask, the conventions cover several of them directly:

The last row is the gap. Retries, fallbacks and policy decisions happen inside the platform, so they only become visible if the platform chooses to emit them.

How settled the conventions are

The conventions are still evolving. According to the project's repository and Dash0's guide, they are marked as Development, and in June 2026 (semantic conventions v1.42.0) they moved into a dedicated semantic-conventions-genai repository so they can change faster than the core conventions. Dash0 notes that the only Stable attributes on a typical GenAI span are inherited from the core conventions, such as error.type and server.address.

A practical consequence is that attribute names may still change. Teams adopting them may find it easier to emit these signals from one shared place, such as a gateway or a common client library, rather than in every application.

Connecting what each side sees

The W3C Trace Context Recommendation defines the traceparent header, which carries a trace ID, the caller's span ID and a sampled flag between services. When the same trace ID shows up in the application's logs and in the platform's traces, both sides can look at one request together. An example value from the specification's format:

traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
             ^  ^ trace ID                       ^ parent span ID ^ flags

What usually stays out by default

Prompt and response content is handled differently from metadata. The OpenTelemetry walkthrough describes content capture as off by default: without it, spans carry model names, token counts and durations, but no prompts or tool arguments. It also points out that captured content can be sensitive. Metadata alone is often enough to tell whether a problem is in the application, the platform, the model or a tool.

@article{adam2026hidecomplexitynotevidence,
  title   = {Good abstractions hide complexity, not evidence},
  author  = {Adam, Ammar},
  journal = {www.ammaradam.dev},
  year    = {2026},
  month   = {Oct},
  url     = {https://www.ammaradam.dev/posts/hide-complexity-not-evidence/}
}