feat(astro): Add distributed tracing via <meta> tags

packages/astro/src/server/meta.ts

@@ -0,0 +1,79 @@
+import type { Hub } from '@sentry/core';
+import { getDynamicSamplingContextFromClient } from '@sentry/core';
+import type { Span } from '@sentry/types';
+import {
+  dynamicSamplingContextToSentryBaggageHeader,
+  generateSentryTraceHeader,
+  logger,
+  TRACEPARENT_REGEXP,
+} from '@sentry/utils';
+
+/**
+ * Extracts the tracing data from the current span or from the client's scope
+ * (via transaction or propagation context) and renders the data to <meta> tags.
+ *
+ * This function creates two serialized <meta> tags:
+ * - `<meta name="sentry-trace" content="..."/>`
+ * - `<meta name="baggage" content="..."/>`
+ *
+ * TODO: Extract this later on and export it from the Core or Node SDK
+ *
+ * @param span the currently active span
+ * @param client the SDK's client
+ *
+ * @returns an object with the two serialized <meta> tags
+ */
+export function getTracingMetaTags(span: Span | undefined, hub: Hub): { sentryTrace: string; baggage?: string } {
+  const scope = hub.getScope();
+  const client = hub.getClient();
+  const { dsc, sampled, traceId } = scope.getPropagationContext();
+  const transaction = span?.transaction;
+
+  const sentryTrace = span ? span.toTraceparent() : generateSentryTraceHeader(traceId, undefined, sampled);
+
+  const dynamicSamplingContext = transaction
+    ? transaction.getDynamicSamplingContext()
+    : dsc
+    ? dsc
+    : client
+    ? getDynamicSamplingContextFromClient(traceId, client, scope)
+    : undefined;
+
+  const baggage = dynamicSamplingContextToSentryBaggageHeader(dynamicSamplingContext);
+
+  const isValidSentryTraceHeader = TRACEPARENT_REGEXP.test(sentryTrace);
+  if (!isValidSentryTraceHeader) {
+    logger.warn('Invalid sentry-trace data. Returning empty <meta name="sentry-trace"/> tag');
+  }
+
+  const validBaggage = isValidBaggageString(baggage);
+  if (!validBaggage) {
+    logger.warn('Invalid baggage data. Returning empty <meta name="baggage"/> tag');
+  }
+
+  return {
+    sentryTrace: `<meta name="sentry-trace" content="${isValidSentryTraceHeader ? sentryTrace : ''}"/>`,
+    baggage: baggage && `<meta name="baggage" content="${validBaggage ? baggage : ''}"/>`,
+  };
+}
+
+/**
+ * Tests string against baggage spec as defined in:
+ *
+ * - W3C Baggage grammar: https://www.w3.org/TR/baggage/#definition
+ * - RFC7230 token definition: https://datatracker.ietf.org/doc/html/rfc7230#section-3.2.6
+ *
+ * exported for testing
+ */
+export function isValidBaggageString(baggage?: string): boolean {
+  if (!baggage || !baggage.length) {
+    return false;
+  }
+  const keyRegex = "[-!#$%&'*+.^_`|~A-Za-z0-9]+";
+  const valueRegex = '[!#-+-./0-9:<=>?@A-Z\\[\\]a-z{-}]+';
+  const spaces = '\\s*';
+  const baggageRegex = new RegExp(
+    `^${keyRegex}${spaces}=${spaces}${valueRegex}(${spaces},${spaces}${keyRegex}${spaces}=${spaces}${valueRegex})*$`,
+  );
+  return baggageRegex.test(baggage);
+}

packages/astro/src/server/middleware.ts

@@ -1,7 +1,9 @@
-import { captureException, configureScope, startSpan } from '@sentry/node';
+import { captureException, configureScope, getCurrentHub, startSpan } from '@sentry/node';
 import { addExceptionMechanism, objectify, stripUrlQueryAndFragment, tracingContextFromHeaders } from '@sentry/utils';
 import type { APIContext, MiddlewareResponseHandler } from 'astro';
 
+import { getTracingMetaTags } from './meta';
+
 type MiddlewareOptions = {
   /**
    * If true, the client IP will be attached to the event by calling `setUser`.
@@ -93,11 +95,30 @@ export const handleRequest: (options?: MiddlewareOptions) => MiddlewareResponseH
           },
         },
         async span => {
-          const res = await next();
-          if (span && res.status) {
-            span.setHttpStatus(res.status);
+          const originalResponse = await next();
+          if (span && originalResponse.status) {
+            span.setHttpStatus(originalResponse.status);
+          }
+
+          const hub = getCurrentHub();
+          const client = hub.getClient();
+          const contentType = originalResponse.headers.get('content-type');
+
+          const isPageloadRequest = contentType && contentType.startsWith('text/html');
+          if (!isPageloadRequest || !client) {
+            return originalResponse;
           }
-          return res;
+
+          const html = await originalResponse.text();
+          if (typeof html !== 'string' || !html.includes('<head>')) {
+            return originalResponse;
+          }
+
+          const { sentryTrace, baggage } = getTracingMetaTags(span, hub);
+          const content = `<head>\n${sentryTrace}\n${baggage}\n`;
+          const modifiedHtml = html.replace('<head>', content);
+
+          return new Response(modifiedHtml, originalResponse);
         },
       );
       return res;

packages/astro/test/server/meta.test.ts

@@ -0,0 +1,178 @@
+import * as SentryCore from '@sentry/core';
+import { vi } from 'vitest';
+
+import { getTracingMetaTags, isValidBaggageString } from '../../src/server/meta';
+
+const mockedSpan = {
+  toTraceparent: () => '12345678901234567890123456789012-1234567890123456-1',
+  transaction: {
+    getDynamicSamplingContext: () => ({
+      environment: 'production',
+    }),
+  },
+};
+
+const mockedHub = {
+  getScope: () => ({
+    getPropagationContext: () => ({
+      traceId: '123',
+    }),
+  }),
+  getClient: () => ({}),
+};
+
+describe('getTracingMetaTags', () => {
+  it('returns the tracing tags from the span, if it is provided', () => {
+    {
+      // @ts-expect-error - only passing a partial span object
+      const tags = getTracingMetaTags(mockedSpan, mockedHub);
+
+      expect(tags).toEqual({
+        sentryTrace: '<meta name="sentry-trace" content="12345678901234567890123456789012-1234567890123456-1"/>',
+        baggage: '<meta name="baggage" content="sentry-environment=production"/>',
+      });
+    }
+  });
+
+  it('returns propagationContext DSC data if no span is available', () => {
+    const tags = getTracingMetaTags(undefined, {
+      ...mockedHub,
+      // @ts-expect-error - only passing a partial scope object
+      getScope: () => ({
+        getPropagationContext: () => ({
+          traceId: '12345678901234567890123456789012',
+          sampled: true,
+          spanId: '1234567890123456',
+          dsc: {
+            environment: 'staging',
+            public_key: 'key',
+            trace_id: '12345678901234567890123456789012',
+          },
+        }),
+      }),
+    });
+
+    expect(tags).toEqual({
+      sentryTrace: expect.stringMatching(
+        /<meta name="sentry-trace" content="12345678901234567890123456789012-(.{16})-1"\/>/,
+      ),
+      baggage:
+        '<meta name="baggage" content="sentry-environment=staging,sentry-public_key=key,sentry-trace_id=12345678901234567890123456789012"/>',
+    });
+  });
+
+  it('returns only the `sentry-trace` tag if no DSC is available', () => {
+    vi.spyOn(SentryCore, 'getDynamicSamplingContextFromClient').mockReturnValueOnce({
+      trace_id: '',
+      public_key: undefined,
+    });
+
+    const tags = getTracingMetaTags(
+      // @ts-expect-error - only passing a partial span object
+      {
+        toTraceparent: () => '12345678901234567890123456789012-1234567890123456-1',
+        transaction: undefined,
+      },
+      mockedHub,
+    );
+
+    expect(tags).toEqual({
+      sentryTrace: '<meta name="sentry-trace" content="12345678901234567890123456789012-1234567890123456-1"/>',
+    });
+  });
+
+  it('returns only the `sentry-trace` tag if no DSC is available', () => {
+    vi.spyOn(SentryCore, 'getDynamicSamplingContextFromClient').mockReturnValueOnce({
+      trace_id: '',
+      public_key: undefined,
+    });
+
+    const tags = getTracingMetaTags(
+      // @ts-expect-error - only passing a partial span object
+      {
+        toTraceparent: () => '12345678901234567890123456789012-1234567890123456-1',
+        transaction: undefined,
+      },
+      {
+        ...mockedHub,
+        getClient: () => undefined,
+      },
+    );
+
+    expect(tags).toEqual({
+      sentryTrace: '<meta name="sentry-trace" content="12345678901234567890123456789012-1234567890123456-1"/>',
+    });
+  });
+});
+
+describe('isValidBaggageString', () => {
+  it.each([
+    'sentry-environment=production',
+    'sentry-environment=staging,sentry-public_key=key,sentry-trace_id=abc',
+    // @ is allowed in values
+    '[email protected]',
+    // spaces are allowed around the delimiters
+    'sentry-environment=staging ,   sentry-public_key=key  ,[email protected]',
+    'sentry-environment=staging ,   thirdparty=value  ,[email protected]',
+    // these characters are explicitly allowed for keys in the baggage spec:
+    "!#$%&'*+-.^_`|~1234567890abcxyzABCXYZ=true",
+    // special characters in values are fine (except for ",;\ - see other test)
+    'key=(value)',
+    'key=[{(value)}]',
+    'key=some$value',
+    'key=more#value',
+    'key=max&value',
+    'key=max:value',
+    'key=x=value',
+  ])('returns true if the baggage string is valid (%s)', baggageString => {
+    expect(isValidBaggageString(baggageString)).toBe(true);
+  });
+
+  it.each([
+    // baggage spec doesn't permit leading spaces
+    ' sentry-environment=production,sentry-publickey=key,sentry-trace_id=abc',
+    // no spaces in keys or values
+    'sentry-public key=key',
+    'sentry-publickey=my key',
+    // no delimiters ("(),/:;<=>?@[\]{}") in keys
+    'asdf(x=value',
+    'asdf)x=value',
+    'asdf,x=value',
+    'asdf/x=value',
+    'asdf:x=value',
+    'asdf;x=value',
+    'asdf<x=value',
+    'asdf>x=value',
+    'asdf?x=value',
+    'asdf@x=value',
+    'asdf[x=value',
+    'asdf]x=value',
+    'asdf\\x=value',
+    'asdf{x=value',
+    'asdf}x=value',
+    // no ,;\" in values
+    'key=va,lue',
+    'key=va;lue',
+    'key=va\\lue',
+    'key=va"lue"',
+    // baggage headers can have properties but we currently don't support them
+    'sentry-environment=production;prop1=foo;prop2=bar,nextkey=value',
+    // no fishy stuff
+    'absolutely not a valid baggage string',
+    'val"/><script>alert("xss")</script>',
+    'something"/>',
+    '<script>alert("xss")</script>',
+    '/>',
+    '" onblur="alert("xss")',
+  ])('returns false if the baggage string is invalid (%s)', baggageString => {
+    expect(isValidBaggageString(baggageString)).toBe(false);
+  });
+
+  it('returns false if the baggage string is empty', () => {
+    expect(isValidBaggageString('')).toBe(false);
+  });
+
+  it('returns false if the baggage string is empty', () => {
+    expect(isValidBaggageString(undefined)).toBe(false);
+  });
+});