feat(core): Deprecate op span start option

`op` duplicates the `sentry.op` span attribute, which is the canonical way to categorize a span. It
will be removed in a future version; the deprecation deliberately does not name a specific one.

All internal usages are rewritten to set `sentry.op` (via the `SENTRY_OP` constant from
`@sentry/conventions`) instead. Precedence is unchanged everywhere: an explicit `sentry.op` attribute
still wins over `op`. Call sites that already set both now only set the attribute.

`browserTracingIntegration` is the one exception that still touches `op`: `beforeStartSpan` is a
public hook that receives and may override it, so the option is kept in the options handed to the
hook and only folded into `sentry.op` afterwards.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: Lms24

packages/astro/src/server/middleware.ts

@@ -108,7 +108,7 @@ export const handleRequest: (options?: MiddlewareOptions) => MiddlewareHandler =
     const rootSpan = activeSpan ? getRootSpan(activeSpan) : undefined;
 
     // if there is an active span, we just want to enhance it with routing data etc.
-    if (rootSpan && spanToJSON(rootSpan).attributes[SENTRY_OP] === 'http.server') {
+    if (rootSpan && spanToJSON(rootSpan).attributes[SENTRY_OP] === HTTP_SERVER) {
       return enhanceHttpServerSpan(ctx, next, rootSpan);
     }
 
@@ -252,7 +252,10 @@ async function instrumentRequestStartHttpServerSpan(
 
           const res = await startSpan(
             {
-              attributes,
+              attributes: {
+                [SENTRY_OP]: HTTP_SERVER,
+                ...attributes,
+              },
               name,
             },
             async span => {

packages/browser-utils/src/performance/entries.ts

@@ -118,8 +118,8 @@ export function startTrackingLongTasks(): void {
 
       startAndEndSpan(parent, startTime, startTime + duration, {
         name: 'Main UI thread blocked',
-        op: UI_LONG_TASK,
         attributes: {
+          [SENTRY_OP]: UI_LONG_TASK,
           [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.ui.browser.metrics',
         },
       });
@@ -161,6 +161,7 @@ export function startTrackingLongAnimationFrames(): void {
       const duration = msToSec(entry.duration);
 
       const attributes: SpanAttributes = {
+        [SENTRY_OP]: UI_LONG_ANIMATION_FRAME,
         [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.ui.browser.metrics',
       };
 
@@ -180,7 +181,6 @@ export function startTrackingLongAnimationFrames(): void {
 
       startAndEndSpan(parent, startTime, startTime + duration, {
         name: 'Main UI thread blocked',
-        op: UI_LONG_ANIMATION_FRAME,
         attributes,
       });
     }
@@ -464,7 +464,11 @@ export function _addResourceSpans(
     ['deliveryType', 'http.response_delivery_type'],
   ]);
 
-  const attributesWithResourceTiming: SpanAttributes = { ...attributes, ...resourceTimingToSpanAttributes(entry) };
+  const attributesWithResourceTiming: SpanAttributes = {
+    [SENTRY_OP]: op,
+    ...attributes,
+    ...resourceTimingToSpanAttributes(entry),
+  };
 
   const startTimestamp = timeOrigin + startTime;
   const endTimestamp = startTimestamp + duration;
@@ -474,7 +478,6 @@ export function _addResourceSpans(
     name: spanStreamingEnabled
       ? domain || RESOURCE_SPAN_NAME_FALLBACK
       : resourceUrl.replace(WINDOW.location.origin, ''),
-    op,
     attributes: attributesWithResourceTiming,
   });
 }

packages/browser-utils/src/performance/userTiming.ts

@@ -116,6 +116,7 @@ export function _addUserTimingSpan(
   const spanEndTimestamp = originalStartTimestamp + duration;
 
   const attributes: SpanAttributes = {
+    [SENTRY_OP]: entry.entryType,
     [SENTRY_ORIGIN]: `auto.browser.user_timing.${entry.entryType}`,
   };
 
@@ -130,7 +131,6 @@ export function _addUserTimingSpan(
   if (spanStartTimestamp <= spanEndTimestamp) {
     startAndEndSpan(parentSpan, spanStartTimestamp, spanEndTimestamp, {
       name: entry.name,
-      op: entry.entryType,
       attributes,
     });
   }

packages/browser/src/tracing/browserTracingIntegration.ts

@@ -331,12 +331,14 @@ export const browserTracingIntegration = ((options: Partial<BrowserTracingOption
 
   /** Create routing idle transaction. */
   function _createRouteSpan(client: Client, startSpanOptions: StartSpanOptions, makeActive = true, url?: string): void {
-    const isPageloadSpan = startSpanOptions.op === 'pageload';
+    const originalOp = startSpanOptions.attributes?.[SENTRY_OP];
+    // backfill top-level `op` option
+    // oxlint-disable-next-line typescript/no-deprecated
+    const optionsWithOp: StartSpanOptions = { op: originalOp, ...startSpanOptions };
+    const isPageloadSpan = originalOp === PAGELOAD;
 
-    const initialSpanName = startSpanOptions.name;
-    const finalStartSpanOptions: StartSpanOptions = beforeStartSpan
-      ? beforeStartSpan(startSpanOptions)
-      : startSpanOptions;
+    const initialSpanName = optionsWithOp.name;
+    const finalStartSpanOptions: StartSpanOptions = beforeStartSpan ? beforeStartSpan(optionsWithOp) : optionsWithOp;
 
     // For navigations, `url` is the destination URL, so we use it to reflect the post-navigation location.
     // For pageloads (and manual navigation spans without a URL) we fall back to the current location.
@@ -348,6 +350,12 @@ export const browserTracingIntegration = ((options: Partial<BrowserTracingOption
       ...finalStartSpanOptions.attributes,
     };
 
+    // oxlint-disable-next-line typescript/no-deprecated
+    if (finalStartSpanOptions.op !== originalOp) {
+      // oxlint-disable-next-line typescript/no-deprecated
+      attributes[SENTRY_OP] = finalStartSpanOptions.op;
+    }
+
     // If `finalStartSpanOptions.name` is different than `startSpanOptions.name`
     // it is because `beforeStartSpan` set a custom name. Therefore we set the source to 'custom'.
     if (initialSpanName !== finalStartSpanOptions.name) {
@@ -485,8 +493,8 @@ export const browserTracingIntegration = ((options: Partial<BrowserTracingOption
           _createRouteSpan(
             client,
             {
-              op: NAVIGATION_REDIRECT,
               ...startSpanOptions,
+              attributes: { [SENTRY_OP]: NAVIGATION_REDIRECT, ...startSpanOptions.attributes },
             },
             false,
             navigationOptions.url,
@@ -517,8 +525,8 @@ export const browserTracingIntegration = ((options: Partial<BrowserTracingOption
         _createRouteSpan(
           client,
           {
-            op: NAVIGATION,
             ...startSpanOptions,
+            attributes: { [SENTRY_OP]: NAVIGATION, ...startSpanOptions.attributes },
             // Navigation starts a new trace and is NOT parented under any active interaction (e.g. ui.action.click)
             parentSpan: null,
           },
@@ -555,8 +563,8 @@ export const browserTracingIntegration = ((options: Partial<BrowserTracingOption
         });
 
         _createRouteSpan(client, {
-          op: PAGELOAD,
           ...startSpanOptions,
+          attributes: { [SENTRY_OP]: PAGELOAD, ...startSpanOptions.attributes },
         });
       });
 

packages/cloudflare/src/instrumentations/instrumentDurableObjectSyncKvStorage.ts

@@ -1,5 +1,5 @@
-import type { SyncKvStorage } from '@cloudflare/workers-types';
 import { SENTRY_OP } from '@sentry/conventions/attributes';
+import type { SyncKvStorage } from '@cloudflare/workers-types';
 import { DB } from '@sentry/conventions/op';
 import { SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN, startSpan } from '@sentry/core';
 

packages/cloudflare/src/instrumentations/instrumentSqlStorage.ts

@@ -1,5 +1,5 @@
-import type { SqlStorage } from '@cloudflare/workers-types';
 import { SENTRY_OP } from '@sentry/conventions/attributes';
+import type { SqlStorage } from '@cloudflare/workers-types';
 import { DB_QUERY } from '@sentry/conventions/op';
 import {
   _INTERNAL_getSqlQuerySummary,

packages/cloudflare/src/instrumentations/worker/instrumentR2.ts

@@ -58,7 +58,6 @@ function createSpanOptions(bindingName: string, r2Op: R2OperationKey, key?: stri
   const requestKey = Array.isArray(key) ? key.join(', ') : typeof key === 'string' ? key : undefined;
 
   return {
-    op,
     name: spanName,
     attributes: {
       [CLOUDFLARE_R2_OPERATION]: operation,

packages/cloudflare/test/instrumentations/worker/instrumentR2.test.ts

@@ -80,7 +80,6 @@ describe('instrumentR2Bucket', () => {
       expect(startSpanSpy).toHaveBeenCalledTimes(1);
       expect(startSpanSpy).toHaveBeenLastCalledWith(
         expect.objectContaining({
-          op: 'object.get',
           name: 'r2_get',
           attributes: expect.objectContaining({
             'cloudflare.r2.operation': 'GetObject',
@@ -112,7 +111,6 @@ describe('instrumentR2Bucket', () => {
       expect(startSpanSpy).toHaveBeenCalledTimes(1);
       expect(startSpanSpy).toHaveBeenLastCalledWith(
         expect.objectContaining({
-          op: 'object.head',
           name: 'r2_head',
           attributes: expect.objectContaining({
             'cloudflare.r2.operation': 'HeadObject',
@@ -142,7 +140,6 @@ describe('instrumentR2Bucket', () => {
       expect(startSpanSpy).toHaveBeenCalledTimes(1);
       expect(startSpanSpy).toHaveBeenLastCalledWith(
         expect.objectContaining({
-          op: 'object.put',
           name: 'r2_put',
           attributes: expect.objectContaining({
             'cloudflare.r2.operation': 'PutObject',
@@ -170,7 +167,6 @@ describe('instrumentR2Bucket', () => {
       expect(startSpanSpy).toHaveBeenCalledTimes(1);
       expect(startSpanSpy).toHaveBeenLastCalledWith(
         expect.objectContaining({
-          op: 'object.delete',
           name: 'r2_delete',
           attributes: expect.objectContaining({
             'cloudflare.r2.operation': 'DeleteObject',
@@ -206,7 +202,6 @@ describe('instrumentR2Bucket', () => {
       expect(startSpanSpy).toHaveBeenCalledTimes(1);
       expect(startSpanSpy).toHaveBeenLastCalledWith(
         expect.objectContaining({
-          op: 'object.list',
           name: 'r2_list',
           attributes: expect.objectContaining({
             'cloudflare.r2.operation': 'ListObjects',
@@ -236,11 +231,11 @@ describe('instrumentR2Bucket', () => {
       expect(startSpanSpy).toHaveBeenCalledTimes(1);
       expect(startSpanSpy).toHaveBeenLastCalledWith(
         expect.objectContaining({
-          op: 'object.multipart_upload.create',
           name: 'r2_createMultipartUpload',
           attributes: expect.objectContaining({
             'cloudflare.r2.operation': 'CreateMultipartUpload',
             'cloudflare.r2.request.key': 'big-file.bin',
+            'sentry.op': 'object.multipart_upload.create',
           }),
         }),
         expect.any(Function),

packages/core/src/integrations/mcp-server/spans.ts

@@ -212,6 +212,7 @@ export function buildMcpServerSpanConfig(
 
   return {
     name: spanName,
+    // oxlint-disable-next-line typescript/no-deprecated
     forceTransaction: true,
     attributes,
   };

packages/core/src/tracing/trace.ts

@@ -445,8 +445,10 @@ function parseSentrySpanArguments(options: StartSpanOptions): SentrySpanArgument
 
   // Fold `op` into the attributes up front so samplers see `sentry.op`; the `SentrySpan`
   // constructor only adds it after the sampling decision. An explicit `sentry.op` attribute wins.
+  // oxlint-disable-next-line typescript/no-deprecated
   if (options.op) {
     initialCtx.attributes = {
+      // oxlint-disable-next-line typescript/no-deprecated
       [SEMANTIC_ATTRIBUTE_SENTRY_OP]: options.op,
       ...options.attributes,
     };