Semantic Conventions

---
name: semantic-conventions
description: "Understand and validate OpenLLMetry's GenAI semantic-convention layer."
disable-model-invocation: true
metadata:
  disco-role: operating
license: Apache 2.0
---

# Semantic Conventions

Use this sub-skill when the task is about OpenLLMetry's semantic-convention contract rather than a provider wrapper or SDK decorator workflow.

## Route here for

- Importing or validating `opentelemetry.semconv_ai` symbols such as `SpanAttributes`, `GenAISystem`, `Meters`, `Events`, `EventAttributes`, `LLMRequestTypeValues`, and `TraceloopSpanKindValues`.
- Mapping upstream OpenTelemetry GenAI attributes such as `gen_ai.provider.name`, `gen_ai.input.messages`, `gen_ai.output.messages`, `gen_ai.tool.definitions`, and `gen_ai.response.finish_reasons`.
- Understanding Traceloop workflow/task/agent/tool span attributes and vector DB event attributes.
- Migrating legacy `LLM_*` names to current `GEN_AI_*` or upstream `GenAIAttributes` names without breaking compatibility aliases.
- Checking whether an installed environment exposes the expected constants and enums using `scripts/check_semconv_constants.py`.

## Use the bundled references

- `references/semantic-attributes.md` — import map, constant groups, message/tool/finish-reason validation rules, and compliance-helper expectations.
- `references/migration-notes.md` — legacy alias categories, provider-name migration, and safe before/after snippets.
- `references/troubleshooting.md` — version drift, deprecated `gen_ai.system`, content/event gating, JSON schemas, finish-reason placement, and alias confusion.
- `scripts/check_semconv_constants.py` — no-network helper for public constant/enumeration checks; supports `--json`.

## Route elsewhere

- Provider wrapper patch points, `.instrument()` behavior, optional target-library failures, and VCR/live-service provider behavior: `../instrumentations/SKILL.md`.
- Traceloop SDK initialization, decorators, manual spans, exporters/processors, and app-level content-tracing configuration: `../sdk-and-tracing/SKILL.md`.
- Checkout-level commands, package maintenance, lint/test selection, and VCR cassette policy: `../repo-development/SKILL.md`.

## Operating checks

When validating a semantic-convention change, keep these invariants visible:

1. New provider spans should use upstream `gen_ai.provider.name`; treat `gen_ai.system` as deprecated compatibility data.
2. Content-bearing message attributes must use the upstream JSON-array fields; finish-reason metadata must not be dropped solely because content tracing is disabled.
3. `SpanAttributes.LLM_*` names are intentionally retained for older packages, but new code should use current `GEN_AI_*` names or upstream `GenAIAttributes` constants.
4. The shared `_testing.py` helper is the source pattern for constant/enumeration compliance checks; use the bundled checker for a safe environment probe.