OpenTelemetry Semantic Conventions

Workflow

1. Start with released semantic conventions, not model memory.

• do not load the full semantic convention spec into context
• use the bundled lookup script to query only the needed released group or attribute
• for local verification against a checked-out upstream repo, set

  OTEL_SEMCONV_REPO=/path/to/semantic-conventions

1. Choose the closest released group before inventing custom keys.

• identify the boundary type such as

  http

  ,

  db

  ,

  messaging

  ,

  rpc

  , or

  network

• pick one primary group first, then add related groups only when they add needed context
• for

  gen_ai.*

  , OpenAI, or MCP conventions, use the dedicated OpenTelemetry GenAI semantic conventions repository; the core repository keeps only deprecated GenAI-era stubs after v1.42.0
• see

  references/semconv-selection.md

1. Query only the released guidance you need.

• list groups:

  ./scripts/query-otel-semantic-conventions.sh --groups

• inspect one group:

  ./scripts/query-otel-semantic-conventions.sh http

• inspect one kind:

  ./scripts/query-otel-semantic-conventions.sh http spans

• inspect one exact attribute or entry:

  ./scripts/query-otel-semantic-conventions.sh http http.request.method

• see

  references/otel-semantic-conventions.md

• after changing the parser, run

  OTEL_SEMCONV_REPO=/path/to/semantic-conventions bash ./scripts/test-query-otel-semantic-conventions.sh

1. Apply the released naming and attribute rules directly.

• use required and recommended attributes before optional ones
• derive semconv-governed span names directly from the released naming rule
• do not prepend or append protocol labels, hostnames, product names, business hints, or other custom prose to semconv-governed span names
• if the released naming rule does not provide a low-cardinality target, use the simpler fallback allowed by that convention
• if no released key exists, use a stable custom namespace and keep values bounded

1. Return the result with exact source context.

• include the group name, released version, and source URL from the script output
• call out any concrete compatibility limitation if the implementation cannot fully match the released guidance