feat(deno): Add orchestrion deno runtime hook (#21451)

Use the orchestrion loader hook defined in server-utils, and create a
loader for Deno that detects the presence of the hooks, and instruments
the channels added to the mysql module.

Documentation added to call out the caveat of usage in Deno v2.8.0
through 2.8.2, which is fixed in 2.8.3.

Author: isaacs

.github/workflows/build.yml

@@ -998,7 +998,7 @@ jobs:
       - name: Set up Deno
         if:
           matrix.test-application == 'deno' || matrix.test-application == 'deno-streamed' || matrix.test-application ==
-          'deno-redis' || matrix.test-application == 'hono-4'
+          'deno-redis' || matrix.test-application == 'hono-4' || matrix.test-application == 'deno-mysql'
         uses: denoland/setup-deno@v2.0.4
         with:
           deno-version: ${{ matrix.deno-version || 'v2.8.0' }}

dev-packages/e2e-tests/test-applications/deno-mysql/deno.json

@@ -0,0 +1,7 @@
+{
+  "imports": {
+    "@sentry/deno": "npm:@sentry/deno",
+    "mysql": "npm:mysql@2.18.1"
+  },
+  "nodeModulesDir": "manual"
+}

dev-packages/e2e-tests/test-applications/deno-mysql/docker-compose.yml

@@ -0,0 +1,18 @@
+services:
+  db:
+    image: mysql:8.0
+    restart: always
+    container_name: e2e-tests-deno-mysql
+    # The `mysql` 2.x driver doesn't speak MySQL 8's default
+    # `caching_sha2_password` auth, so force the legacy plugin.
+    command: ['--default-authentication-plugin=mysql_native_password']
+    ports:
+      - '3306:3306'
+    environment:
+      MYSQL_ROOT_PASSWORD: password
+    healthcheck:
+      test: ['CMD-SHELL', 'mysqladmin ping -h 127.0.0.1 -uroot -ppassword']
+      interval: 2s
+      timeout: 3s
+      retries: 30
+      start_period: 10s

dev-packages/e2e-tests/test-applications/deno-mysql/global-setup.mjs

@@ -0,0 +1,14 @@
+import { execSync } from 'child_process';
+import { dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export default async function globalSetup() {
+  // Start MySQL via Docker Compose. `--wait` blocks until the healthcheck
+  // in docker-compose.yml passes, so the Deno app can connect immediately.
+  execSync('docker compose up -d --wait', {
+    cwd: __dirname,
+    stdio: 'inherit',
+  });
+}

dev-packages/e2e-tests/test-applications/deno-mysql/global-teardown.mjs

@@ -0,0 +1,12 @@
+import { execSync } from 'child_process';
+import { dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export default async function globalTeardown() {
+  execSync('docker compose down --volumes', {
+    cwd: __dirname,
+    stdio: 'inherit',
+  });
+}

dev-packages/e2e-tests/test-applications/deno-mysql/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "deno-mysql",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "start": "docker compose up -d --wait && deno run --allow-net --allow-env --allow-read --allow-sys --allow-write src/app.ts",
+    "test": "playwright test",
+    "clean": "npx rimraf node_modules pnpm-lock.yaml",
+    "test:build": "pnpm install",
+    "test:assert": "pnpm test"
+  },
+  "dependencies": {
+    "@sentry/deno": "file:../../packed/sentry-deno-packed.tgz",
+    "mysql": "2.18.1"
+  },
+  "devDependencies": {
+    "@playwright/test": "~1.56.0",
+    "@sentry-internal/test-utils": "link:../../../test-utils"
+  },
+  "volta": {
+    "extends": "../../package.json"
+  }
+}

dev-packages/e2e-tests/test-applications/deno-mysql/playwright.config.mjs

@@ -0,0 +1,12 @@
+import { getPlaywrightConfig } from '@sentry-internal/test-utils';
+
+const config = getPlaywrightConfig({
+  startCommand: `pnpm start`,
+  port: 3030,
+});
+
+export default {
+  ...config,
+  globalSetup: './global-setup.mjs',
+  globalTeardown: './global-teardown.mjs',
+};

dev-packages/e2e-tests/test-applications/deno-mysql/src/app.ts

@@ -0,0 +1,66 @@
+// `@sentry/deno/import` MUST be the very first import: it registers the
+// orchestrion runtime hook, which transforms `mysql` (imported dynamically
+// below) to publish the `orchestrion:mysql:query` diagnostics channel.
+// In Deno 2.8.0–2.8.2 the hook only works as the first import in the entry graph.
+import '@sentry/deno/import';
+import * as Sentry from '@sentry/deno';
+
+Sentry.init({
+  environment: 'qa',
+  dsn: Deno.env.get('E2E_TEST_DSN'),
+  debug: !!Deno.env.get('DEBUG'),
+  tunnel: 'http://localhost:3031/', // proxy server
+  tracesSampleRate: 1,
+});
+
+// Dynamic import AFTER init so the orchestrion hook (registered above) is in
+// place to transform `mysql/lib/Connection.js`'s `query`, and so
+// `denoMysqlIntegration` (wired by `init()`) is already subscribed.
+const { default: mysql } = await import('mysql');
+
+const connection = mysql.createConnection({
+  host: Deno.env.get('MYSQL_HOST') ?? '127.0.0.1',
+  port: Number(Deno.env.get('MYSQL_PORT') ?? 3306),
+  user: 'root',
+  password: 'password',
+});
+
+// Swallow connection errors (e.g. the DB container going away at teardown) so
+// they don't become an uncaught exception that crashes the process on shutdown.
+connection.on('error', (err: unknown) => {
+  // eslint-disable-next-line no-console
+  console.error('mysql connection error', err);
+});
+
+connection.connect((err: unknown) => {
+  if (err) {
+    // eslint-disable-next-line no-console
+    console.error('mysql connect error', err);
+  }
+});
+
+const port = 3030;
+
+Deno.serve({ port, hostname: '0.0.0.0' }, async (req: Request) => {
+  const url = new URL(req.url);
+
+  // Runs two queries, the second NESTED inside the first's callback. mysql
+  // dispatches that callback from its socket data handler (a fresh async
+  // context), so the nested query's span only lands on this request's
+  // http.server transaction if `denoMysqlIntegration`'s AsyncLocalStorage
+  // context strategy restored the parent across the async boundary.
+  if (url.pathname === '/test-mysql') {
+    await new Promise<void>((resolve, reject) => {
+      connection.query('SELECT 1 + 1 AS solution', (err: unknown) => {
+        if (err) return reject(err);
+        connection.query('SELECT NOW()', (err2: unknown) => {
+          if (err2) return reject(err2);
+          resolve();
+        });
+      });
+    });
+    return Response.json({ status: 'ok' });
+  }
+
+  return new Response('Not found', { status: 404 });
+});

dev-packages/e2e-tests/test-applications/deno-mysql/start-event-proxy.mjs

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

dev-packages/e2e-tests/test-applications/deno-mysql/tests/mysql.test.ts

@@ -0,0 +1,54 @@
+import { expect, test } from '@playwright/test';
+import { waitForTransaction } from '@sentry-internal/test-utils';
+
+test('mysql queries emit a db span with orchestrion-channel attributes', async ({ baseURL }) => {
+  // Each incoming request gets a Sentry http.server transaction (via the
+  // default denoServeIntegration); the mysql queries run inside it, so their
+  // db spans attach to that transaction.
+  const transactionPromise = waitForTransaction('deno-mysql', event => {
+    return (
+      event?.contexts?.trace?.op === 'http.server' &&
+      (event.request?.url ?? '').includes('/test-mysql') &&
+      (event.spans?.some(span => span.op === 'db') ?? false)
+    );
+  });
+
+  const res = await fetch(`${baseURL}/test-mysql`);
+  expect(res.status).toBe(200);
+  await res.json();
+
+  const transaction = await transactionPromise;
+  const dbSpans = transaction.spans!.filter(span => span.op === 'db');
+
+  const firstQuery = dbSpans.find(span => span.description === 'SELECT 1 + 1 AS solution');
+  expect(firstQuery).toBeDefined();
+  expect(firstQuery!.data?.['sentry.origin']).toBe('auto.db.orchestrion.mysql');
+  expect(firstQuery!.data?.['db.system']).toBe('mysql');
+  expect(firstQuery!.data?.['db.statement']).toBe('SELECT 1 + 1 AS solution');
+  expect(firstQuery!.data?.['net.peer.port']).toBe(3306);
+  expect(firstQuery!.data?.['db.user']).toBe('root');
+});
+
+test('a nested query lands on the same transaction (AsyncLocalStorage context restored)', async ({ baseURL }) => {
+  // The second query runs inside the first query's callback — i.e. across
+  // mysql's async socket-callback dispatch. Both spans appearing on the SAME
+  // http.server transaction proves denoMysqlIntegration's context strategy
+  // restored the parent span across that async boundary (otherwise the nested
+  // query would start its own trace and never join this transaction).
+  const transactionPromise = waitForTransaction('deno-mysql', event => {
+    return (
+      event?.contexts?.trace?.op === 'http.server' &&
+      (event.request?.url ?? '').includes('/test-mysql') &&
+      (event.spans?.filter(span => span.op === 'db').length ?? 0) >= 2
+    );
+  });
+
+  const res = await fetch(`${baseURL}/test-mysql`);
+  expect(res.status).toBe(200);
+  await res.json();
+
+  const transaction = await transactionPromise;
+  const descriptions = transaction.spans!.filter(span => span.op === 'db').map(span => span.description);
+  expect(descriptions).toContain('SELECT 1 + 1 AS solution');
+  expect(descriptions).toContain('SELECT NOW()');
+});