diff --git a/.agents/skills/add-ai-integration/SKILL.md b/.agents/skills/add-ai-integration/SKILL.md index c3b823fdfa17..278160f4133c 100644 --- a/.agents/skills/add-ai-integration/SKILL.md +++ b/.agents/skills/add-ai-integration/SKILL.md @@ -10,7 +10,7 @@ argument-hint: Span ops and attributes are specified outside this repo. Never invent or hardcode either: -- [gen_ai attributes](https://getsentry.github.io/sentry-conventions/attributes/gen_ai/) and [gen_ai ops](https://getsentry.github.io/sentry-conventions/ops/#gen_ai) — normative; import from `@sentry/conventions/attributes` and `@sentry/conventions/op` +- [gen_ai attributes](https://conventions.sentry.dev/attributes/gen_ai/) and [gen_ai ops](https://conventions.sentry.dev/ops/#gen_ai) — normative; import from `@sentry/conventions/attributes` and `@sentry/conventions/op` - [RFC 0153](https://github.com/getsentry/rfcs/blob/main/text/0153-decoupling-sentrys-generative-ai-conventions-from-open-telemetry.md) — why Sentry's gen-AI conventions diverge from the [OTel gen-ai semconv](https://opentelemetry.io/docs/specs/semconv/gen-ai/) Derive the op with `getGenAiSpanOp()` from `ai/core/utils.ts` rather than picking one by hand. `ai/core/gen-ai-attributes.ts` is for gap-fillers only — keys with no `@sentry/conventions` equivalent — so check it last, not first. diff --git a/.agents/skills/port-span-names/SKILL.md b/.agents/skills/port-span-names/SKILL.md index f6f35d0c7bcb..930afa8bce7a 100644 --- a/.agents/skills/port-span-names/SKILL.md +++ b/.agents/skills/port-span-names/SKILL.md @@ -6,7 +6,7 @@ argument-hint: ' [constraints] # e.g. navigation, or "db.query --only # Port a span op to low-cardinality span names -Span names must be low cardinality, per the [Sentry span name conventions](https://getsentry.github.io/sentry-conventions/names/): a raw URL, id, or query must never end up in a span name. Where the SDK has no low-cardinality value for a span, it uses a **static fallback name** for that op instead. +Span names must be low cardinality, per the [Sentry span name conventions](https://conventions.sentry.dev/names/): a raw URL, id, or query must never end up in a span name. Where the SDK has no low-cardinality value for a span, it uses a **static fallback name** for that op instead. This only applies when span streaming is enabled. With `traceLifecycle: 'static'` every span name must stay byte-identical to before. @@ -37,13 +37,13 @@ These are non-negotiable. Every one of them was arrived at by rejecting the alte ## 1. Look up the convention -Read and find the op. Each op lists attribute templates in priority order, ending in a static fallback — that fallback is your name. Examples: `pageload` → `Pageload`, `navigation` → `Navigation`, database ops → `Database operation`. +Read and find the op. Each op lists attribute templates in priority order, ending in a static fallback — that fallback is your name. Examples: `pageload` → `Pageload`, `navigation` → `Navigation`, database ops → `Database operation`. Add it next to `PAGELOAD_SPAN_NAME_FALLBACK` in `packages/core/src/tracing/spans/spanNames.ts` and export it from `shared-exports.ts`. Every package imports it from `@sentry/core` directly — no re-export from `@sentry/browser` is needed. ### Then look up the description rules -The name is only half the contract. Relay re-derives a span's **description** from its attributes using the [span description rules](https://getsentry.github.io/sentry-conventions/descriptions/) — a separate, much shorter set of templates from the name rules. `function`, for example, has exactly one (`{{code.function.name}}`) and no static fallback, so a `function` span with no `code.function.name` gets no inferred description at all. +The name is only half the contract. Relay re-derives a span's **description** from its attributes using the [span description rules](https://conventions.sentry.dev/descriptions/) — a separate, much shorter set of templates from the name rules. `function`, for example, has exactly one (`{{code.function.name}}`) and no static fallback, so a `function` span with no `code.function.name` gets no inferred description at all. Renaming a span therefore drops information unless you check what the op's description template can still produce. For each site, in this order: diff --git a/MIGRATION.md b/MIGRATION.md index 9785e86fd6a8..9bde06ab53f1 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -1013,7 +1013,7 @@ The process still exits with code `1` and the reason is still written to `stderr Affected SDKs: All SDKs. -With [span streaming](#span-streaming-is-now-the-default) enabled (the default), span names are now **low cardinality**, following the [Sentry span name conventions](https://getsentry.github.io/sentry-conventions/names/). +With [span streaming](#span-streaming-is-now-the-default) enabled (the default), span names are now **low cardinality**, following the [Sentry span name conventions](https://conventions.sentry.dev/names/). If you [opt out of span streaming](#opting-out-of-span-streaming), span names remain unchanged. diff --git a/packages/core/src/integrations/supabase.ts b/packages/core/src/integrations/supabase.ts index 16b6f95588b7..0b6b7ab22bca 100644 --- a/packages/core/src/integrations/supabase.ts +++ b/packages/core/src/integrations/supabase.ts @@ -283,7 +283,7 @@ function instrumentAuthOperation(operation: AuthOperationFn, isAdmin = false): A // operation that internally makes the respective request to the database. // So I think we can interpret this as a "db.query.summary"-esque span name. // Either way, it's definitely low-cardinality. - // see: https://getsentry.github.io/sentry-conventions/names/#db-queries + // see: https://conventions.sentry.dev/names/#db-queries operationName : // This name makes little sense semantically but preserving it for now to // avoid a breaking change in the transaction path. Will be removed once we remove diff --git a/packages/core/src/tracing/spans/spanNames.ts b/packages/core/src/tracing/spans/spanNames.ts index da9c2d581854..4815d4ded60c 100644 --- a/packages/core/src/tracing/spans/spanNames.ts +++ b/packages/core/src/tracing/spans/spanNames.ts @@ -20,194 +20,194 @@ import { /** * Fallback name for pageload spans when no better-suited span name is available. - * @see https://getsentry.github.io/sentry-conventions/names/#browser-pageload + * @see https://conventions.sentry.dev/names/#browser-pageload */ export const PAGELOAD_SPAN_NAME_FALLBACK = 'Pageload'; /** * Fallback name for navigation spans when no better-suited span name is available. - * @see https://getsentry.github.io/sentry-conventions/names/#browser-navigation + * @see https://conventions.sentry.dev/names/#browser-navigation */ export const NAVIGATION_SPAN_NAME_FALLBACK = 'Navigation'; /** * Fallback name for db spans when no better-suited span name is available. - * @see https://getsentry.github.io/sentry-conventions/names/#db-queries + * @see https://conventions.sentry.dev/names/#db-queries */ export const DB_SPAN_NAME_FALLBACK = 'Database operation'; /** * Fallback name for gen_ai agent spans when no better-suited span name is available. - * @see https://getsentry.github.io/sentry-conventions/names/#gen_ai-agent + * @see https://conventions.sentry.dev/names/#gen_ai-agent */ export const GEN_AI_AGENT_SPAN_NAME_FALLBACK = 'Generative AI agent operation'; /** * Fallback name for gen_ai model spans when no better-suited span name is available. - * @see https://getsentry.github.io/sentry-conventions/names/#gen_ai-inference + * @see https://conventions.sentry.dev/names/#gen_ai-inference */ export const GEN_AI_INFERENCE_SPAN_NAME_FALLBACK = 'Generative AI model operation'; /** * Fallback name for graphql spans when no better-suited span name is available. - * @see https://getsentry.github.io/sentry-conventions/names/#graphql-graphql + * @see https://conventions.sentry.dev/names/#graphql-graphql */ export const GRAPHQL_SPAN_NAME_FALLBACK = 'GraphQL Operation'; /** * Fallback name for http.(client|server) spans when no better-suited span name is available. - * @see https://getsentry.github.io/sentry-conventions/names/#http + * @see https://conventions.sentry.dev/names/#http */ export const HTTP_SPAN_NAME_FALLBACK = 'HTTP'; /** * Fallback name for messaging spans when no better-suited span name is available. - * @see https://getsentry.github.io/sentry-conventions/names/#messaging + * @see https://conventions.sentry.dev/names/#messaging */ export const MESSAGING_SPAN_NAME_FALLBACK = 'Messaging'; /** * Fallback name for mcp server spans when no better-suited span name is available. - * @see https://getsentry.github.io/sentry-conventions/names/#mcp-server + * @see https://conventions.sentry.dev/names/#mcp-server */ export const MCP_SERVER_SPAN_NAME_FALLBACK = 'MCP server operation'; /** * Fallback name for mcp notification spans when no better-suited span name is available. - * @see https://getsentry.github.io/sentry-conventions/names/#mcp-notification + * @see https://conventions.sentry.dev/names/#mcp-notification */ export const MCP_NOTIFICATION_SPAN_NAME_FALLBACK = 'MCP notification'; /** * Fallback name for resource spans when no better-suited span name is available. - * @see https://getsentry.github.io/sentry-conventions/names/#resource-resources + * @see https://conventions.sentry.dev/names/#resource-resources */ export const RESOURCE_SPAN_NAME_FALLBACK = 'Resource'; /** * Fallback name for router spans when no better-suited span name is available. - * @see https://getsentry.github.io/sentry-conventions/names/#routing-router + * @see https://conventions.sentry.dev/names/#routing-router */ export const ROUTER_SPAN_NAME_FALLBACK = 'Router'; /** * Fallback name for request handler spans when no better-suited span name is available. - * @see https://getsentry.github.io/sentry-conventions/names/#web_server-request-handler + * @see https://conventions.sentry.dev/names/#web_server-request-handler */ export const REQUEST_HANDLER_SPAN_NAME_FALLBACK = 'Request handler'; /** * Fallback name for serverless function execution spans when no better-suited span name is available. - * @see https://getsentry.github.io/sentry-conventions/names/#faas-serverless-function-execution + * @see https://conventions.sentry.dev/names/#faas-serverless-function-execution */ export const SERVERLESS_FUNCTION_SPAN_NAME_FALLBACK = 'Serverless function execution'; /** * Fallback name for function execution spans when no better-suited span name is available. - * @see https://getsentry.github.io/sentry-conventions/names/#function + * @see https://conventions.sentry.dev/names/#function */ export const FUNCTION_SPAN_NAME_FALLBACK = 'Function execution'; /** * Fallback name for ui.mount spans when no better-suited span name is available. - * @see https://getsentry.github.io/sentry-conventions/names/#ui-component-mount + * @see https://conventions.sentry.dev/names/#ui-component-mount */ export const UI_MOUNT_SPAN_NAME_FALLBACK = 'Component mount'; /** * Fallback name for ui.update spans when no better-suited span name is available. - * @see https://getsentry.github.io/sentry-conventions/names/#ui-component-update + * @see https://conventions.sentry.dev/names/#ui-component-update */ export const UI_UPDATE_SPAN_NAME_FALLBACK = 'Component update'; /** * Fallback name for ui.render spans when no better-suited span name is available. - * @see https://getsentry.github.io/sentry-conventions/names/#ui-component-render + * @see https://conventions.sentry.dev/names/#ui-component-render */ export const UI_RENDER_SPAN_NAME_FALLBACK = 'Component render'; /** * Fallback name for ui.unmount spans when no better-suited span name is available. - * @see https://getsentry.github.io/sentry-conventions/names/#ui-component-unmount + * @see https://conventions.sentry.dev/names/#ui-component-unmount */ export const UI_UNMOUNT_SPAN_NAME_FALLBACK = 'Component unmount'; /** * Fallback name for ui.resolve spans when no better-suited span name is available. - * @see https://getsentry.github.io/sentry-conventions/names/#ui-component-resolve + * @see https://conventions.sentry.dev/names/#ui-component-resolve */ export const UI_RESOLVE_SPAN_NAME_FALLBACK = 'Component resolve'; /** * Fallback name for ui.task spans when no better-suited span name is available. - * @see https://getsentry.github.io/sentry-conventions/names/#ui-ui-task + * @see https://conventions.sentry.dev/names/#ui-ui-task */ export const UI_TASK_SPAN_NAME_FALLBACK = 'UI task'; /** * Fallback name for ui.long_task and ui.long_animation_frame spans when no better-suited span name is available. - * @see https://getsentry.github.io/sentry-conventions/names/#ui-main-ui-thread-blocked + * @see https://conventions.sentry.dev/names/#ui-main-ui-thread-blocked */ export const UI_LONG_TASK_SPAN_NAME_FALLBACK = 'Main UI thread blocked'; /** * Fallback name for ui.action spans when no better-suited span name is available. - * @see https://getsentry.github.io/sentry-conventions/names/#ui-ui-action + * @see https://conventions.sentry.dev/names/#ui-ui-action */ export const UI_ACTION_SPAN_NAME_FALLBACK = 'UI action'; /** * Fallback name for ui.action.click spans when no better-suited span name is available. - * @see https://getsentry.github.io/sentry-conventions/names/#ui-click-action + * @see https://conventions.sentry.dev/names/#ui-click-action */ export const UI_ACTION_CLICK_SPAN_NAME_FALLBACK = 'Click'; /** * Fallback name for ui.interaction.click spans when no better-suited span name is available. - * @see https://getsentry.github.io/sentry-conventions/names/#ui-click-interaction + * @see https://conventions.sentry.dev/names/#ui-click-interaction */ export const UI_INTERACTION_CLICK_SPAN_NAME_FALLBACK = 'Click'; /** * Fallback name for ui.interaction.hover spans when no better-suited span name is available. - * @see https://getsentry.github.io/sentry-conventions/names/#ui-hover-interaction + * @see https://conventions.sentry.dev/names/#ui-hover-interaction */ export const UI_INTERACTION_HOVER_SPAN_NAME_FALLBACK = 'Hover'; /** * Fallback name for ui.interaction.drag spans when no better-suited span name is available. - * @see https://getsentry.github.io/sentry-conventions/names/#ui-drag-interaction + * @see https://conventions.sentry.dev/names/#ui-drag-interaction */ export const UI_INTERACTION_DRAG_SPAN_NAME_FALLBACK = 'Drag'; /** * Fallback name for ui.interaction.press spans when no better-suited span name is available. - * @see https://getsentry.github.io/sentry-conventions/names/#ui-key-press-interaction + * @see https://conventions.sentry.dev/names/#ui-key-press-interaction */ export const UI_INTERACTION_PRESS_SPAN_NAME_FALLBACK = 'Key press'; /** * Fallback name for ui.webvital.lcp spans when no better-suited span name is available. - * @see https://getsentry.github.io/sentry-conventions/names/#ui-largest-contentful-paint + * @see https://conventions.sentry.dev/names/#ui-largest-contentful-paint */ export const UI_WEBVITAL_LCP_SPAN_NAME_FALLBACK = 'Largest contentful paint'; /** * Fallback name for ui.webvital.cls spans when no better-suited span name is available. - * @see https://getsentry.github.io/sentry-conventions/names/#ui-layout-shift + * @see https://conventions.sentry.dev/names/#ui-layout-shift */ export const UI_WEBVITAL_CLS_SPAN_NAME_FALLBACK = 'Layout shift'; /** * Fallback name for generic ui spans when no better-suited span name is available. - * @see https://getsentry.github.io/sentry-conventions/names/#ui-ui + * @see https://conventions.sentry.dev/names/#ui-ui */ export const UI_SPAN_NAME_FALLBACK = 'UI'; /** * The `cache.operation` attribute value each cache op carries. Cache span names are * `cache.{{cache.operation}}`, so the op constant itself doubles as the low-cardinality span name. - * @see https://getsentry.github.io/sentry-conventions/names/#cache + * @see https://conventions.sentry.dev/names/#cache */ export const CACHE_OPERATION_NAMES = { [CACHE_GET]: 'get', @@ -218,7 +218,7 @@ export const CACHE_OPERATION_NAMES = { /** * Span names for the browser navigation timing ops, keyed by op. None of these ops has an attribute * template, so the static name is the only name they can get. - * @see https://getsentry.github.io/sentry-conventions/names/#browser-navigation-timing + * @see https://conventions.sentry.dev/names/#browser-navigation-timing */ export const BROWSER_NAVIGATION_TIMING_SPAN_NAMES = { [BROWSER_CACHE]: 'Cache lookup', diff --git a/packages/core/src/utils/request.ts b/packages/core/src/utils/request.ts index 7c92511185ab..82c7135fb2ac 100644 --- a/packages/core/src/utils/request.ts +++ b/packages/core/src/utils/request.ts @@ -274,8 +274,8 @@ function getAbsoluteUrl({ * @see https://opentelemetry.io/docs/specs/semconv/registry/attributes/http/#http-request-header * @see https://opentelemetry.io/docs/specs/semconv/registry/attributes/http/#http-response-header * - * @see https://getsentry.github.io/sentry-conventions/attributes/http/#http-request-header-key - * @see https://getsentry.github.io/sentry-conventions/attributes/http/#http-response-header-key + * @see https://conventions.sentry.dev/attributes/http/#http-request-header-key + * @see https://conventions.sentry.dev/attributes/http/#http-response-header-key */ export function httpHeadersToSpanAttributes( headers: Record, diff --git a/packages/nuxt/src/runtime/hooks/updateRouteBeforeResponse.ts b/packages/nuxt/src/runtime/hooks/updateRouteBeforeResponse.ts index 515b5350880c..5a448a8665ca 100644 --- a/packages/nuxt/src/runtime/hooks/updateRouteBeforeResponse.ts +++ b/packages/nuxt/src/runtime/hooks/updateRouteBeforeResponse.ts @@ -46,7 +46,7 @@ export function updateRouteBeforeResponse(event: EventWithMatchedRoute): void { if (isObjectLike(params)) { Object.entries(params).forEach(([key, value]) => { - // Based on this convention: https://getsentry.github.io/sentry-conventions/generated/attributes/url.html#urlpathparameterkey + // Based on this convention: https://conventions.sentry.dev/attributes/url/#url-path-parameter-key rootSpan.setAttributes({ [`url.path.parameter.${key}`]: String(value), [`params.${key}`]: String(value), diff --git a/packages/server-utils/src/ai/mastra/utils.ts b/packages/server-utils/src/ai/mastra/utils.ts index 5fa9f1b62316..3f6d32ed8424 100644 --- a/packages/server-utils/src/ai/mastra/utils.ts +++ b/packages/server-utils/src/ai/mastra/utils.ts @@ -57,7 +57,7 @@ export function getOperation(spanType: MastraSpanType): { op: string; operationN /** * `{operation} {identifier}` per the gen_ai name templates. Mastra's own span name is never used. - * https://getsentry.github.io/sentry-conventions/names/ + * https://conventions.sentry.dev/names/ */ export function getSpanName(span: MastraExportedSpan): string { const operationName = getOperation(span.type)?.operationName ?? span.type; diff --git a/packages/server-utils/src/integrations/nitro/captureTracingEvents.ts b/packages/server-utils/src/integrations/nitro/captureTracingEvents.ts index 800acc5b30ca..938590229708 100644 --- a/packages/server-utils/src/integrations/nitro/captureTracingEvents.ts +++ b/packages/server-utils/src/integrations/nitro/captureTracingEvents.ts @@ -301,7 +301,7 @@ function setParameterizedRouteAttributes(span: Span, event: NitroH3Event): void if (isObjectLike(params)) { Object.entries(params).forEach(([key, value]) => { - // Based on this convention: https://getsentry.github.io/sentry-conventions/generated/attributes/url.html#urlpathparameterkey + // Based on this convention: https://conventions.sentry.dev/attributes/url/#url-path-parameter-key rootSpan.setAttributes({ [`url.path.parameter.${key}`]: String(value), [`params.${key}`]: String(value),