semantic-conventions-genai

OpenTelemetry GenAI semantic conventions: spans, metrics, and events for GenAI clients, MCP, and provider-specific conventions. Attributes live in model/<namespace>/registry.yaml; signals in model/<namespace>/{spans,metrics,events}.yaml. Human docs are in docs/gen-ai/; runnable proofs in reference/.

How to contribute conventions

1. Be concise. Short brief/note text. Small, focused PRs — phase large changes across several.
2. Be actionable. Tell instrumentation authors how to collect telemetry and consumers how to interpret it. Keep justification out of the conventions — put it in the PR description.
3. Use this repo's terminology. Reuse the established vocabulary — operation, span, attribute, signal, inference, embeddings, execute tool, invoke agent (client vs internal), plan, memory, retrieval, workflow — and existing gen_ai.* attribute names. When introducing a new concept, explain it and show how it maps across libraries and frameworks.
4. No attribute without a signal. Every attribute added must be referenced by a span, metric, or event that defines when and how it is recorded. No orphan attributes.
5. No convention without a reference scenario. A new convention needs a reference/scenarios/<library>/ scenario that emits it, with every emitted value readable from inside the library: a parameter it interprets, a return value, exception, or library state. See reference/CONTRIBUTING.md.
6. Only model what generic instrumentation can record at runtime. A reference scenario must plausibly show how generic instrumentation captures the telemetry from information available to it at runtime. If it isn't instrumentable, don't propose conventions — open an issue and bring it to the GenAI SIG or #otel-genai-instrumentation.
7. Investigate breadth first. Before adding a convention, survey the libraries/frameworks it applies to and the terminology and primitives they use. Propose something that works broadly across them, not for one SDK.
8. Don't over-abstract. If a broadly-applicable convention gets too abstract to be useful, prefer concrete framework-specific conventions over a forced generic concept.
9. Stay in the GenAI domain. This repo holds GenAI-related conventions. If a proposal is broader than GenAI, take it to open-telemetry/semantic-conventions.

Workflow

make generate-all      # regenerate registry docs, embedded tables, reports — run after editing model
make test-json-schemas # validate sample documents against model/gen-ai/*.json; see docs/gen-ai/non-normative/tests/README.md

cd reference
uv run run-scenario <library>   # or --all; runs scenario, validates telemetry, writes data.json

CI fails if committed generated output doesn't match make generate-all. Add a Towncrier fragment under changelog.d/ for any consumer-visible change. See CONTRIBUTING.md.

For PRs that change semantic conventions, use the reference skill in .github/skills/reference/SKILL.md. For reviews of reference coverage and capturability, see the evaluation rubric in .github/instructions/evaluate-reference.instructions.md - an instruction file that applies automatically to model, docs, and scenario changes, not a skill to invoke.

Further reading

• How to write conventions - best practices
• Naming
• Events
• Recording errors