mcpField
O
otel-semantic-conventions

otel-semantic-conventions

github.com/ollygardenDevelopment119153 installsUpdated 4d ago
Repository

About otel-semantic-conventions

otel-semantic-conventions is a skill for developers who need released OpenTelemetry naming and attribute guidance. It queries targeted convention details and helps verify implementations against a local upstream checkout.

Key features

  1. 01Query released convention groups and attributes
  2. 02Select conventions before creating custom keys
  3. 03Check local upstream repository guidance
  4. 04Include version and source context

Use cases

  1. 01Choose span names and telemetry attributes
  2. 02Check convention compliance in an implementation

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/ollygarden/opentelemetry-agent-skills --skill otel-semantic-conventions

After installing, type/otel-semantic-conventionsin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

evals/
evals.json
references/
otel-semantic-conventions.md
sdk-semconv-packages.md
semconv-selection.md
scripts/
query-otel-semantic-conventions.sh
test-query-otel-semantic-conventions.sh

Details

From the project README

OpenTelemetry Semantic Conventions

Use this skill when you need released semantic convention guidance for naming, attributes, or compliance checks.

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 open-telemetry/semantic-conventions-genai; it has no tagged release as of 2026-10-25, so cite the commit and label the guidance unreleased (the lookup script does not cover it); the core repository keeps only deprecated GenAI-era stubs after v1.42.0
  • see references/semconv-selection.md
  • to target a version a language's semconv package actually exposes (works offline, dated), see references/sdk-semconv-packages.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

Comments

Markdown supported