ref(span): deprecate span status enum

Author: JonasBa

packages/node/test/handlers.test.ts

@@ -1,7 +1,7 @@
 import * as sentryCore from '@sentry/core';
 import { Hub } from '@sentry/hub';
 import * as sentryHub from '@sentry/hub';
-import { SpanStatus, Transaction } from '@sentry/tracing';
+import { Transaction } from '@sentry/tracing';
 import { RequestSessionStatus, Runtime } from '@sentry/types';
 import * as http from 'http';
 import * as net from 'net';
@@ -403,7 +403,7 @@ describe('tracingHandler', () => {
 
     setImmediate(() => {
       expect(finishTransaction).toHaveBeenCalled();
-      expect(transaction.status).toBe(SpanStatus.Ok);
+      expect(transaction.status).toBe('ok');
       expect(transaction.tags).toEqual(expect.objectContaining({ 'http.status_code': '200' }));
       done();
     });

packages/tracing/src/browser/backgroundtab.ts

@@ -2,7 +2,7 @@ import { getGlobalObject, logger } from '@sentry/utils';
 
 import { FINISH_REASON_TAG, IDLE_TRANSACTION_FINISH_REASONS } from '../constants';
 import { IdleTransaction } from '../idletransaction';
-import { SpanStatus } from '../spanstatus';
+import { SpanStatusType } from '../spanstatus';
 import { getActiveTransaction } from '../utils';
 
 const global = getGlobalObject<Window>();
@@ -16,13 +16,15 @@ export function registerBackgroundTabDetection(): void {
     global.document.addEventListener('visibilitychange', () => {
       const activeTransaction = getActiveTransaction() as IdleTransaction;
       if (global.document.hidden && activeTransaction) {
+        const statusType: SpanStatusType = 'cancelled';
+
         logger.log(
-          `[Tracing] Transaction: ${SpanStatus.Cancelled} -> since tab moved to the background, op: ${activeTransaction.op}`,
+          `[Tracing] Transaction: ${statusType} -> since tab moved to the background, op: ${activeTransaction.op}`,
         );
         // We should not set status if it is already set, this prevent important statuses like
         // error or data loss from being overwritten on transaction.
         if (!activeTransaction.status) {
-          activeTransaction.setStatus(SpanStatus.Cancelled);
+          activeTransaction.setStatus(statusType);
         }
         activeTransaction.setTag('visibilitychange', 'document.hidden');
         activeTransaction.setTag(FINISH_REASON_TAG, IDLE_TRANSACTION_FINISH_REASONS[2]);

packages/tracing/src/browser/browsertracing.ts

@@ -4,7 +4,6 @@ import { getGlobalObject, logger } from '@sentry/utils';
 
 import { startIdleTransaction } from '../hubextensions';
 import { DEFAULT_IDLE_TIMEOUT, IdleTransaction } from '../idletransaction';
-import { SpanStatus } from '../spanstatus';
 import { extractTraceparentData, secToMs } from '../utils';
 import { registerBackgroundTabDetection } from './backgroundtab';
 import { MetricsInstrumentation } from './metrics';
@@ -269,7 +268,7 @@ function adjustTransactionDuration(maxDuration: number, transaction: IdleTransac
   const diff = endTimestamp - transaction.startTimestamp;
   const isOutdatedTransaction = endTimestamp && (diff > maxDuration || diff < 0);
   if (isOutdatedTransaction) {
-    transaction.setStatus(SpanStatus.DeadlineExceeded);
+    transaction.setStatus('deadline_exceeded');
     transaction.setTag('maxTransactionDurationExceeded', 'true');
   }
 }

packages/tracing/src/browser/request.ts

@@ -1,7 +1,6 @@
 import { addInstrumentationHandler, isInstanceOf, isMatchingPattern } from '@sentry/utils';
 
 import { Span } from '../span';
-import { SpanStatus } from '../spanstatus';
 import { getActiveTransaction, hasTracingEnabled } from '../utils';
 
 export const DEFAULT_TRACING_ORIGINS = ['localhost', /^\//];
@@ -156,7 +155,7 @@ export function fetchCallback(
         // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
         span.setHttpStatus(handlerData.response.status);
       } else if (handlerData.error) {
-        span.setStatus(SpanStatus.InternalError);
+        span.setStatus('internal_error');
       }
       span.finish();
 

packages/tracing/src/errors.ts

@@ -1,6 +1,6 @@
 import { addInstrumentationHandler, logger } from '@sentry/utils';
 
-import { SpanStatus } from './spanstatus';
+import { SpanStatusType } from './spanstatus';
 import { getActiveTransaction } from './utils';
 
 /**
@@ -23,7 +23,8 @@ export function registerErrorInstrumentation(): void {
 function errorCallback(): void {
   const activeTransaction = getActiveTransaction();
   if (activeTransaction) {
-    logger.log(`[Tracing] Transaction: ${SpanStatus.InternalError} -> Global error occured`);
-    activeTransaction.setStatus(SpanStatus.InternalError);
+    const status: SpanStatusType = 'internal_error';
+    logger.log(`[Tracing] Transaction: ${status} -> Global error occured`);
+    activeTransaction.setStatus(status);
   }
 }

packages/tracing/src/idletransaction.ts

@@ -4,7 +4,6 @@ import { logger, timestampWithMs } from '@sentry/utils';
 
 import { FINISH_REASON_TAG, IDLE_TRANSACTION_FINISH_REASONS } from './constants';
 import { Span, SpanRecorder } from './span';
-import { SpanStatus } from './spanstatus';
 import { Transaction } from './transaction';
 
 export const DEFAULT_IDLE_TIMEOUT = 1000;
@@ -125,7 +124,7 @@ export class IdleTransaction extends Transaction {
         // We cancel all pending spans with status "cancelled" to indicate the idle transaction was finished early
         if (!span.endTimestamp) {
           span.endTimestamp = endTimestamp;
-          span.setStatus(SpanStatus.Cancelled);
+          span.setStatus('cancelled');
           logger.log('[Tracing] cancelling span since transaction ended early', JSON.stringify(span, undefined, 2));
         }
 
@@ -253,7 +252,7 @@ export class IdleTransaction extends Transaction {
 
     if (this._heartbeatCounter >= 3) {
       logger.log(`[Tracing] Transaction finished because of no change for 3 heart beats`);
-      this.setStatus(SpanStatus.DeadlineExceeded);
+      this.setStatus('deadline_exceeded');
       this.setTag(FINISH_REASON_TAG, IDLE_TRANSACTION_FINISH_REASONS[0]);
       this.finish();
     } else {

packages/tracing/src/index.ts

@@ -29,7 +29,7 @@ export {
   RequestInstrumentationOptions,
   defaultRequestInstrumentationOptions,
 } from './browser';
-export { SpanStatus } from './spanstatus';
+export { SpanStatus, spanStatusfromHttpCode } from './spanstatus';
 export { IdleTransaction } from './idletransaction';
 export { startIdleTransaction } from './hubextensions';
 

packages/tracing/src/span.ts

@@ -2,7 +2,7 @@
 import { Primitive, Span as SpanInterface, SpanContext, Transaction } from '@sentry/types';
 import { dropUndefinedKeys, timestampWithMs, uuid4 } from '@sentry/utils';
 
-import { SpanStatus } from './spanstatus';
+import { spanStatusfromHttpCode, SpanStatusType } from './spanstatus';
 
 /**
  * Keeps track of finished spans for a given transaction
@@ -56,7 +56,7 @@ export class Span implements SpanInterface {
   /**
    * Internal keeper of the status
    */
-  public status?: SpanStatus | string;
+  public status?: SpanStatusType;
 
   /**
    * @inheritDoc
@@ -204,7 +204,7 @@ export class Span implements SpanInterface {
   /**
    * @inheritDoc
    */
-  public setStatus(value: SpanStatus): this {
+  public setStatus(value: SpanStatusType): this {
     this.status = value;
     return this;
   }
@@ -214,8 +214,8 @@ export class Span implements SpanInterface {
    */
   public setHttpStatus(httpStatus: number): this {
     this.setTag('http.status_code', String(httpStatus));
-    const spanStatus = SpanStatus.fromHttpCode(httpStatus);
-    if (spanStatus !== SpanStatus.UnknownError) {
+    const spanStatus = spanStatusfromHttpCode(httpStatus);
+    if (spanStatus !== 'unknown_error') {
       this.setStatus(spanStatus);
     }
     return this;
@@ -225,7 +225,7 @@ export class Span implements SpanInterface {
    * @inheritDoc
    */
   public isSuccess(): boolean {
-    return this.status === SpanStatus.Ok;
+    return this.status === 'ok';
   }
 
   /**

packages/tracing/src/spanstatus.ts

@@ -37,51 +37,84 @@ export enum SpanStatus {
   DataLoss = 'data_loss',
 }
 
-// eslint-disable-next-line @typescript-eslint/no-namespace, import/export
-export namespace SpanStatus {
-  /**
-   * Converts a HTTP status code into a {@link SpanStatus}.
-   *
-   * @param httpStatus The HTTP response status code.
-   * @returns The span status or {@link SpanStatus.UnknownError}.
-   */
-  export function fromHttpCode(httpStatus: number): SpanStatus {
-    if (httpStatus < 400 && httpStatus >= 100) {
-      return SpanStatus.Ok;
-    }
+export type SpanStatusType =
+  /** The operation completed successfully. */
+  | 'ok'
+  /** Deadline expired before operation could complete. */
+  | 'deadline_exceeded'
+  /** 401 Unauthorized (actually does mean unauthenticated according to RFC 7235) */
+  | 'unauthenticated'
+  /** 403 Forbidden */
+  | 'permission_denied'
+  /** 404 Not Found. Some requested entity (file or directory) was not found. */
+  | 'not_found'
+  /** 429 Too Many Requests */
+  | 'resource_exhausted'
+  /** Client specified an invalid argument. 4xx. */
+  | 'invalid_argument'
+  /** 501 Not Implemented */
+  | 'unimplemented'
+  /** 503 Service Unavailable */
+  | 'unavailable'
+  /** Other/generic 5xx. */
+  | 'internal_error'
+  /** Unknown. Any non-standard HTTP status code. */
+  | 'unknown_error'
+  /** The operation was cancelled (typically by the user). */
+  | 'cancelled'
+  /** Already exists (409) */
+  | 'already_exists'
+  /** Operation was rejected because the system is not in a state required for the operation's */
+  | 'failed_precondition'
+  /** The operation was aborted, typically due to a concurrency issue. */
+  | 'aborted'
+  /** Operation was attempted past the valid range. */
+  | 'out_of_range'
+  /** Unrecoverable data loss or corruption */
+  | 'data_loss';
 
-    if (httpStatus >= 400 && httpStatus < 500) {
-      switch (httpStatus) {
-        case 401:
-          return SpanStatus.Unauthenticated;
-        case 403:
-          return SpanStatus.PermissionDenied;
-        case 404:
-          return SpanStatus.NotFound;
-        case 409:
-          return SpanStatus.AlreadyExists;
-        case 413:
-          return SpanStatus.FailedPrecondition;
-        case 429:
-          return SpanStatus.ResourceExhausted;
-        default:
-          return SpanStatus.InvalidArgument;
-      }
-    }
+/**
+ * Converts a HTTP status code into a {@link SpanStatusType}.
+ *
+ * @param httpStatus The HTTP response status code.
+ * @returns The span status or unknown_error.
+ */
+export function spanStatusfromHttpCode(httpStatus: number): SpanStatusType {
+  if (httpStatus < 400 && httpStatus >= 100) {
+    return 'ok';
+  }
 
-    if (httpStatus >= 500 && httpStatus < 600) {
-      switch (httpStatus) {
-        case 501:
-          return SpanStatus.Unimplemented;
-        case 503:
-          return SpanStatus.Unavailable;
-        case 504:
-          return SpanStatus.DeadlineExceeded;
-        default:
-          return SpanStatus.InternalError;
-      }
+  if (httpStatus >= 400 && httpStatus < 500) {
+    switch (httpStatus) {
+      case 401:
+        return 'unauthenticated';
+      case 403:
+        return 'permission_denied';
+      case 404:
+        return 'not_found';
+      case 409:
+        return 'already_exists';
+      case 413:
+        return 'failed_precondition';
+      case 429:
+        return 'resource_exhausted';
+      default:
+        return 'invalid_argument';
     }
+  }
 
-    return SpanStatus.UnknownError;
+  if (httpStatus >= 500 && httpStatus < 600) {
+    switch (httpStatus) {
+      case 501:
+        return 'unimplemented';
+      case 503:
+        return 'unavailable';
+      case 504:
+        return 'deadline_exceeded';
+      default:
+        return 'internal_error';
+    }
   }
+
+  return 'unknown_error';
 }

packages/tracing/test/browser/backgroundtab.test.ts

@@ -2,7 +2,6 @@ import { BrowserClient } from '@sentry/browser';
 import { Hub, makeMain } from '@sentry/hub';
 import { JSDOM } from 'jsdom';
 
-import { SpanStatus } from '../../src';
 import { registerBackgroundTabDetection } from '../../src/browser/backgroundtab';
 
 describe('registerBackgroundTabDetection', () => {
@@ -49,7 +48,7 @@ describe('registerBackgroundTabDetection', () => {
     global.document.hidden = true;
     events.visibilitychange();
 
-    expect(transaction.status).toBe(SpanStatus.Cancelled);
+    expect(transaction.status).toBe('cancelled');
     expect(transaction.tags.visibilitychange).toBe('document.hidden');
     expect(transaction.endTimestamp).toBeDefined();
   });

packages/tracing/test/browser/browsertracing.test.ts

@@ -3,7 +3,6 @@ import { Hub, makeMain } from '@sentry/hub';
 import { getGlobalObject } from '@sentry/utils';
 import { JSDOM } from 'jsdom';
 
-import { SpanStatus } from '../../src';
 import {
   BrowserTracing,
   BrowserTracingOptions,
@@ -273,7 +272,7 @@ describe('BrowserTracing', () => {
         const transaction = getActiveTransaction(hub) as IdleTransaction;
         transaction.finish(transaction.startTimestamp + secToMs(DEFAULT_MAX_TRANSACTION_DURATION_SECONDS) + 1);
 
-        expect(transaction.status).toBe(SpanStatus.DeadlineExceeded);
+        expect(transaction.status).toBe('deadline_exceeded');
         expect(transaction.tags.maxTransactionDurationExceeded).toBeDefined();
       });
 

packages/tracing/test/browser/request.test.ts

@@ -2,7 +2,7 @@ import { BrowserClient } from '@sentry/browser';
 import { Hub, makeMain } from '@sentry/hub';
 import * as utils from '@sentry/utils';
 
-import { Span, SpanStatus, Transaction } from '../../src';
+import { Span, Transaction, spanStatusfromHttpCode } from '../../src';
 import { fetchCallback, FetchData, instrumentOutgoingRequests, xhrCallback, XHRData } from '../../src/browser/request';
 import { addExtensionMethods } from '../../src/hubextensions';
 import * as tracingUtils from '../../src/utils';
@@ -176,7 +176,7 @@ describe('callbacks', () => {
       // triggered by response coming back
       fetchCallback(postRequestFetchHandlerData, alwaysCreateSpan, spans);
 
-      expect(newSpan!.status).toBe(SpanStatus.fromHttpCode(404));
+      expect(newSpan!.status).toBe(spanStatusfromHttpCode(404));
     });
 
     it('adds sentry-trace header to fetch requests', () => {
@@ -267,7 +267,7 @@ describe('callbacks', () => {
       // triggered by response coming back
       xhrCallback(postRequestXHRHandlerData, alwaysCreateSpan, spans);
 
-      expect(newSpan!.status).toBe(SpanStatus.fromHttpCode(404));
+      expect(newSpan!.status).toBe(spanStatusfromHttpCode(404));
     });
   });
 });

packages/tracing/test/errors.test.ts

@@ -1,7 +1,6 @@
 import { BrowserClient } from '@sentry/browser';
 import { Hub, makeMain } from '@sentry/hub';
 
-import { SpanStatus } from '../src';
 import { registerErrorInstrumentation } from '../src/errors';
 import { _addTracingExtensions } from '../src/hubextensions';
 
@@ -71,7 +70,7 @@ describe('registerErrorHandlers()', () => {
     hub.configureScope(scope => scope.setSpan(transaction));
 
     mockErrorCallback();
-    expect(transaction.status).toBe(SpanStatus.InternalError);
+    expect(transaction.status).toBe('internal_error');
 
     transaction.finish();
   });
@@ -82,7 +81,7 @@ describe('registerErrorHandlers()', () => {
     hub.configureScope(scope => scope.setSpan(transaction));
 
     mockUnhandledRejectionCallback();
-    expect(transaction.status).toBe(SpanStatus.InternalError);
+    expect(transaction.status).toBe('internal_error');
     transaction.finish();
   });
 });