add tracestate property to Transaction class

Author: lobsterkatie

packages/tracing/src/transaction.ts

@@ -3,6 +3,7 @@ import { Event, Measurements, Transaction as TransactionInterface, TransactionCo
 import { dropUndefinedKeys, isInstanceOf, logger } from '@sentry/utils';
 
 import { Span as SpanClass, SpanRecorder } from './span';
+import { computeTracestateValue } from './utils';
 
 interface TransactionMetadata {
   transactionSampling?: { [key: string]: string | number };
@@ -12,6 +13,8 @@ interface TransactionMetadata {
 export class Transaction extends SpanClass implements TransactionInterface {
   public name: string;
 
+  public readonly tracestate: string;
+
   private _metadata: TransactionMetadata = {};
 
   private _measurements: Measurements = {};
@@ -41,6 +44,10 @@ export class Transaction extends SpanClass implements TransactionInterface {
 
     this._trimEnd = transactionContext.trimEnd;
 
+    // _getNewTracestate only returns undefined in the absence of a client or dsn, in which case it doesn't matter what
+    // the header values are - nothing can be sent anyway - so the third alternative here is just to make TS happy
+    this.tracestate = transactionContext.tracestate || this._getNewTracestate() || 'things are broken';
+
     // this is because transactions are also spans, and spans have a transaction pointer
     this.transaction = this;
   }
@@ -161,4 +168,27 @@ export class Transaction extends SpanClass implements TransactionInterface {
 
     return this;
   }
+
+  /**
+   * Create a new tracestate header value
+   *
+   * @returns The new tracestate value, or undefined if there's no client or no dsn
+   */
+  private _getNewTracestate(): string | undefined {
+    const client = this._hub.getClient();
+    const dsn = client?.getDsn();
+
+    if (!client || !dsn) {
+      return;
+    }
+
+    const { environment, release } = client.getOptions() || {};
+
+    // TODO - the only reason we need the non-null assertion on `dsn.publicKey` (below) is because `dsn.publicKey` has
+    // to be optional while we transition from `dsn.user` -> `dsn.publicKey`. Once `dsn.user` is removed, we can make
+    // `dsn.publicKey` required and remove the `!`.
+
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    return computeTracestateValue({ trace_id: this.traceId, environment, release, public_key: dsn.publicKey! });
+  }
 }

packages/tracing/src/utils.ts

@@ -1,5 +1,6 @@
 import { getCurrentHub, Hub } from '@sentry/hub';
 import { Options, TraceparentData, Transaction } from '@sentry/types';
+import { SentryError, unicodeToBase64 } from '@sentry/utils';
 
 export const TRACEPARENT_REGEXP = new RegExp(
   '^[ \\t]*' + // whitespace
@@ -66,3 +67,35 @@ export function secToMs(time: number): number {
 
 // so it can be used in manual instrumentation without necessitating a hard dependency on @sentry/utils
 export { stripUrlQueryAndFragment } from '@sentry/utils';
+
+/**
+ * Compute the value of a tracestate header.
+ *
+ * @throws SentryError (because using the logger creates a circular dependency)
+ * @returns the base64-encoded header value
+ */
+// Note: this is here instead of in the tracing package since @sentry/core tests rely on it
+export function computeTracestateValue(tracestateData: {
+  trace_id: string;
+  environment: string | undefined | null;
+  release: string | undefined | null;
+  public_key: string;
+}): string {
+  // `JSON.stringify` will drop keys with undefined values, but not ones with null values
+  tracestateData.environment = tracestateData.environment || null;
+  tracestateData.release = tracestateData.release || null;
+
+  // See https://www.w3.org/TR/trace-context/#tracestate-header-field-values
+  // The spec for tracestate header values calls for a string of the form
+  //
+  //    identifier1=value1,identifier2=value2,...
+  //
+  // which means the value can't include any equals signs, since they already have meaning. Equals signs are commonly
+  // used to pad the end of base64 values though, so to avoid confusion, we strip them off. (Most languages' base64
+  // decoding functions (including those in JS) are able to function without the padding.)
+  try {
+    return unicodeToBase64(JSON.stringify(tracestateData)).replace(/={1,2}$/, '');
+  } catch (err) {
+    throw new SentryError(`[Tracing] Error creating tracestate header: ${err}`);
+  }
+}

packages/tracing/test/hub.test.ts

@@ -1,6 +1,6 @@
 /* eslint-disable @typescript-eslint/unbound-method */
-import { BrowserClient } from '@sentry/browser';
-import { Hub } from '@sentry/hub';
+import { BrowserClient, init as initSDK } from '@sentry/browser';
+import { getCurrentHub, Hub } from '@sentry/hub';
 import * as hubModule from '@sentry/hub';
 import { TransactionSamplingMethod } from '@sentry/types';
 import * as utilsModule from '@sentry/utils'; // for mocking
@@ -9,7 +9,7 @@ import { logger } from '@sentry/utils';
 import { BrowserTracing } from '../src/browser/browsertracing';
 import { addExtensionMethods } from '../src/hubextensions';
 import { Transaction } from '../src/transaction';
-import { extractTraceparentData, TRACEPARENT_REGEXP } from '../src/utils';
+import { computeTracestateValue, extractTraceparentData, TRACEPARENT_REGEXP } from '../src/utils';
 import { addDOMPropertiesToGlobal, getSymbolObjectKeyByName, testOnlyIfNodeVersionAtLeast } from './testutils';
 
 addExtensionMethods();
@@ -29,6 +29,61 @@ describe('Hub', () => {
     jest.clearAllMocks();
   });
 
+  describe('transaction creation', () => {
+    it('uses inherited values when given in transaction context', () => {
+      const transactionContext = {
+        name: 'dogpark',
+        traceId: '12312012123120121231201212312012',
+        parentSpanId: '1121201211212012',
+        tracestate: 'doGsaREgReaT',
+      };
+      const hub = new Hub(new BrowserClient({ tracesSampleRate: 1 }));
+      const transaction = hub.startTransaction(transactionContext);
+
+      expect(transaction).toEqual(expect.objectContaining(transactionContext));
+    });
+
+    it('creates a new tracestate value if not given one in transaction context', () => {
+      const environment = 'dogpark';
+      const release = 'off.leash.park';
+      const hub = new Hub(
+        new BrowserClient({
+          dsn: 'https://[email protected]/12312012',
+          release,
+          environment,
+        }),
+      );
+      const transaction = hub.startTransaction({ name: 'FETCH /ball' });
+
+      const b64Value = computeTracestateValue({
+        trace_id: transaction.traceId,
+        environment,
+        release,
+        public_key: 'dogsarebadatkeepingsecrets',
+      });
+
+      expect(transaction.tracestate).toEqual(b64Value);
+    });
+
+    it('uses default environment if none given', () => {
+      const release = 'off.leash.park';
+      initSDK({
+        dsn: 'https://[email protected]/12312012',
+        release,
+      });
+      const transaction = getCurrentHub().startTransaction({ name: 'FETCH /ball' });
+
+      const b64Value = computeTracestateValue({
+        trace_id: transaction.traceId,
+        environment: 'production',
+        release,
+        public_key: 'dogsarebadatkeepingsecrets',
+      });
+
+      expect(transaction.tracestate).toEqual(b64Value);
+    });
+  });
+
   describe('getTransaction()', () => {
     it('should find a transaction which has been set on the scope if sampled = true', () => {
       const hub = new Hub(new BrowserClient({ tracesSampleRate: 1 }));

packages/types/src/transaction.ts

@@ -22,6 +22,12 @@ export interface TransactionContext extends SpanContext {
    * If this transaction has a parent, the parent's sampling decision
    */
   parentSampled?: boolean;
+
+  /**
+   * The tracestate header value associated with this transaction, potentially inherited from a parent transaction,
+   * which will be propagated across services to all child transactions
+   */
+  tracestate?: string;
 }
 
 /**