---

name: openllmetry description: "Route OpenLLMetry Python SDK, GenAI instrumentation, semantic-convention, and repository-maintenance tasks." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

OpenLLMetry

Use this repo skill for the Python OpenLLMetry package suite: the Traceloop SDK, OpenTelemetry GenAI instrumentations, the opentelemetry.semconv_ai semantic-convention layer, and checkout-local package maintenance.

Read this skill when

• You need to add OpenLLMetry tracing to a Python LLM, RAG, vector database, agent, MCP, or provider SDK application.
• You need to choose between Traceloop.init(...) and direct OpenAIInstrumentor().instrument()-style setup.
• You need exact OpenLLMetry semantic-convention constants, span attributes, event/message schemas, or legacy alias migration guidance.
• You need to troubleshoot missing optional target libraries, no emitted spans, content tracing, metrics/logging, VCR cassette replay, or Nx/uv test commands.
• You are editing an OpenLLMetry checkout and need package/test/source-script guidance.

Fast install/import checks

For application use, start with the SDK:

pip install traceloop-sdk

For direct wrapper use, install the instrumentation package and the target client library it wraps. Many packages declare the target library in an instruments optional extra, for example:

pip install 'opentelemetry-instrumentation-openai[instruments]'

Minimal imports:

from traceloop.sdk import Traceloop
from traceloop.sdk.decorators import workflow, task, agent, tool
from traceloop.sdk.instruments import Instruments
from opentelemetry.semconv_ai import SpanAttributes

Run scripts/check_openllmetry_env.py to check installed package metadata and safe imports without provider calls or network access.

Route by task

If the task is about...	Read
SDK bootstrap, exporters/processors, decorators, manual LLM spans, association properties, content tracing, prompt/dataset/experiment/guardrail client surfaces	sub-skills/sdk-and-tracing/SKILL.md
Direct provider/vector/framework/protocol instrumentors, SDK Instruments selection, optional target clients, duplicate/no-span wrapper troubleshooting	sub-skills/instrumentations/SKILL.md
opentelemetry.semconv_ai, GenAI message schemas, provider names, finish reasons, LLM_* to GEN_AI_* migration, semconv compliance checks	sub-skills/semantic-conventions/SKILL.md
Nx/uv package maintenance, focused test selection, VCR cassettes, source scripts, release/codegen cautions, package discovery in a checkout	sub-skills/repo-development/SKILL.md

Shared references

• references/package-overview.md explains the package family, selected scope, distribution categories, and prerequisites.
• references/troubleshooting.md covers cross-cutting install/import/export/content issues before routing to sub-skill-specific troubleshooting.
• references/repo-provenance.md records the source snapshot used to generate this skill. Read it before deciding whether a checkout needs refresh-repo-skill.
• references/repo-routing-metadata.json is structured router metadata for managed repo-skill imports.

Operating rules

• Prefer no-network smoke checks and in-memory exporters before live provider calls.
• Treat cloud/provider keys, VCR re-recording, vector services, local Ollama daemons, and model downloads as explicit prerequisites, not default verification steps.
• Do not assume a missing provider client is an OpenLLMetry bug; many instrumentor modules require the target client package at import time.
• Use TRACELOOP_TRACE_CONTENT=false to suppress prompt/completion/entity content when privacy matters.
• In a checkout, use Nx for workspace orchestration and uv for package-local Python commands.