feat(deno): Add orchestrion deno runtime hook

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

packages/deno/README.md

@@ -56,3 +56,46 @@ Sentry.captureEvent({
   ],
 });
 ```
+
+## Auto-instrumentation (experimental)
+
+Some libraries (e.g. `mysql`) don't emit tracing signals on their
+own. To instrument them, Sentry uses
+[orchestrion](https://github.com/getsentry/sentry-javascript) to
+transform them at load time so they publish to
+`node:diagnostics_channel`.
+
+In Deno versions prior to 2.8.0, this is not available, as it
+relies on `Module.registerHooks`, which was added in that
+version.
+
+As of Deno 2.8.3, you can use the `--import` or `--preload`
+argument to `deno run` in order to enable these instrumentations.
+
+```bash
+$ deno run --import=@sentry/deno/import app.ts
+```
+
+> [!NOTE]
+> In Deno versions **2.8.0** through **2.8.2**, a bug causes Deno
+> to deadlock when a module hook is added in this way. As a
+> workaround, you can import the loader explicitly, and then
+> dynamically import your app to take advantage of the added
+> module loading hooks.
+>
+> ```ts
+> import 'npm:@sentry/deno/import';
+> await import('./app.ts');
+> ```
+
+In both cases, your `app.ts` should simply load Sentry as usual:
+
+```ts
+// app.ts
+
+// initialize Sentry as early as possible
+import * as Sentry from 'npm:@sentry/deno';
+Sentry.init({ dsn: '__DSN__' });
+
+// ... the rest of the app...
+```

packages/deno/package.json

@@ -15,6 +15,9 @@
         "types": "./build/esm/index.d.ts",
         "default": "./build/esm/index.js"
       }
+    },
+    "./import": {
+      "import": "./build/import.mjs"
     }
   },
   "publishConfig": {
@@ -28,6 +31,9 @@
     "@sentry/core": "10.57.0",
     "@sentry/server-utils": "10.57.0"
   },
+  "devDependencies": {
+    "mysql": "^2.18.1"
+  },
   "scripts": {
     "deno-types": "node ./scripts/download-deno-types.mjs",
     "build": "run-s build:transpile build:types",
@@ -51,7 +57,9 @@
   "volta": {
     "extends": "../../package.json"
   },
-  "sideEffects": false,
+  "sideEffects": [
+    "./build/import.mjs"
+  ],
   "nx": {
     "targets": {
       "build:transpile": {

packages/deno/rollup.npm.config.mjs

@@ -1,3 +1,12 @@
+import { defineConfig } from 'rollup';
 import { makeBaseNPMConfig, makeNPMConfigVariants } from '@sentry-internal/rollup-utils';
 
-export default makeNPMConfigVariants(makeBaseNPMConfig(), { emitCjs: false });
+const orchestrionRuntimeHooks = [
+  defineConfig({
+    input: 'src/import.mjs',
+    external: /.*/,
+    output: { format: 'esm', file: 'build/import.mjs' },
+  }),
+];
+
+export default [...orchestrionRuntimeHooks, ...makeNPMConfigVariants(makeBaseNPMConfig(), { emitCjs: false })];

packages/deno/src/denoVersion.ts

@@ -23,3 +23,10 @@ export const HTTP_SERVER_DIAGNOSTICS_CHANNEL_SUPPORTED = gte(2, 8, 0);
 
 /** Whether `node:diagnostics_channel.tracingChannel` exists (Deno 1.44.3+). */
 export const TRACING_CHANNEL_SUPPORTED = gte(1, 44, 3);
+
+/**
+ * Whether `Module.registerHooks` is available (Deno 2.8.0+), which the
+ * orchestrion runtime hook (`@sentry/deno/import`) needs to transform libraries
+ * like `mysql` so they publish to their tracing channels.
+ */
+export const MODULE_REGISTER_HOOKS_SUPPORTED = gte(2, 8, 0);

packages/deno/src/import.mjs

@@ -0,0 +1,30 @@
+/**
+ * EXPERIMENTAL: orchestrion runtime hook for Deno.
+ *
+ * In Deno versions prior to 2.8.0, this will crash, as it
+ * relies on `Module.registerHooks`, which was added in that
+ * version.
+ *
+ * As of Deno 2.8.3, this can be loaded via `--import` or `--preload`
+ * argument to `deno run` in order to enable these instrumentations.
+ *
+ * For example:
+ *
+ * ```bash
+ * $ deno run --import=@sentry/deno/import app.ts
+ * ```
+ *
+ * In Deno 2.8.0 through 2.8.2, it can be loaded directly in an
+ * `init.ts` file that then loads the app via dynamic import.
+ *
+ * For example:
+ *
+ * ```ts
+ * // init.ts
+ * import '@sentry/deno/import';
+ * await import('./app.ts');
+ * ```
+ *
+ * @module
+ */
+import '@sentry-internal/server-utils/orchestrion/import-hook';

packages/deno/src/index.ts

@@ -108,6 +108,7 @@ export { denoHttpIntegration } from './integrations/http';
 export type { DenoHttpIntegrationOptions } from './integrations/http';
 export { denoRedisIntegration } from './integrations/redis';
 export type { DenoRedisIntegrationOptions } from './integrations/redis';
+export { denoMysqlIntegration } from './integrations/mysql';
 export { denoContextIntegration } from './integrations/context';
 export { globalHandlersIntegration } from './integrations/globalhandlers';
 export { normalizePathsIntegration } from './integrations/normalizepaths';

packages/deno/src/integrations/mysql.ts

@@ -0,0 +1,34 @@
+import { mysqlChannelIntegration } from '@sentry-internal/server-utils/orchestrion';
+import type { Integration, IntegrationFn } from '@sentry/core';
+import { defineIntegration } from '@sentry/core';
+import { setAsyncLocalStorageAsyncContextStrategy } from '../async';
+
+const INTEGRATION_NAME = 'DenoMysql';
+
+/**
+ * Create spans for `mysql` queries under Deno.
+ *
+ * `mysql` channels are injected by the orchestrion runtime hook at load time.
+ * The `@sentry/deno/import` loader must be active for this integration to
+ * record anything.
+ *
+ * The channel-subscription logic is shared with the other server runtimes in
+ * `@sentry-internal/server-utils`. This just installs Deno's
+ * `AsyncLocalStorage` context strategy (so spans nest under the active
+ * span and survive mysql's internal callback dispatch) before delegating.
+ */
+const _denoMysqlIntegration = (() => {
+  const inner = mysqlChannelIntegration();
+  return {
+    name: INTEGRATION_NAME,
+    setupOnce() {
+      setAsyncLocalStorageAsyncContextStrategy();
+      inner.setupOnce?.();
+    },
+  };
+}) satisfies IntegrationFn;
+
+export const denoMysqlIntegration = defineIntegration(_denoMysqlIntegration) as () => Integration & {
+  name: 'DenoMysql';
+  setupOnce: () => void;
+};

packages/deno/src/sdk.ts

@@ -19,10 +19,12 @@ import { contextLinesIntegration } from './integrations/contextlines';
 import {
   HTTP_CLIENT_DIAGNOSTICS_CHANNEL_SUPPORTED,
   HTTP_SERVER_DIAGNOSTICS_CHANNEL_SUPPORTED,
+  MODULE_REGISTER_HOOKS_SUPPORTED,
   TRACING_CHANNEL_SUPPORTED,
 } from './denoVersion';
 import { denoServeIntegration } from './integrations/deno-serve';
 import { denoHttpIntegration } from './integrations/http';
+import { denoMysqlIntegration } from './integrations/mysql';
 import { denoRedisIntegration } from './integrations/redis';
 import { globalHandlersIntegration } from './integrations/globalhandlers';
 import { normalizePathsIntegration } from './integrations/normalizepaths';
@@ -54,6 +56,11 @@ export function getDefaultIntegrations(_options: Options): Integration[] {
       : []),
     // node:diagnostics_channel.tracingChannel exists on Deno 1.44.3+.
     ...(TRACING_CHANNEL_SUPPORTED ? [denoRedisIntegration()] : []),
+    // orchestrion-based instrumentations.
+    // It's possible that the orchestrion channels will be injected AFTER
+    // (or in parallel to) loading the SDK, so we only gate on whether the
+    // feature is possible. If they're never loaded, it'll just be a no-op.
+    ...(MODULE_REGISTER_HOOKS_SUPPORTED ? [denoMysqlIntegration()] : []),
     contextLinesIntegration(),
     normalizePathsIntegration(),
     globalHandlersIntegration(),

packages/deno/test/__snapshots__/mod.test.ts.snap

@@ -115,6 +115,7 @@ snapshot[`captureException 1`] = `
       "DenoServe",
       "DenoHttp",
       "DenoRedis",
+      "DenoMysql",
       "ContextLines",
       "NormalizePaths",
       "GlobalHandlers",
@@ -190,6 +191,7 @@ snapshot[`captureMessage 1`] = `
       "DenoServe",
       "DenoHttp",
       "DenoRedis",
+      "DenoMysql",
       "ContextLines",
       "NormalizePaths",
       "GlobalHandlers",
@@ -272,6 +274,7 @@ snapshot[`captureMessage twice 1`] = `
       "DenoServe",
       "DenoHttp",
       "DenoRedis",
+      "DenoMysql",
       "ContextLines",
       "NormalizePaths",
       "GlobalHandlers",
@@ -361,6 +364,7 @@ snapshot[`captureMessage twice 2`] = `
       "DenoServe",
       "DenoHttp",
       "DenoRedis",
+      "DenoMysql",
       "ContextLines",
       "NormalizePaths",
       "GlobalHandlers",

packages/deno/test/orchestrion-mysql.test.ts

@@ -0,0 +1,53 @@
+// <reference lib="deno.ns" />
+
+import { assert } from 'https://deno.land/std@0.212.0/assert/assert.ts';
+import { assertEquals } from 'https://deno.land/std@0.212.0/assert/assert_equals.ts';
+import type { DenoClient } from '../build/esm/index.js';
+import { getCurrentScope, getGlobalScope, getIsolationScope, init } from '../build/esm/index.js';
+
+function resetGlobals(): void {
+  getCurrentScope().clear();
+  getCurrentScope().setClient(undefined);
+  getIsolationScope().clear();
+  getGlobalScope().clear();
+}
+
+Deno.test('denoMysqlIntegration: included in default integrations (Deno 2.8.0+)', () => {
+  resetGlobals();
+  const client = init({ dsn: 'https://username@domain/123' }) as DenoClient;
+  const names = client.getOptions().integrations.map(i => i.name);
+  assert(names.includes('DenoMysql'), `DenoMysql should be in defaults, got ${names.join(', ')}`);
+});
+
+// The orchestrion runtime hook (`@sentry/deno/import`) only works as a FIRST
+// import inside the entry graph in Deno 2.8.0 through 2.8.2.
+// TODO: revisit a `--import` or `--preload` approach once Deno 2.8.3 ships.
+Deno.test('@sentry/deno/import: transforms mysql so it publishes the orchestrion channel', async () => {
+  const scenario = new URL('./orchestrion-mysql/scenario.mjs', import.meta.url);
+
+  // packages/deno — where node_modules resolves
+  const cwd = new URL('../', import.meta.url);
+
+  const command = new Deno.Command('deno', {
+    args: ['run', '--allow-all', scenario.pathname],
+    cwd: cwd.pathname,
+    stdout: 'piped',
+    stderr: 'piped',
+  });
+
+  const { code, stdout, stderr } = await command.output();
+  const out = new TextDecoder().decode(stdout);
+  const err = new TextDecoder().decode(stderr);
+
+  assertEquals(code, 0, `scenario exited ${code}\nstdout:\n${out}\nstderr:\n${err}`);
+
+  const line = out.split('\n').find(l => l.startsWith('SCENARIO')) ?? '';
+  assert(line, `no SCENARIO line in output:\n${out}\nstderr:\n${err}`);
+  // The injected channel fired on `connection.query()`
+  // proves mysql was transformed...
+  assert(line.includes('events=start'), `expected channel 'start' event, got: ${line}`);
+  // ...with the real SQL forwarded through the channel context.
+  assert(line.includes('statement=SELECT 1 AS solution'), `expected forwarded SQL, got: ${line}`);
+  // The runtime hook set its detection marker at boot.
+  assert(line.includes('"runtime":true'), `expected runtime marker, got: ${line}`);
+});