add functions for computing tracestate and combined tracing headers

Author: lobsterkatie

packages/tracing/src/span.ts

@@ -1,8 +1,10 @@
 /* eslint-disable max-lines */
-import { Primitive, Span as SpanInterface, SpanContext, Transaction } from '@sentry/types';
-import { dropUndefinedKeys, timestampWithMs, uuid4 } from '@sentry/utils';
+import { getCurrentHub, Hub } from '@sentry/hub';
+import { Primitive, Span as SpanInterface, SpanContext, TraceHeaders, Transaction } from '@sentry/types';
+import { dropUndefinedKeys, logger, timestampWithMs, uuid4 } from '@sentry/utils';
 
 import { SpanStatus } from './spanstatus';
+import { computeTracestateValue } from './utils';
 
 /**
  * Keeps track of finished spans for a given transaction
@@ -284,6 +286,26 @@ export class Span implements SpanInterface {
     return this;
   }
 
+  /**
+   * @inheritDoc
+   */
+  public getTraceHeaders(): TraceHeaders {
+    // if this span is part of a transaction, but that transaction doesn't yet have a tracestate value, create one
+    if (this.transaction && !this.transaction?.metadata.tracestate?.sentry) {
+      this.transaction.metadata.tracestate = {
+        ...this.transaction.metadata.tracestate,
+        sentry: this._getNewTracestate(),
+      };
+    }
+
+    const tracestate = this._toTracestate();
+
+    return {
+      'sentry-trace': this._toSentrytrace(),
+      ...(tracestate && { tracestate }),
+    };
+  }
+
   /**
    * @inheritDoc
    */
@@ -339,4 +361,67 @@ export class Span implements SpanInterface {
       trace_id: this.traceId,
     });
   }
+
+  /**
+   * Create a new Sentry tracestate header entry (i.e. `sentry=xxxxxx`)
+   *
+   * @returns The new Sentry tracestate entry, or undefined if there's no client or no dsn
+   */
+  protected _getNewTracestate(): string | undefined {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-explicit-any
+    const hub = ((this.transaction as any)?._hub as Hub) || getCurrentHub();
+    const client = hub.getClient();
+    const { id: userId, segment: userSegment } = hub.getScope()?.getUser() || {};
+    const dsn = client?.getDsn();
+
+    if (!client || !dsn) {
+      return;
+    }
+
+    const { environment, release } = client.getOptions() || {};
+
+    // only define a `user` object if there's going to be something in it (note: prettier insists on removing the
+    // parentheses, but since it's easy to misinterpret this, imagine `()` around `userId || userSegment`)
+    const user = userId || userSegment ? { id: userId, segment: userSegment } : undefined;
+
+    // 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 `!`.
+
+    return `sentry=${computeTracestateValue({
+      trace_id: this.traceId,
+      environment,
+      release,
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      public_key: dsn.publicKey!,
+      user,
+    })}`;
+  }
+
+  /**
+   * Return a traceparent-compatible header string.
+   */
+  private _toSentrytrace(): string {
+    let sampledString = '';
+    if (this.sampled !== undefined) {
+      sampledString = this.sampled ? '-1' : '-0';
+    }
+    return `${this.traceId}-${this.spanId}${sampledString}`;
+  }
+
+  /**
+   * Return a tracestate-compatible header string, including both sentry and third-party data (if any). Returns
+   * undefined if there is no client or no DSN.
+   */
+  private _toTracestate(): string | undefined {
+    // if this is an orphan span, create a new tracestate value
+    const sentryTracestate = this.transaction?.metadata?.tracestate?.sentry || this._getNewTracestate();
+    let thirdpartyTracestate = this.transaction?.metadata?.tracestate?.thirdparty;
+
+    // if there's third-party data, add a leading comma; otherwise, convert from `undefined` to the empty string, so the
+    // end result doesn’t come out as `sentry=xxxxxundefined`
+    thirdpartyTracestate = thirdpartyTracestate ? `,${thirdpartyTracestate}` : '';
+
+    return `${sentryTracestate}${thirdpartyTracestate}`;
+  }
 }

packages/tracing/src/utils.ts

@@ -1,5 +1,6 @@
 import { getCurrentHub, Hub } from '@sentry/hub';
 import { Options, TraceparentData, Transaction } from '@sentry/types';
+import { dropUndefinedKeys, SentryError, unicodeToBase64 } from '@sentry/utils';
 
 export const SENTRY_TRACE_REGEX = new RegExp(
   '^[ \\t]*' + // whitespace
@@ -75,3 +76,36 @@ 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';
+
+type SentryTracestateData = {
+  trace_id: string;
+  environment?: string;
+  release?: string;
+  public_key: string;
+  user?: { id?: string; segment?: string };
+};
+
+/**
+ * Compute the value of a Sentry tracestate header.
+ *
+ * @throws SentryError (because using the logger creates a circular dependency)
+ * @returns the base64-encoded header value
+ */
+export function computeTracestateValue(data: SentryTracestateData): string {
+  // `JSON.stringify` will drop keys with undefined values, but not ones with null values, so this prevents
+  // these values from being dropped if they haven't been set by `Sentry.init`
+
+  // 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(dropUndefinedKeys(data))).replace(/={1,2}$/, '');
+  } catch (err) {
+    throw new SentryError(`[Tracing] Error computing tracestate value from data: ${err}\nData: ${data}`);
+  }
+}

packages/tracing/test/span.test.ts

@@ -1,8 +1,9 @@
 import { BrowserClient } from '@sentry/browser';
 import { Hub, makeMain, Scope } from '@sentry/hub';
+import * as hubPackage from '@sentry/hub';
 
 import { Span, SpanStatus, Transaction } from '../src';
-import { SENTRY_TRACE_REGEX } from '../src/utils';
+import { computeTracestateValue, SENTRY_TRACE_REGEX } from '../src/utils';
 
 describe('Span', () => {
   let hub: Hub;
@@ -93,12 +94,86 @@ describe('Span', () => {
     });
   });
 
+  // TODO Once toTraceparent is removed, we obv don't need these tests anymore
   describe('toTraceparent', () => {
     test('simple', () => {
-      expect(new Span().toTraceparent()).toMatch(SENTRY_TRACE_REGEX);
+      expect(new Span().getTraceHeaders()['sentry-trace']).toMatch(SENTRY_TRACE_REGEX);
     });
     test('with sample', () => {
-      expect(new Span({ sampled: true }).toTraceparent()).toMatch(SENTRY_TRACE_REGEX);
+      expect(new Span({ sampled: true }).getTraceHeaders()['sentry-trace']).toMatch(SENTRY_TRACE_REGEX);
+    });
+  });
+
+  describe('toTracestate', () => {
+    const publicKey = 'dogsarebadatkeepingsecrets';
+    const release = 'off.leash.trail';
+    const environment = 'dogpark';
+    const traceId = '12312012123120121231201212312012';
+    const user = { id: '1121', segment: 'bigs' };
+
+    const computedTracestate = `sentry=${computeTracestateValue({
+      trace_id: traceId,
+      environment,
+      release,
+      public_key: publicKey,
+      user,
+    })}`;
+    const thirdpartyData = 'maisey=silly,charlie=goofy';
+
+    const hub = new Hub(
+      new BrowserClient({
+        dsn: 'https://[email protected]/12312012',
+        tracesSampleRate: 1,
+        release,
+        environment,
+      }),
+    );
+
+    hub.configureScope(scope => {
+      scope.setUser(user);
+    });
+
+    test('no third-party data', () => {
+      const transaction = new Transaction({ name: 'FETCH /ball', traceId }, hub);
+      const span = transaction.startChild({ op: 'dig.hole' });
+
+      expect(span.getTraceHeaders().tracestate).toEqual(computedTracestate);
+    });
+
+    test('third-party data', () => {
+      const transaction = new Transaction({ name: 'FETCH /ball' }, hub);
+      transaction.setMetadata({ tracestate: { sentry: computedTracestate, thirdparty: thirdpartyData } });
+      const span = transaction.startChild({ op: 'dig.hole' });
+
+      expect(span.getTraceHeaders().tracestate).toEqual(`${computedTracestate},${thirdpartyData}`);
+    });
+
+    test('orphan span', () => {
+      jest.spyOn(hubPackage, 'getCurrentHub').mockReturnValueOnce(hub);
+      const span = new Span({ op: 'dig.hole' });
+      span.traceId = traceId;
+
+      expect(span.getTraceHeaders().tracestate).toEqual(computedTracestate);
+    });
+  });
+
+  describe('getTraceHeaders', () => {
+    it('returns correct headers', () => {
+      const hub = new Hub(
+        new BrowserClient({
+          dsn: 'https://[email protected]/12312012',
+          tracesSampleRate: 1,
+          release: 'off.leash.park',
+          environment: 'dogpark',
+        }),
+      );
+      const transaction = hub.startTransaction({ name: 'FETCH /ball' });
+      const span = transaction.startChild({ op: 'dig.hole' });
+
+      const headers = span.getTraceHeaders();
+
+      expect(headers['sentry-trace']).toEqual(`${span.traceId}-${span.spanId}-1`);
+      expect(headers.tracestate).toEqual(transaction.metadata?.tracestate?.sentry);
     });
   });