feat(core): Add getTraceMetaTags function (#13201)

Lms24 · andreiborza · web-flow · commit 05684d452227 · 2024-08-06T14:37:58.000+02:00
Export function `getTraceMetaTags` that gives users an easy way to get stringified Html
meta tags for server-&gt;client trace propagation.

---------

Co-authored-by: Andrei &lt;168741329+andreiborza@users.noreply.github.com&gt;
diff --git a/dev-packages/node-integration-tests/suites/tracing/meta-tags/server.js b/dev-packages/node-integration-tests/suites/tracing/meta-tags/server.js
@@ -0,0 +1,33 @@
+const { loggingTransport } = require('@sentry-internal/node-integration-tests');
+const Sentry = require('@sentry/node');
+
+Sentry.init({
+  dsn: 'https://public@dsn.ingest.sentry.io/1337',
+  tracesSampleRate: 1.0,
+  transport: loggingTransport,
+});
+
+// express must be required after Sentry is initialized
+const express = require('express');
+const { startExpressServerAndSendPortToRunner } = require('@sentry-internal/node-integration-tests');
+
+const app = express();
+
+app.get('/test', (_req, res) => {
+  res.send({
+    response: `
+    <html>
+      <head>
+        ${Sentry.getTraceMetaTags()}
+      </head>
+      <body>
+        Hi :)
+      </body>
+    </html>
+    `,
+  });
+});
+
+Sentry.setupExpressErrorHandler(app);
+
+startExpressServerAndSendPortToRunner(app);
diff --git a/dev-packages/node-integration-tests/suites/tracing/meta-tags/test.ts b/dev-packages/node-integration-tests/suites/tracing/meta-tags/test.ts
@@ -0,0 +1,26 @@
+import { cleanupChildProcesses, createRunner } from '../../../utils/runner';
+
+describe('getTraceMetaTags', () => {
+  afterAll(() => {
+    cleanupChildProcesses();
+  });
+
+  test('injects sentry tracing <meta> tags', async () => {
+    const traceId = 'cd7ee7a6fe3ebe7ab9c3271559bc203c';
+    const parentSpanId = '100ff0980e7a4ead';
+
+    const runner = createRunner(__dirname, 'server.js').start();
+
+    const response = await runner.makeRequest('get', '/test', {
+      'sentry-trace': `${traceId}-${parentSpanId}-1`,
+      baggage: 'sentry-environment=production',
+    });
+
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-ignore
+    const html = response?.response as unknown as string;
+
+    expect(html).toMatch(/<meta name="sentry-trace" content="cd7ee7a6fe3ebe7ab9c3271559bc203c-[a-z0-9]{16}-1"\/>/);
+    expect(html).toContain('<meta name="baggage" content="sentry-environment=production"/>');
+  });
+});
diff --git a/packages/astro/src/index.server.ts b/packages/astro/src/index.server.ts
@@ -56,6 +56,7 @@ export {
   getSpanDescendants,
   getSpanStatusFromHttpCode,
   getTraceData,
+  getTraceMetaTags,
   graphqlIntegration,
   hapiIntegration,
   httpIntegration,
diff --git a/packages/astro/src/server/middleware.ts b/packages/astro/src/server/middleware.ts
@@ -6,6 +6,7 @@ import {
   getActiveSpan,
   getClient,
   getCurrentScope,
+  getTraceMetaTags,
   setHttpStatus,
   startSpan,
   withIsolationScope,
@@ -14,8 +15,6 @@ import type { Client, Scope, Span, SpanAttributes } from '@sentry/types';
 import { addNonEnumerableProperty, objectify, stripUrlQueryAndFragment } from '@sentry/utils';
 import type { APIContext, MiddlewareResponseHandler } from 'astro';
 
-import { getTraceData } from '@sentry/node';
-
 type MiddlewareOptions = {
   /**
    * If true, the client IP will be attached to the event by calling `setUser`.
@@ -189,16 +188,13 @@ function addMetaTagToHead(htmlChunk: string, scope: Scope, client: Client, span?
   if (typeof htmlChunk !== 'string') {
     return htmlChunk;
   }
-  const { 'sentry-trace': sentryTrace, baggage } = getTraceData(span, scope, client);
+  const metaTags = getTraceMetaTags(span, scope, client);
 
-  if (!sentryTrace) {
+  if (!metaTags) {
     return htmlChunk;
   }
 
-  const sentryTraceMeta = `<meta name="sentry-trace" content="${sentryTrace}"/>`;
-  const baggageMeta = baggage && `<meta name="baggage" content="${baggage}"/>`;
-
-  const content = `<head>\n${sentryTraceMeta}`.concat(baggageMeta ? `\n${baggageMeta}` : '', '\n');
+  const content = `<head>${metaTags}`;
 
   return htmlChunk.replace('<head>', content);
 }
diff --git a/packages/astro/test/server/middleware.test.ts b/packages/astro/test/server/middleware.test.ts
@@ -34,10 +34,12 @@ describe('sentryMiddleware', () => {
     });
     vi.spyOn(SentryNode, 'getActiveSpan').mockImplementation(getSpanMock);
     vi.spyOn(SentryNode, 'getClient').mockImplementation(() => ({}) as Client);
-    vi.spyOn(SentryNode, 'getTraceData').mockImplementation(() => ({
-      'sentry-trace': '123',
-      baggage: 'abc',
-    }));
+    vi.spyOn(SentryNode, 'getTraceMetaTags').mockImplementation(
+      () => `
+    <meta name="sentry-trace" content="123">
+    <meta name="baggage" content="abc">
+    `,
+    );
     vi.spyOn(SentryCore, 'getDynamicSamplingContextFromSpan').mockImplementation(() => ({
       transaction: 'test',
     }));
diff --git a/packages/aws-serverless/src/index.ts b/packages/aws-serverless/src/index.ts
@@ -21,6 +21,7 @@ export {
   getGlobalScope,
   getIsolationScope,
   getTraceData,
+  getTraceMetaTags,
   setCurrentClient,
   Scope,
   SDK_VERSION,
diff --git a/packages/bun/src/index.ts b/packages/bun/src/index.ts
@@ -41,6 +41,7 @@ export {
   getGlobalScope,
   getIsolationScope,
   getTraceData,
+  getTraceMetaTags,
   setCurrentClient,
   Scope,
   SDK_VERSION,
diff --git a/packages/cloudflare/src/index.ts b/packages/cloudflare/src/index.ts
@@ -56,6 +56,7 @@ export {
   getActiveSpan,
   getRootSpan,
   getTraceData,
+  getTraceMetaTags,
   startSpan,
   startInactiveSpan,
   startSpanManual,
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
@@ -83,6 +83,7 @@ export {
 export { parseSampleRate } from './utils/parseSampleRate';
 export { applySdkMetadata } from './utils/sdkMetadata';
 export { getTraceData } from './utils/traceData';
+export { getTraceMetaTags } from './utils/meta';
 export { DEFAULT_ENVIRONMENT } from './constants';
 export { addBreadcrumb } from './breadcrumbs';
 export { functionToStringIntegration } from './integrations/functiontostring';
diff --git a/packages/core/src/utils/meta.ts b/packages/core/src/utils/meta.ts
@@ -0,0 +1,29 @@
+import type { Client, Scope, Span } from '@sentry/types';
+import { getTraceData } from './traceData';
+
+/**
+ * Returns a string of meta tags that represent the current trace data.
+ *
+ * You can use this to propagate a trace from your server-side rendered Html to the browser.
+ * This function returns up to two meta tags, `sentry-trace` and `baggage`, depending on the
+ * current trace data state.
+ *
+ * @example
+ * Usage example:
+ *
+ * ```js
+ * function renderHtml() {
+ *   return `
+ *     <head>
+ *       ${getTraceMetaTags()}
+ *     </head>
+ *   `;
+ * }
+ * ```
+ *
+ */
+export function getTraceMetaTags(span?: Span, scope?: Scope, client?: Client): string {
+  return Object.entries(getTraceData(span, scope, client))
+    .map(([key, value]) => `<meta name="${key}" content="${value}"/>`)
+    .join('\n');
+}
diff --git a/packages/core/test/lib/utils/meta.test.ts b/packages/core/test/lib/utils/meta.test.ts
@@ -0,0 +1,30 @@
+import { getTraceMetaTags } from '../../../src/utils/meta';
+import * as TraceDataModule from '../../../src/utils/traceData';
+
+describe('getTraceMetaTags', () => {
+  it('renders baggage and sentry-trace values to stringified Html meta tags', () => {
+    jest.spyOn(TraceDataModule, 'getTraceData').mockReturnValueOnce({
+      'sentry-trace': '12345678901234567890123456789012-1234567890123456-1',
+      baggage: 'sentry-environment=production',
+    });
+
+    expect(getTraceMetaTags()).toBe(`<meta name="sentry-trace" content="12345678901234567890123456789012-1234567890123456-1"/>
+<meta name="baggage" content="sentry-environment=production"/>`);
+  });
+
+  it('renders just sentry-trace values to stringified Html meta tags', () => {
+    jest.spyOn(TraceDataModule, 'getTraceData').mockReturnValueOnce({
+      'sentry-trace': '12345678901234567890123456789012-1234567890123456-1',
+    });
+
+    expect(getTraceMetaTags()).toBe(
+      '<meta name="sentry-trace" content="12345678901234567890123456789012-1234567890123456-1"/>',
+    );
+  });
+
+  it('returns an empty string if neither sentry-trace nor baggage values are available', () => {
+    jest.spyOn(TraceDataModule, 'getTraceData').mockReturnValueOnce({});
+
+    expect(getTraceMetaTags()).toBe('');
+  });
+});
diff --git a/packages/deno/src/index.ts b/packages/deno/src/index.ts
@@ -56,6 +56,7 @@ export {
   getActiveSpan,
   getRootSpan,
   getTraceData,
+  getTraceMetaTags,
   startSpan,
   startInactiveSpan,
   startSpanManual,
diff --git a/packages/google-cloud-serverless/src/index.ts b/packages/google-cloud-serverless/src/index.ts
@@ -21,6 +21,7 @@ export {
   getGlobalScope,
   getIsolationScope,
   getTraceData,
+  getTraceMetaTags,
   setCurrentClient,
   Scope,
   SDK_VERSION,
diff --git a/packages/node/src/index.ts b/packages/node/src/index.ts
@@ -96,6 +96,7 @@ export {
   getCurrentScope,
   getIsolationScope,
   getTraceData,
+  getTraceMetaTags,
   withScope,
   withIsolationScope,
   captureException,
diff --git a/packages/sveltekit/src/server/index.ts b/packages/sveltekit/src/server/index.ts
@@ -52,6 +52,7 @@ export {
   getSpanDescendants,
   getSpanStatusFromHttpCode,
   getTraceData,
+  getTraceMetaTags,
   graphqlIntegration,
   hapiIntegration,
   httpIntegration,
diff --git a/packages/vercel-edge/src/index.ts b/packages/vercel-edge/src/index.ts
@@ -56,6 +56,7 @@ export {
   getActiveSpan,
   getRootSpan,
   getTraceData,
+  getTraceMetaTags,
   startSpan,
   startInactiveSpan,
   startSpanManual,
