Merge branch 'develop' into ab/js-3482/lazy-routes

Author: andreiborza

MIGRATION.md

@@ -97,7 +97,7 @@ Sentry.init({
 });
 ```
 
-If a library you depend on emits its own OpenTelemetry spans and you want those in Sentry too, use setup 2.
+Spans are completely managed by the Sentry SDK and there is no OpenTelemetry involved: spans created through `@opentelemetry/api` are ignored. If a library you depend on emits its own OpenTelemetry spans and you want those in Sentry too, use setup 2.
 
 ##### 2. OpenTelemetry-compatible mode, everything goes to Sentry
 
@@ -119,7 +119,7 @@ Spans go to Sentry. This is not a general OpenTelemetry pipeline: there is no ex
 
 ##### 3. Your own OpenTelemetry, Sentry linked to it
 
-Leave `enableOpenTelemetrySetup` unset or set it to `false`, turn Sentry tracing off, use your own OpenTelemetry setup, and add the Sentry `otlpIntegration()`:
+Turn Sentry tracing off, run your own OpenTelemetry setup, and add the Sentry `otlpIntegration()`. Leave `enableOpenTelemetrySetup` unset or set it to `false`:
 
 ```js
 import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
@@ -142,30 +142,15 @@ Sentry.init({
 
 `enableOpenTelemetrySetup` already defaults to `false` on most server SDKs, so there is nothing to set. On `@sentry/nextjs` and `@sentry/sveltekit` it defaults to `true`, so you have to set it to `false` explicitly. Otherwise Sentry registers its own tracer provider and you end up in setup 2 rather than this one.
 
-OpenTelemetry owns spans end to end. Sentry captures errors and logs, and the Sentry `otlpIntegration()` attaches them to the active OpenTelemetry span so all your telemetry is connected in one trace. `getOtlpTracesEndpoint()` turns your DSN into the URL and auth headers for Sentry's OTLP endpoint, so you can point your own exporter at Sentry, at your own collector, or at both.
+Spans are completely managed by your OpenTelemetry setup and the two pipelines stay separate: Sentry sends no spans, and no Sentry span is exported to your OpenTelemetry pipeline. Sentry captures errors and logs, and the Sentry `otlpIntegration()` attaches them to the active OpenTelemetry span so all your telemetry is connected in one trace. `getOtlpTracesEndpoint()` turns your DSN into the URL and auth headers for Sentry's OTLP endpoint, so you can point your own exporter at Sentry, at your own collector, or at both.
 
 Sentry does not touch your pipeline: no exporter, no span processor, no tracer provider, and outgoing trace propagation is left to your propagator. See [Connecting Sentry to your OpenTelemetry traces](#connecting-sentry-to-your-opentelemetry-traces) for the details, including what changed if you used the v10 integration.
 
-##### Avoiding duplicate spans
+##### Turning Sentry tracing off
 
-Sentry instruments many of the same libraries OpenTelemetry does (Express, Postgres, Redis, Prisma, Kafka and so on), so enabling Sentry tracing on top of your own instrumentation gives you two spans for every operation. Leave `tracesSampleRate` in your `Sentry.init` unset to avoid duplicate spans. With tracing off, Sentry's instrumentation stays installed and keeps isolating requests, but emits no spans.
+This setup only works with Sentry tracing off, so leave `tracesSampleRate` unset. Sentry instruments many of the same libraries OpenTelemetry does (Express, Postgres, Redis, Prisma, Kafka and so on), so leaving tracing on gives you two spans for every operation, in two pipelines that never join up. With tracing off, Sentry's instrumentation stays installed and keeps isolating requests, but emits no spans.
 
-Note that this changed since v10, where setting `skipOpenTelemetrySetup: true` also turned Sentry's HTTP and fetch spans off by default. Sentry now emits those whenever tracing is enabled, regardless of `enableOpenTelemetrySetup`.
-
-If you do want Sentry spans alongside your own, keep `tracesSampleRate` set and drop the integrations that overlap. HTTP and fetch are the exception: turn off only their spans, because `httpIntegration` also provides request isolation, request data and session tracking:
-
-```js
-Sentry.init({
-  dsn: '__DSN__',
-  tracesSampleRate: 1.0,
-  integrations: integrations => [
-    // your own OpenTelemetry instrumentation already covers these
-    ...integrations.filter(integration => integration.name !== 'Postgres'),
-    Sentry.httpIntegration({ spans: false }),
-    Sentry.nativeNodeFetchIntegration({ spans: false }),
-  ],
-});
-```
+Note that this changed since v10, where setting `skipOpenTelemetrySetup: true` also turned Sentry's HTTP and fetch spans off by default. Sentry now emits those whenever tracing is enabled, regardless of `enableOpenTelemetrySetup`, so an app that relied on that has to unset `tracesSampleRate`.
 
 ##### Migrating custom OpenTelemetry setups
 

dev-packages/e2e-tests/test-applications/node-otel-sdk-node/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "node-otel-sdk-node",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "start": "node --import ./src/instrument.mjs src/app.mjs",
+    "clean": "npx rimraf node_modules pnpm-lock.yaml",
+    "test:build": "pnpm install",
+    "test:assert": "playwright test"
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.220.0",
+    "@opentelemetry/instrumentation": "^0.220.0",
+    "@opentelemetry/instrumentation-http": "^0.220.0",
+    "@opentelemetry/sdk-node": "^0.220.0",
+    "@opentelemetry/sdk-trace-base": "^2.9.0",
+    "@sentry/node": "file:../../packed/sentry-node-packed.tgz",
+    "express": "^4.21.2"
+  },
+  "devDependencies": {
+    "@playwright/test": "~1.56.0",
+    "@sentry-internal/test-utils": "link:../../../test-utils"
+  },
+  "volta": {
+    "extends": "../../package.json"
+  }
+}

dev-packages/e2e-tests/test-applications/node-otel-sdk-node/playwright.config.mjs

@@ -0,0 +1,34 @@
+import { getPlaywrightConfig } from '@sentry-internal/test-utils';
+
+const config = getPlaywrightConfig(
+  {
+    startCommand: `pnpm start`,
+  },
+  {
+    webServer: [
+      {
+        command: `node ./start-event-proxy.mjs`,
+        port: 3031,
+        stdout: 'pipe',
+        stderr: 'pipe',
+      },
+      {
+        command: `node ./start-otel-proxy.mjs`,
+        port: 3032,
+        stdout: 'pipe',
+        stderr: 'pipe',
+      },
+      {
+        command: 'pnpm start',
+        port: 3030,
+        stdout: 'pipe',
+        stderr: 'pipe',
+        env: {
+          PORT: 3030,
+        },
+      },
+    ],
+  },
+);
+
+export default config;

dev-packages/e2e-tests/test-applications/node-otel-sdk-node/src/app.mjs

@@ -0,0 +1,47 @@
+import { trace } from '@opentelemetry/api';
+import * as Sentry from '@sentry/node';
+import express from 'express';
+import http from 'node:http';
+
+const app = express();
+const port = 3030;
+const tracer = trace.getTracer('node-otel-sdk-node');
+
+app.get('/test-telemetry/:id', function (req, res) {
+  tracer.startActiveSpan('telemetry-handler', span => {
+    const { traceId, spanId } = span.spanContext();
+
+    Sentry.captureException(new Error(`This is an exception with id ${req.params.id}`));
+
+    span.end();
+
+    res.json({ traceId, spanId });
+  });
+});
+
+app.get('/test-exception/:id', function (req, _res) {
+  throw new Error(`This is an exception with id ${req.params.id}`);
+});
+
+app.get('/test-outgoing', function (_req, res) {
+  http.get(`http://localhost:${port}/echo-headers`, response => {
+    let body = '';
+    response.on('data', chunk => (body += chunk));
+    response.on('end', () => res.type('json').send(body));
+  });
+});
+
+app.get('/echo-headers', function (req, res) {
+  res.send(req.headers);
+});
+
+// Answers with the OpenTelemetry span the request ran under, so the test can check what the error
+// captured by Sentry was linked to.
+app.use(function onError(_err, _req, res, _next) {
+  const spanContext = trace.getActiveSpan()?.spanContext();
+  res.status(500).json({ traceId: spanContext?.traceId, spanId: spanContext?.spanId });
+});
+
+app.listen(port, () => {
+  console.log(`Example app listening on port ${port}`);
+});

dev-packages/e2e-tests/test-applications/node-otel-sdk-node/src/instrument.mjs

@@ -0,0 +1,32 @@
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { HttpInstrumentation } from '@opentelemetry/instrumentation-http';
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base';
+import * as Sentry from '@sentry/node';
+import { register } from 'node:module';
+
+// What an ESM app needs for the OpenTelemetry instrumentation to see the modules it patches. It
+// puts import-in-the-middle in the process next to the module hooks Sentry's channel injection
+// registers from `Sentry.init()` below, which is the pairing this app exists to cover.
+register('@opentelemetry/instrumentation/hook.mjs', import.meta.url);
+
+// OpenTelemetry owns tracing here: the user's own SDK, their own instrumentation and their own
+// exporter. In production the exporter would point at `Sentry.getOtlpTracesEndpoint(dsn)`; here it
+// points at a local receiver so the test can assert what was exported.
+const sdk = new NodeSDK({
+  instrumentations: [new HttpInstrumentation()],
+  spanProcessors: [
+    new BatchSpanProcessor(new OTLPTraceExporter({ url: 'http://localhost:3032/' }), { scheduledDelayMillis: 100 }),
+  ],
+});
+
+sdk.start();
+
+Sentry.init({
+  environment: 'qa',
+  dsn: process.env.E2E_TEST_DSN,
+  debug: !!process.env.DEBUG,
+  tunnel: `http://localhost:3031/`, // proxy server
+  // no tracesSampleRate: OpenTelemetry owns spans, Sentry owns errors and logs
+  integrations: [Sentry.otlpIntegration()],
+});

dev-packages/e2e-tests/test-applications/node-otel-sdk-node/start-event-proxy.mjs

@@ -0,0 +1,6 @@
+import { startEventProxyServer } from '@sentry-internal/test-utils';
+
+startEventProxyServer({
+  port: 3031,
+  proxyServerName: 'node-otel-sdk-node',
+});

dev-packages/e2e-tests/test-applications/node-otel-sdk-node/start-otel-proxy.mjs

@@ -0,0 +1,6 @@
+import { startProxyServer } from '@sentry-internal/test-utils';
+
+startProxyServer({
+  port: 3032,
+  proxyServerName: 'node-otel-sdk-node-otel',
+});

dev-packages/e2e-tests/test-applications/node-otel-sdk-node/tests/errors.test.ts

@@ -0,0 +1,31 @@
+import { expect, test } from '@playwright/test';
+import { waitForError } from '@sentry-internal/test-utils';
+
+test('links errors to the active OpenTelemetry span', async ({ baseURL }) => {
+  const errorEventPromise = waitForError('node-otel-sdk-node', errorEvent => {
+    return errorEvent.exception?.values?.[0]?.value === 'This is an exception with id 123';
+  });
+
+  const response = await fetch(`${baseURL}/test-telemetry/123`);
+  const { traceId, spanId } = (await response.json()) as { traceId: string; spanId: string };
+
+  const errorEvent = await errorEventPromise;
+
+  expect(errorEvent.contexts?.trace).toEqual({ trace_id: traceId, span_id: spanId });
+});
+
+test('links errors from the Sentry instrumentation to the active OpenTelemetry span', async ({ baseURL }) => {
+  const errorEventPromise = waitForError('node-otel-sdk-node', errorEvent => {
+    return errorEvent.exception?.values?.[0]?.value === 'This is an exception with id 456';
+  });
+
+  const response = await fetch(`${baseURL}/test-exception/456`);
+  const { traceId, spanId } = (await response.json()) as { traceId: string; spanId: string };
+
+  const errorEvent = await errorEventPromise;
+
+  // With tracing off, Sentry's channel instrumentation still runs and reports the errors express
+  // never handles.
+  expect(errorEvent.exception?.values?.[0]?.mechanism).toEqual({ type: 'auto.http.express', handled: false });
+  expect(errorEvent.contexts?.trace).toEqual({ trace_id: traceId, span_id: spanId });
+});

dev-packages/e2e-tests/test-applications/node-otel-sdk-node/tests/opentelemetry.test.ts

@@ -0,0 +1,73 @@
+import { expect, test } from '@playwright/test';
+import { waitForError, waitForPlainRequest, waitForTransaction } from '@sentry-internal/test-utils';
+
+interface OtlpSpan {
+  name: string;
+  traceId: string;
+}
+
+/**
+ * The proxy hands back the payloads it received as newline separated JSON, so a single read can
+ * hold more than one OTLP export.
+ */
+function getExportedSpans(data: string): OtlpSpan[] {
+  return data
+    .split('\n')
+    .filter(Boolean)
+    .flatMap(
+      line => (JSON.parse(line) as { resourceSpans?: { scopeSpans?: { spans?: OtlpSpan[] }[] }[] }).resourceSpans ?? [],
+    )
+    .flatMap(resourceSpan => resourceSpan.scopeSpans ?? [])
+    .flatMap(scopeSpan => scopeSpan.spans ?? []);
+}
+
+test('exports the spans of the user OpenTelemetry setup to their own collector', async ({ baseURL }) => {
+  let traceId: string | undefined;
+
+  // Every test in this app exports into the same proxy, and the http span only ends once the
+  // response is out, so wait for this request's own trace to be complete. Waiting on the span names
+  // alone matches a batch that another test filled, whose spans are on a different trace.
+  const otelExportPromise = waitForPlainRequest('node-otel-sdk-node-otel', data => {
+    const names = getExportedSpans(data)
+      .filter(span => span.traceId === traceId)
+      .map(span => span.name);
+    return names.includes('telemetry-handler') && names.includes('GET');
+  });
+
+  const response = await fetch(`${baseURL}/test-telemetry/234`);
+  ({ traceId } = (await response.json()) as { traceId: string });
+
+  const exportedSpans = getExportedSpans(await otelExportPromise).filter(span => span.traceId === traceId);
+
+  // The user's own http instrumentation keeps working and stays on the same trace as their spans.
+  expect(exportedSpans.map(span => span.name)).toEqual(expect.arrayContaining(['telemetry-handler', 'GET']));
+});
+
+test('sends no spans to Sentry', async ({ baseURL }) => {
+  const transactionPromise = waitForTransaction('node-otel-sdk-node', () => true);
+  const errorPromise = waitForError('node-otel-sdk-node', errorEvent => {
+    return errorEvent.exception?.values?.[0]?.value === 'This is an exception with id 345';
+  });
+
+  await fetch(`${baseURL}/test-telemetry/345`);
+  // Proves the request's telemetry reached the proxy, so the absence check below is not vacuous.
+  await errorPromise;
+
+  // Absence can only be time bounded. This guards against Sentry's own instrumentation emitting
+  // spans again, which would produce a transaction for every request, well inside this window.
+  const transaction = await Promise.race([
+    transactionPromise,
+    new Promise(resolve => setTimeout(() => resolve(undefined), 3000)),
+  ]);
+
+  expect(transaction).toBeUndefined();
+});
+
+test('leaves outgoing trace propagation to the user propagator', async ({ baseURL }) => {
+  const response = await fetch(`${baseURL}/test-outgoing`);
+  const headers = (await response.json()) as Record<string, string>;
+
+  expect(headers['traceparent']).toMatch(/^00-[a-f0-9]{32}-[a-f0-9]{16}-\d{2}$/);
+  expect(headers['sentry-trace']).toBeUndefined();
+  expect(headers['baggage']).toBeUndefined();
+});

packages/astro/package.json

@@ -88,5 +88,18 @@
   },
   "astro": {
     "external": true
+  },
+  "nx": {
+    "targets": {
+      "build:transpile": {
+        "outputs": [
+          "{projectRoot}/build/esm",
+          "{projectRoot}/build/cjs",
+          "{projectRoot}/build/npm/esm",
+          "{projectRoot}/build/npm/cjs",
+          "{projectRoot}/build/import-hook.mjs"
+        ]
+      }
+    }
   }
 }