ClickHouse is a columnar OLAP database designed for analytical workloads, and recommended for production observability. The new ClickHouse storage adapter gives your Mastra application high-throughput writes and millisecond aggregate queries.
Mastra's observability layer collects the telemetry to monitor AI applications at scale.
The storage adapter persists the data in ClickHouse. Studio surfaces aggregate trends on the metrics dashboard, and individual runs in traces and logs.
ClickHouse is suitable for deployment platforms with ephemeral filesystems and won't lose data on restart. It can run on your own infrastructure or as a hosted service.
Get started
Install the ClickHouse adapter:
1npm install @mastra/clickhouseRequires @mastra/core@1.29.0 or later, added in PR #14696.
Configure Observability on your main Mastra instance with the DefaultExporter. Use MastraCompositeStore to configure the observability domain and attach the ObservabilityStorageClickhouseVNext.
1import { Mastra } from "@mastra/core";
2import { MastraCompositeStore } from "@mastra/core/storage";
3import { ObservabilityStorageClickhouseVNext } from "@mastra/clickhouse";
4import { Observability, DefaultExporter } from "@mastra/observability";
5
6export const mastra = new Mastra({
7 storage: new MastraCompositeStore({
8 id: "composite-storage",
9 default: {
10 // ...
11 },
12 domains: {
13 observability: new ObservabilityStorageClickhouseVNext({
14 url: process.env.CLICKHOUSE_URL!,
15 username: process.env.CLICKHOUSE_USERNAME!,
16 password: process.env.CLICKHOUSE_PASSWORD!
17 })
18 }
19 }),
20 observability: new Observability({
21 configs: {
22 default: {
23 serviceName: "mastra",
24 exporters: [new DefaultExporter()]
25 }
26 }
27 })
28});
29// VNext is the recommended schema for new projects.
30// For the legacy schema, see:
31// https://mastra.ai/reference/storage/clickhouse#observability-with-the-legacy-domainFor more information and full configuration options, see:
