Stats
Actions
Tags
Help us improve
Share bugs, ideas, or general feedback.
From sentry-sdk-skills
Review OpenTelemetry tracing span changes in SDK repositories for conformance to Sentry Conventions and OTel Semantic Conventions. Use when reviewing span instrumentation, "review spans", "check span conventions", "span review", "OTel span check", "tracing convention review".
npx claudepluginhub getsentry/sdk-skills --plugin sentry-sdk-skillsHow this skill is triggered — by the user, by Claude, or both
Slash command
/sentry-sdk-skills:span-convention-reviewopusThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Review changes in SDK repositories that involve OpenTelemetry tracing spans to ensure they conform to Sentry Conventions and, where Sentry conventions are underspecified, to OpenTelemetry Semantic Conventions.
OpenTelemetry tracing discipline: correct spans, propagation, and semantic conventions produce useful traces. Invoke whenever task involves any interaction with distributed tracing — span creation, context propagation, instrumentation, sampling configuration, or OpenTelemetry SDK setup.
Provides OpenTelemetry conventions for span naming, semantic attributes, status setting, in-memory trace testing, and instrumentation boundaries. Use when setting up tracing or writing trace tests.
Migrates Python SDK from transaction-based to span-first trace lifecycle for Sentry span streaming. Use when asked to enable span streaming or switch to streamed span delivery.
Share bugs, ideas, or general feedback.
Review changes in SDK repositories that involve OpenTelemetry tracing spans to ensure they conform to Sentry Conventions and, where Sentry conventions are underspecified, to OpenTelemetry Semantic Conventions.
Find all span-related changes in the current branch compared to the base branch:
git diff main...HEAD
Look for patterns indicating span creation or modification:
start_span, start_child, startSpan, StartSpanop=, op:, setting span operation namesset_data, set_attribute, setAttribute, SetAttributedescription=, name=, span namingSPANDATA., SpanData., span data constantsOP., span operation constantsgen_ai., db., http., cache., queue., messaging., resource., ui.If no diff is available, ask the user which files or changes to review.
Determine which Sentry Insights Module each span belongs to based on its operation prefix. Use this mapping to identify the relevant convention URLs:
For each module identified in Step 2, use WebFetch to retrieve the Sentry Convention page from the URL in the table above. Sentry conventions are the primary authority.
If the Sentry convention page is underspecified for a particular attribute, span name format, or operation pattern, also fetch the corresponding OTel Semantic Conventions page for supplementary guidance.
Do not assume or hardcode convention details. Always fetch the live documentation to ensure you are reviewing against the latest version.
For each span change, verify conformance against the fetched conventions for its module. Check the following categories:
op)Verify the op value matches the expected pattern defined in the fetched Sentry convention for the module.
Verify the span name follows the format specified in the fetched convention.
Verify all required span data attributes listed in the fetched convention are set.
Flag if commonly expected optional attributes (listed in the fetched convention) are missing. These are "should have" not blockers.
Check that spans do not leak sensitive data:
Verify attributes use correct types as specified in the conventions:
Present findings grouped by severity:
Issues that MUST be fixed — missing required attributes, wrong op format, incorrect span name patterns.
Issues that SHOULD be addressed — missing recommended attributes, suboptimal naming.
Informational observations — things that look correct, edge cases to be aware of, or areas where conventions are ambiguous.
For each finding, include:
## Span Convention Review
### Required Fixes
1. **[file:line]** Missing required attribute `gen_ai.operation.name`
- Convention: All AI agent spans MUST set `gen_ai.operation.name`
- Source: https://develop.sentry.dev/sdk/telemetry/traces/modules/ai-agents/
2. **[file:line]** Incorrect span name format
- Expected: `"chat {model}"` (e.g., `"chat gpt-4"`)
- Actual: `"OpenAI chat completion"`
- Source: https://develop.sentry.dev/sdk/telemetry/traces/modules/ai-agents/
### Recommended Improvements
1. **[file:line]** Missing recommended attribute `gen_ai.response.finish_reasons`
- This attribute helps with debugging incomplete responses
- Source: https://develop.sentry.dev/sdk/telemetry/traces/modules/ai-agents/
### Notes
- All cache spans correctly implement the `cache.hit` attribute
- Queue span naming follows OTel convention (Sentry convention is underspecified here)
cache.* and db.redis spans). Review each span type against its respective module convention.start_span(op=..., name=...), JavaScript uses startSpan({op: ..., name: ...}), etc.). Focus on the semantic correctness of op, name, and attributes regardless of the API surface.origin is set on auto-instrumented spans (pattern: auto.{category}.{integration}). This is a general Sentry SDK convention.