feat(node): add ClickHouse instrumentation

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

@@ -36,6 +36,7 @@
     "@aws-sdk/client-sfn": "^3.1161.0",
     "@aws-sdk/client-sns": "^3.1161.0",
     "@aws-sdk/client-sqs": "^3.1161.0",
+    "@clickhouse/client": "1.25.0",
     "@earendil-works/chord": "^1.4.0",
     "@earendil-works/pi-ai": "^1.4.0",
     "@earendil-works/pi-durable": "^1.4.0",

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

@@ -0,0 +1,20 @@
+services:
+  db:
+    image: clickhouse/clickhouse-server:25.8
+    restart: always
+    ports:
+      - '8123:8123'
+    environment:
+      CLICKHOUSE_DB: tests
+      CLICKHOUSE_USER: test
+      CLICKHOUSE_PASSWORD: test
+    ulimits:
+      nofile:
+        soft: 262144
+        hard: 262144
+    healthcheck:
+      test: ['CMD-SHELL', 'clickhouse-client --user test --password test --query "SELECT 1"']
+      interval: 2s
+      timeout: 3s
+      retries: 30
+      start_period: 5s

dev-packages/node-integration-tests/suites/tracing/clickhouse/instrument.mjs

@@ -0,0 +1,9 @@
+import * as Sentry from '@sentry/node';
+import { loggingTransport } from '@sentry-internal/node-integration-tests';
+
+Sentry.init({
+  dsn: 'https://public@dsn.ingest.sentry.io/1337',
+  release: '1.0',
+  tracesSampleRate: 1.0,
+  transport: loggingTransport,
+});

dev-packages/node-integration-tests/suites/tracing/clickhouse/scenario.mjs

@@ -0,0 +1,67 @@
+import * as Sentry from '@sentry/node';
+import { waitForConnection } from '@sentry-internal/node-integration-tests';
+import { createClient } from '@clickhouse/client';
+
+const client = createClient({
+  url: 'http://localhost:8123',
+  username: 'test',
+  password: 'test',
+  database: 'tests',
+});
+
+async function run() {
+  // `ping` isn't instrumented, so the probe adds no spans.
+  await waitForConnection(async () => {
+    const result = await client.ping();
+    if (!result.success) {
+      throw result.error;
+    }
+  });
+
+  await Sentry.startSpan({ name: 'Test Span', op: 'test' }, async () => {
+    try {
+      await client.command({
+        query: 'CREATE TABLE IF NOT EXISTS events (id UInt32, name String) ENGINE = MergeTree ORDER BY id',
+      });
+
+      await client.insert({ table: 'events', values: [{ id: 1, name: 'signup' }], format: 'JSONEachRow' });
+      await client.command({ query: 'INSERT INTO events FORMAT CSV\n2,inline-sensitive@example.com' });
+
+      const literal = await client.query({
+        query: "SELECT name FROM events WHERE name = 'signup'",
+        format: 'JSONEachRow',
+      });
+      await literal.json();
+
+      const nestedComment = await client.query({
+        query: 'SELECT 1 /* outer /* inner */ private@example.com */',
+        format: 'JSONEachRow',
+      });
+      await nestedComment.json();
+
+      const parameterized = await client.query({
+        query: 'SELECT name FROM events WHERE id = {id:UInt32}',
+        query_params: { id: 1 },
+        format: 'JSONEachRow',
+      });
+      await parameterized.json();
+
+      const { stream } = await client.exec({ query: 'SELECT count() FROM events FORMAT JSONEachRow' });
+      for await (const _chunk of stream) {
+        // drain the response so the socket is released
+      }
+
+      // Failed calls the caller handles: each should leave an errored span and no error event.
+      await client.query({ query: 'SELECT * FROM does_not_exist' }).catch(() => {});
+      await client.command({ query: 'DROP TABLE does_not_exist' }).catch(() => {});
+      await client.exec({ query: 'SELECT * FROM does_not_exist FORMAT JSONEachRow' }).catch(() => {});
+      await client.insert({ table: 'does_not_exist', values: [{ id: 1 }], format: 'JSONEachRow' }).catch(() => {});
+    } finally {
+      await client.command({ query: 'DROP TABLE IF EXISTS events' });
+    }
+  });
+
+  await client.close();
+}
+
+run();

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

@@ -0,0 +1,118 @@
+import type { SerializedStreamedSpanContainer } from '@sentry/core';
+import {
+  DB_COLLECTION_NAME,
+  DB_NAMESPACE,
+  DB_OPERATION_NAME,
+  DB_QUERY_SUMMARY,
+  DB_QUERY_TEXT,
+  DB_SYSTEM_NAME,
+  DB_USER,
+  SENTRY_KIND,
+  SENTRY_OP,
+  SENTRY_ORIGIN,
+  SERVER_ADDRESS,
+  SERVER_PORT,
+} from '@sentry/conventions/attributes';
+import { DB } from '@sentry/conventions/op';
+import { afterAll, describe, expect } from 'vitest';
+import { streamedAttribute as attr } from '../../../utils';
+import { cleanupChildProcesses, createEsmAndCjsTests, describeWithDockerCompose } from '../../../utils/runner';
+
+const ORIGIN = 'auto.db.clickhouse';
+
+const CONNECTION_ATTRIBUTES = {
+  [SENTRY_OP]: attr(DB),
+  [SENTRY_KIND]: attr('client'),
+  [SENTRY_ORIGIN]: attr(ORIGIN),
+  [DB_SYSTEM_NAME]: attr('clickhouse'),
+  [DB_NAMESPACE]: attr('tests'),
+  [DB_USER]: attr('test'),
+  [SERVER_ADDRESS]: attr('localhost'),
+  [SERVER_PORT]: attr(8123, 'integer'),
+};
+
+const CREATE_TABLE = 'CREATE TABLE IF NOT EXISTS events (id UInt32, name String) ENGINE = MergeTree ORDER BY id';
+
+// One entry per instrumented call, in the order the scenario makes them.
+const EXPECTED_SPANS = [
+  { name: 'CREATE TABLE events', status: 'ok', operation: 'CREATE', text: CREATE_TABLE },
+  { name: 'INSERT events', status: 'ok', operation: 'INSERT', text: undefined, collection: 'events' },
+  { name: 'INSERT events', status: 'ok', operation: 'INSERT', text: 'INSERT INTO events' },
+  // the string literal is sanitized out of the statement
+  { name: 'SELECT events', status: 'ok', operation: 'SELECT', text: 'SELECT name FROM events WHERE name = ?' },
+  // nested comments are removed before the query reaches the span
+  { name: 'SELECT', status: 'ok', operation: 'SELECT', text: 'SELECT ?' },
+  // `{name:Type}` query parameters are kept as written
+  { name: 'SELECT events', status: 'ok', operation: 'SELECT', text: 'SELECT name FROM events WHERE id = {id:UInt32}' },
+  { name: 'SELECT events', status: 'ok', operation: 'SELECT', text: 'SELECT count() FROM events FORMAT JSONEachRow' },
+  // handled failures, one per method
+  { name: 'SELECT does_not_exist', status: 'error', operation: 'SELECT', text: 'SELECT * FROM does_not_exist' },
+  { name: 'DROP TABLE does_not_exist', status: 'error', operation: 'DROP', text: 'DROP TABLE does_not_exist' },
+  {
+    name: 'SELECT does_not_exist',
+    status: 'error',
+    operation: 'SELECT',
+    text: 'SELECT * FROM does_not_exist FORMAT JSONEachRow',
+  },
+  {
+    name: 'INSERT does_not_exist',
+    status: 'error',
+    operation: 'INSERT',
+    text: undefined,
+    collection: 'does_not_exist',
+  },
+  { name: 'DROP TABLE events', status: 'ok', operation: 'DROP', text: 'DROP TABLE IF EXISTS events' },
+];
+
+function assertClickhouseSpans(container: SerializedStreamedSpanContainer): void {
+  const segment = container.items.find(span => span.is_segment);
+  expect(segment?.name).toBe('Test Span');
+
+  const spans = container.items.filter(span => span.attributes[SENTRY_ORIGIN]?.value === ORIGIN);
+  for (const span of spans) {
+    expect(span.parent_span_id).toBe(segment?.span_id);
+    expect(span.attributes).toEqual(expect.objectContaining(CONNECTION_ATTRIBUTES));
+  }
+
+  expect(
+    spans.map(span => ({
+      name: span.name,
+      status: span.status,
+      operation: span.attributes[DB_OPERATION_NAME]?.value,
+      text: span.attributes[DB_QUERY_TEXT]?.value,
+      ...(span.attributes[DB_COLLECTION_NAME] ? { collection: span.attributes[DB_COLLECTION_NAME].value } : {}),
+    })),
+  ).toEqual(EXPECTED_SPANS);
+  expect(spans.map(span => span.attributes[DB_QUERY_SUMMARY]?.value)).toEqual(EXPECTED_SPANS.map(span => span.name));
+}
+
+describeWithDockerCompose('clickhouse auto instrumentation', { workingDirectory: [__dirname] }, () => {
+  afterAll(() => {
+    cleanupChildProcesses();
+  });
+
+  // The span container is the only envelope expected. A captured error would arrive as an `event`
+  // envelope ahead of it and fail the run, so this also checks that handled failures aren't captured.
+  describe('@clickhouse/client >=1.23', () => {
+    createEsmAndCjsTests(__dirname, 'scenario.mjs', 'instrument.mjs', (createTestRunner, test) => {
+      test('instruments `query`, `command`, `exec` and `insert`', { timeout: 90_000 }, async () => {
+        await createTestRunner().expect({ span: assertClickhouseSpans }).start().completed();
+      });
+    });
+  });
+
+  // Before 1.23.0 the client lives in the separate `@clickhouse/client-common` package.
+  describe('@clickhouse/client <1.23', () => {
+    createEsmAndCjsTests(
+      __dirname,
+      'scenario.mjs',
+      'instrument.mjs',
+      (createTestRunner, test) => {
+        test('instruments `query`, `command`, `exec` and `insert`', { timeout: 90_000 }, async () => {
+          await createTestRunner().expect({ span: assertClickhouseSpans }).start().completed();
+        });
+      },
+      { additionalDependencies: { '@clickhouse/client': '1.22.0' } },
+    );
+  });
+});

packages/astro/src/index.server.ts

@@ -118,6 +118,7 @@ export {
   postgresIntegration,
   postgresJsIntegration,
   neonIntegration,
+  clickhouseIntegration,
   prismaIntegration,
   openTelemetryIntegration,
   getOtlpTracesEndpoint,

packages/aws-serverless/src/index.ts

@@ -137,6 +137,7 @@ export {
   postgresIntegration,
   postgresJsIntegration,
   neonIntegration,
+  clickhouseIntegration,
   processSessionIntegration,
   prismaIntegration,
   openTelemetryIntegration,

packages/bun/src/index.ts

@@ -160,6 +160,7 @@ export {
   postgresIntegration,
   postgresJsIntegration,
   neonIntegration,
+  clickhouseIntegration,
   prismaIntegration,
   openTelemetryIntegration,
   getOtlpTracesEndpoint,

packages/cloudflare/src/index.ts

@@ -191,6 +191,7 @@ export {
   mysql2Integration,
   mysqlIntegration,
   neonIntegration,
+  clickhouseIntegration,
   nitroIntegration,
   openAIIntegration,
   piDurableIntegration,

packages/deno/src/index.ts

@@ -195,6 +195,7 @@ export {
   postgresIntegration,
   postgresJsIntegration,
   neonIntegration,
+  clickhouseIntegration,
   cronJobIntegration,
   nodeCronIntegration,
   nodeScheduleIntegration,

packages/elysia/src/index.ts

@@ -134,6 +134,7 @@ export {
   postgresIntegration,
   postgresJsIntegration,
   neonIntegration,
+  clickhouseIntegration,
   prismaIntegration,
   processSessionIntegration,
   hapiIntegration,

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

@@ -137,6 +137,7 @@ export {
   postgresIntegration,
   postgresJsIntegration,
   neonIntegration,
+  clickhouseIntegration,
   prismaIntegration,
   openTelemetryIntegration,
   getOtlpTracesEndpoint,

packages/node/src/index.ts

@@ -48,6 +48,7 @@ export {
   postgresIntegration,
   postgresJsIntegration,
   neonIntegration,
+  clickhouseIntegration,
   redisIntegration,
   tediousIntegration,
   vercelAIIntegration,

packages/server-utils/src/index.ts

@@ -80,6 +80,7 @@ export { openAIIntegration } from './integrations/openai';
 export { postgresIntegration } from './integrations/pg';
 export { postgresJsIntegration } from './integrations/postgresjs';
 export { neonIntegration } from './integrations/neon';
+export { clickhouseIntegration } from './integrations/clickhouse';
 export { tediousIntegration } from './integrations/tedious';
 export { vercelAIIntegration } from './integrations/vercel-ai';
 export { expressIntegration } from './integrations/express';