// 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".
Creates Linear projects for SDK repositories based on a Linear initiative. Use when rolling out a feature across multiple SDKs, creating SDK projects from initiative, or setting up cross-SDK alignment work.
Implement a feature across Sentry SDK repositories by spawning parallel agents. Use when you have Linear initiatives/projects/issues and want to create draft PRs. Triggers on "implement across SDKs", "spawn SDK agents", "SDK implementation", "parallel SDK implementation", "continue SDK rollout".
Classify and apply SDK Telemetry labels to Linear issues based on their title and description. Use when triaging issues related to SDK telemetry signals: errors, traces, spans, profiles, replays, logs, metrics, cron checks, client reports, user feedbacks, or attachments. Triggers: "sdk telemetry label", "telemetry labeler", "label telemetry issues", "tag telemetry".
Classify and apply Type labels to Linear issues based on their title and description.
Generate or align a CONTRIBUTING.md for a Sentry SDK repository with the develop.sentry.dev standard template. Use when asked to "create contributing.md", "update contributing.md", "align contributing docs", "standardize contributor docs", or when the contributing guide is outdated, missing sections, or does not exist.
Generate a formatted async daily standup message for the Sentry SDK team channel. Use when asked to create a "daily update", "async daily", "standup update", or "async team update".
| name | span-convention-review |
| description | 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". |
| model | opus |
| allowed-tools | Read Grep Glob Bash WebFetch |
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.