feat(node): Add knex integration

dev-packages/node-integration-tests/package.json

@@ -47,6 +47,7 @@
     "graphql": "^16.3.0",
     "http-terminator": "^3.2.0",
     "ioredis": "^5.4.1",
+    "knex": "^2.5.1",
     "mongodb": "^3.7.3",
     "mongodb-memory-server-global": "^7.6.3",
     "mongoose": "^5.13.22",

dev-packages/node-integration-tests/suites/tracing/knex/docker-compose.yml

@@ -0,0 +1,23 @@
+version: '3.9'
+
+services:
+  db_postgres:
+    image: postgres:13
+    restart: always
+    container_name: integration-tests-knex-postgres
+    ports:
+      - '5445:5432'
+    environment:
+      POSTGRES_USER: test
+      POSTGRES_PASSWORD: test
+      POSTGRES_DB: tests
+
+  db_mysql2:
+    image: mysql:8
+    restart: always
+    container_name: integration-tests-knex-mysql2
+    ports:
+      - '3307:3306'
+    environment:
+      MYSQL_ROOT_PASSWORD: docker
+      MYSQL_DATABASE: tests

dev-packages/node-integration-tests/suites/tracing/knex/scenario-withMysql2.js

@@ -0,0 +1,52 @@
+const { loggingTransport } = require('@sentry-internal/node-integration-tests');
+const Sentry = require('@sentry/node');
+
+Sentry.init({
+  dsn: 'https://public@dsn.ingest.sentry.io/1337',
+  release: '1.0',
+  tracesSampleRate: 1.0,
+  transport: loggingTransport,
+});
+
+// Stop the process from exiting before the transaction is sent
+setInterval(() => {}, 1000);
+
+const knex = require('knex').default;
+
+const mysql2Client = knex({
+  client: 'mysql2',
+  connection: {
+    host: 'localhost',
+    port: 3307,
+    user: 'root',
+    password: 'docker',
+    database: 'tests',
+  },
+});
+
+async function run() {
+  await Sentry.startSpan(
+    {
+      name: 'Test Transaction',
+      op: 'transaction',
+    },
+    async () => {
+      try {
+        await mysql2Client.schema.createTable('User', table => {
+          table.increments('id').notNullable().primary({ constraintName: 'User_pkey' });
+          table.timestamp('createdAt', { precision: 3 }).notNullable().defaultTo(mysql2Client.fn.now(3));
+          table.text('email').notNullable();
+          table.text('name').notNullable();
+        });
+
+        await mysql2Client('User').insert({ name: 'jane', email: 'jane@domain.com' });
+        await mysql2Client('User').select('*');
+      } finally {
+        await mysql2Client.destroy();
+      }
+    },
+  );
+}
+
+// eslint-disable-next-line @typescript-eslint/no-floating-promises
+run();

dev-packages/node-integration-tests/suites/tracing/knex/scenario-withPostgres.js

@@ -0,0 +1,52 @@
+const { loggingTransport } = require('@sentry-internal/node-integration-tests');
+const Sentry = require('@sentry/node');
+
+Sentry.init({
+  dsn: 'https://public@dsn.ingest.sentry.io/1337',
+  release: '1.0',
+  tracesSampleRate: 1.0,
+  transport: loggingTransport,
+});
+
+// Stop the process from exiting before the transaction is sent
+setInterval(() => {}, 1000);
+
+const knex = require('knex').default;
+
+const pgClient = knex({
+  client: 'pg',
+  connection: {
+    host: 'localhost',
+    port: 5445,
+    user: 'test',
+    password: 'test',
+    database: 'tests',
+  },
+});
+
+async function run() {
+  await Sentry.startSpan(
+    {
+      name: 'Test Transaction',
+      op: 'transaction',
+    },
+    async () => {
+      try {
+        await pgClient.schema.createTable('User', table => {
+          table.increments('id').notNullable().primary({ constraintName: 'User_pkey' });
+          table.timestamp('createdAt', { precision: 3 }).notNullable().defaultTo(pgClient.fn.now(3));
+          table.text('email').notNullable();
+          table.text('name').notNullable();
+        });
+
+        await pgClient('User').insert({ name: 'bob', email: 'bob@domain.com' });
+        await pgClient('User').select('*');
+      } finally {
+        await pgClient.destroy();
+      }
+    },
+  );
+}
+
+// eslint-disable-next-line @typescript-eslint/no-floating-promises
+run();

dev-packages/node-integration-tests/suites/tracing/knex/test.ts

@@ -0,0 +1,120 @@
+import { createRunner } from '../../../utils/runner';
+
+// When running docker compose, we need a larger timeout, as this takes some time...
+jest.setTimeout(90000);
+
+describe('knex auto instrumentation', () => {
+  test('should auto-instrument `knex` package when using `pg` client', done => {
+    const EXPECTED_TRANSACTION = {
+      transaction: 'Test Transaction',
+      spans: expect.arrayContaining([
+        expect.objectContaining({
+          data: expect.objectContaining({
+            'db.system': 'knex',
+            'db.name': 'tests',
+            'sentry.origin': 'auto.db.otel.knex',
+            'sentry.op': 'db',
+            'net.peer.name': 'localhost',
+            'net.peer.port': 5445,
+          }),
+          status: 'ok',
+          description:
+            'create table "User" ("id" serial primary key, "createdAt" timestamptz(3) not null default CURRENT_TIMESTAMP(3), "email" text not null, "name" text not null)',
+          origin: 'auto.db.otel.knex',
+        }),
+        expect.objectContaining({
+          data: expect.objectContaining({
+            'db.system': 'knex',
+            'db.name': 'tests',
+            'sentry.origin': 'auto.db.otel.knex',
+            'sentry.op': 'db',
+            'net.peer.name': 'localhost',
+            'net.peer.port': 5445,
+          }),
+          status: 'ok',
+          // In the knex-otel spans, the placeholders (e.g., `$1`) are replaced by a `?`.
+          description: 'insert into "User" ("email", "name") values (?, ?)',
+          origin: 'auto.db.otel.knex',
+        }),
+
+        expect.objectContaining({
+          data: expect.objectContaining({
+            'db.operation': 'select',
+            'db.sql.table': 'User',
+            'db.system': 'knex',
+            'db.name': 'tests',
+            'db.statement': 'select * from "User"',
+            'sentry.origin': 'auto.db.otel.knex',
+            'sentry.op': 'db',
+          }),
+          status: 'ok',
+          description: 'select * from "User"',
+          origin: 'auto.db.otel.knex',
+        }),
+      ]),
+    };
+
+    createRunner(__dirname, 'scenario-withPostgres.js')
+      .withDockerCompose({ workingDirectory: [__dirname], readyMatches: ['port 5432'] })
+      .expect({ transaction: EXPECTED_TRANSACTION })
+      .start(done);
+  });
+
+  test('should auto-instrument `knex` package when using `mysql2` client', done => {
+    const EXPECTED_TRANSACTION = {
+      transaction: 'Test Transaction',
+      spans: expect.arrayContaining([
+        expect.objectContaining({
+          data: expect.objectContaining({
+            'db.system': 'knex',
+            'db.name': 'tests',
+            'db.user': 'root',
+            'sentry.origin': 'auto.db.otel.knex',
+            'sentry.op': 'db',
+            'net.peer.name': 'localhost',
+            'net.peer.port': 3307,
+          }),
+          status: 'ok',
+          description:
+            'create table `User` (`id` int unsigned not null auto_increment primary key, `createdAt` timestamp(3) not null default CURRENT_TIMESTAMP(3), `email` text not null, `name` text not null)',
+          origin: 'auto.db.otel.knex',
+        }),
+        expect.objectContaining({
+          data: expect.objectContaining({
+            'db.system': 'knex',
+            'db.name': 'tests',
+            'db.user': 'root',
+            'sentry.origin': 'auto.db.otel.knex',
+            'sentry.op': 'db',
+            'net.peer.name': 'localhost',
+            'net.peer.port': 3307,
+          }),
+          status: 'ok',
+          description: 'insert into `User` (`email`, `name`) values (?, ?)',
+          origin: 'auto.db.otel.knex',
+        }),
+
+        expect.objectContaining({
+          data: expect.objectContaining({
+            'db.operation': 'select',
+            'db.sql.table': 'User',
+            'db.system': 'knex',
+            'db.name': 'tests',
+            'db.statement': 'select * from `User`',
+            'db.user': 'root',
+            'sentry.origin': 'auto.db.otel.knex',
+            'sentry.op': 'db',
+          }),
+          status: 'ok',
+          description: 'select * from `User`',
+          origin: 'auto.db.otel.knex',
+        }),
+      ]),
+    };
+
+    createRunner(__dirname, 'scenario-withMysql2.js')
+      .withDockerCompose({ workingDirectory: [__dirname], readyMatches: ['port: 3306'] })
+      .expect({ transaction: EXPECTED_TRANSACTION })
+      .start(done);
+  });
+});

packages/astro/src/index.server.ts

@@ -65,6 +65,7 @@ export {
   initOpenTelemetry,
   isInitialized,
   koaIntegration,
+  knexIntegration,
   lastEventId,
   linkedErrorsIntegration,
   localVariablesIntegration,

packages/aws-serverless/src/index.ts

@@ -88,6 +88,7 @@ export {
   fastifyIntegration,
   fsIntegration,
   graphqlIntegration,
+  knexIntegration,
   mongoIntegration,
   mongooseIntegration,
   mysqlIntegration,

packages/bun/src/index.ts

@@ -109,6 +109,7 @@ export {
   connectIntegration,
   setupConnectErrorHandler,
   graphqlIntegration,
+  knexIntegration,
   mongoIntegration,
   mongooseIntegration,
   mysqlIntegration,

packages/google-cloud-serverless/src/index.ts

@@ -88,6 +88,7 @@ export {
   setupConnectErrorHandler,
   fastifyIntegration,
   graphqlIntegration,
+  knexIntegration,
   mongoIntegration,
   mongooseIntegration,
   mysqlIntegration,

packages/node/package.json

@@ -77,6 +77,7 @@
     "@opentelemetry/instrumentation-hapi": "0.40.0",
     "@opentelemetry/instrumentation-http": "0.52.1",
     "@opentelemetry/instrumentation-ioredis": "0.42.0",
+    "@opentelemetry/instrumentation-knex": "0.39.0",
     "@opentelemetry/instrumentation-koa": "0.42.0",
     "@opentelemetry/instrumentation-mongodb": "0.46.0",
     "@opentelemetry/instrumentation-mongoose": "0.40.0",

packages/node/src/index.ts

@@ -26,6 +26,7 @@ export { hapiIntegration, setupHapiErrorHandler } from './integrations/tracing/h
 export { koaIntegration, setupKoaErrorHandler } from './integrations/tracing/koa';
 export { connectIntegration, setupConnectErrorHandler } from './integrations/tracing/connect';
 export { spotlightIntegration } from './integrations/spotlight';
+export { knexIntegration } from './integrations/tracing/knex';
 
 export { SentryContextManager } from './otel/contextManager';
 export { generateInstrumentOnce } from './otel/instrument';

packages/node/src/integrations/tracing/index.ts

@@ -6,6 +6,7 @@ import { expressIntegration, instrumentExpress } from './express';
 import { fastifyIntegration, instrumentFastify } from './fastify';
 import { graphqlIntegration, instrumentGraphql } from './graphql';
 import { hapiIntegration, instrumentHapi } from './hapi';
+import { instrumentKnex, knexIntegration } from './knex';
 import { instrumentKoa, koaIntegration } from './koa';
 import { instrumentMongo, mongoIntegration } from './mongo';
 import { instrumentMongoose, mongooseIntegration } from './mongoose';
@@ -37,6 +38,7 @@ export function getAutoPerformanceIntegrations(): Integration[] {
     hapiIntegration(),
     koaIntegration(),
     connectIntegration(),
+    knexIntegration(),
   ];
 }
 
@@ -61,5 +63,6 @@ export function getOpenTelemetryInstrumentationToPreload(): (((options?: any) =>
     instrumentHapi,
     instrumentGraphql,
     instrumentRedis,
+    instrumentKnex,
   ];
 }

packages/node/src/integrations/tracing/knex.ts

@@ -0,0 +1,39 @@
+import { KnexInstrumentation } from '@opentelemetry/instrumentation-knex';
+import { SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN, defineIntegration, spanToJSON } from '@sentry/core';
+import type { IntegrationFn } from '@sentry/types';
+import { generateInstrumentOnce } from '../../otel/instrument';
+
+const INTEGRATION_NAME = 'Knex';
+
+export const instrumentKnex = generateInstrumentOnce(
+  INTEGRATION_NAME,
+  () => new KnexInstrumentation({ requireParentSpan: true }),
+);
+
+const _knexIntegration = (() => {
+  return {
+    name: INTEGRATION_NAME,
+    setupOnce() {
+      instrumentKnex();
+    },
+
+    setup(client) {
+      client.on('spanStart', span => {
+        const spanJSON = spanToJSON(span);
+        const spanData = spanJSON.data;
+
+        if (spanData && 'knex.version' in spanData) {
+          span.setAttribute(SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN, 'auto.db.otel.knex');
+          span.setAttribute('db.system', 'knex');
+        }
+      });
+    },
+  };
+}) satisfies IntegrationFn;
+
+/**
+ * Knex integration
+ *
+ * Capture tracing data for Knex.
+ */
+export const knexIntegration = defineIntegration(_knexIntegration);

packages/remix/src/index.server.ts

@@ -66,6 +66,7 @@ export {
   inboundFiltersIntegration,
   initOpenTelemetry,
   isInitialized,
+  knexIntegration,
   koaIntegration,
   lastEventId,
   linkedErrorsIntegration,

packages/solidstart/src/server/index.ts

@@ -57,6 +57,7 @@ export {
   inboundFiltersIntegration,
   initOpenTelemetry,
   isInitialized,
+  knexIntegration,
   koaIntegration,
   lastEventId,
   linkedErrorsIntegration,

packages/sveltekit/src/server/index.ts

@@ -59,6 +59,7 @@ export {
   inboundFiltersIntegration,
   initOpenTelemetry,
   isInitialized,
+  knexIntegration,
   koaIntegration,
   lastEventId,
   linkedErrorsIntegration,