Skip to content
Draft
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@
---
title: ClickHouse
description: "Adds instrumentation for the ClickHouse JavaScript clients. (default)"
supportedCategories:
- server
- serverless
---

<AvailableSince version="11.17.0" />

_Import name: `Sentry.clickhouseIntegration`_

This integration is enabled by default when <PlatformLink to="/tracing/">tracing</PlatformLink> is enabled. To customize it, see [Modifying Default Integrations](./../#modifying-default-integrations).

The `clickhouseIntegration` adds instrumentation for the official ClickHouse clients: [`@clickhouse/client`](https://www.npmjs.com/package/@clickhouse/client) for Node.js and [`@clickhouse/client-web`](https://www.npmjs.com/package/@clickhouse/client-web) for web runtimes such as Cloudflare Workers. It creates a `db` span for each statement the client sends, so slow or failing ClickHouse queries show up in your traces.

```javascript
Sentry.init({
dsn: "___PUBLIC_DSN___",
tracesSampleRate: 1.0,
integrations: [Sentry.clickhouseIntegration()],
});
```

<PlatformSection supported={["javascript.nextjs"]}>

Run ClickHouse calls in the Node.js runtime. This automatic instrumentation isn't available in the Edge runtime.

</PlatformSection>

<PlatformSection supported={["javascript.cloudflare"]}>

On Cloudflare Workers, use `@clickhouse/client-web` and build your Worker with the <PlatformLink to="/install/vite-plugin/">Sentry Cloudflare Vite plugin</PlatformLink>. The plugin traces the client automatically, as long as `@clickhouse/client-web` is bundled and not marked as external. If you deploy with `wrangler` directly, ClickHouse calls aren't traced.

</PlatformSection>

<PlatformSection supported={["javascript.deno"]}>

On Deno, preload Sentry's import hook so the ClickHouse client can be instrumented:

```bash
deno run --allow-net --allow-env --allow-read --allow-sys --allow-write --preload=npm:@sentry/deno/import app.ts
```

</PlatformSection>

<PlatformSection supported={["javascript.bun", "javascript.elysia"]}>

On Bun, automatic instrumentation requires a build with `sentryBunPlugin()` and `@clickhouse/client` included in the bundle:

```typescript {filename:build.ts}
import { sentryBunPlugin } from "@sentry/bun/plugin";

await Bun.build({
entrypoints: ["./src/index.ts"],
outdir: "./dist",
target: "bun",
plugins: [sentryBunPlugin()],
});
```

</PlatformSection>

## Supported Operations

The integration traces these `ClickHouseClient` methods:

- `query()`
- `command()`
- `exec()`
- `insert()`

`ping()` and `close()` don't send a statement, so they don't create spans. An `insert()` with an empty `values` array doesn't send a request and doesn't create a span either.

Spans are only created inside an active span, such as a request handler or a span you start with <PlatformLink to="/tracing/instrumentation/">`Sentry.startSpan()`</PlatformLink>.

## Spans

Each span is named after the operation and the table it targets, for example `SELECT events` or `INSERT events`. Span attributes follow Sentry's `db.*` conventions, with `db.system.name` set to `clickhouse`. The spans also record the database, the user, and the server address and port of the client.

Query text is sanitized before it's sent to Sentry:

- String and number literals are replaced with `?`. For example, `SELECT name FROM events WHERE name = 'signup'` is recorded as `SELECT name FROM events WHERE name = ?`.
- Comments are removed.
- Inline data sent with a statement, such as the rows after `INSERT INTO events FORMAT CSV`, is removed.
- ClickHouse query parameters, such as `{id:UInt32}`, are kept as written. Their values, passed in `query_params`, aren't recorded.
- `insert()` spans record the target table, but not the inserted values or a query text.

## Errors

When a call fails, the span gets an error status. The integration doesn't capture the error, because the client still rejects to your code, which can handle it. Errors you don't handle are captured like any other unhandled error.

## Supported Versions

- `@clickhouse/client`: `>=1.1.0 <2`
- `@clickhouse/client-web`: `>=1.1.0 <2`
Loading