From 93a2a829a64f03e9d65aed1956196f2bf3b30b20 Mon Sep 17 00:00:00 2001 From: Mihir G <99999231+mihir119CH@users.noreply.github.com> Date: Thu, 18 Jun 2026 14:18:11 -0700 Subject: [PATCH 1/4] Document Datadog integration options for ClickHouse Added details on various Datadog integrations with ClickHouse, including API, Prometheus, Agent, and DBM integrations. Each integration's deployment mode, signals, and specific considerations are outlined. --- .../features/08_monitoring/integrations.md | 65 +++++++++++++++++++ 1 file changed, 65 insertions(+) diff --git a/docs/cloud/features/08_monitoring/integrations.md b/docs/cloud/features/08_monitoring/integrations.md index cf70a0a697d..0cbc228b8c0 100644 --- a/docs/cloud/features/08_monitoring/integrations.md +++ b/docs/cloud/features/08_monitoring/integrations.md @@ -22,6 +22,71 @@ Instead, use the Datadog [Agent](https://docs.datadoghq.com/agent/?tab=Linux) an For Prometheus endpoint setup details, see the [Prometheus integration page](/integrations/prometheus#integrating-with-datadog). +## Direct Datadog integration + +ClickHouse has multiple ways of integrating with Datadog, suited to different deployment modes. Each has its own tradeoffs, and some are owned by ClickHouse while others are owned by Datadog. Integrations are listed in recommended order. + +| Integration | Docs | Deployment | Signals | +|---|---|---|---| +| [ClickHouse Cloud Datadog API integration](#clickhouse-cloud-datadog-api-integration) *(recommended)* | [docs.datadoghq.com](https://docs.datadoghq.com/integrations/clickhouse-cloud/) | Cloud | Metrics | +| [ClickHouse Cloud Prometheus integration](#clickhouse-cloud-prometheus-integration) | [clickhouse.com/docs](https://clickhouse.com/docs/integrations/prometheus) | Cloud | Metrics | +| [ClickHouse Datadog Agent integration](#clickhouse-datadog-agent-integration) | [docs.datadoghq.com](https://docs.datadoghq.com/integrations/clickhouse/?tab=host) | OSS / Cloud | Logs, Metrics | +| [ClickHouse Datadog DBM](#clickhouse-datadog-dbm) | [datadoghq.com](https://www.datadoghq.com/product-preview/database-monitoring-for-clickhouse/) | OSS / Cloud | Logs, Metrics, Query Insights | + +### ClickHouse Cloud Datadog API integration + +The recommended way to serve service-level metrics from ClickHouse Cloud in Datadog. + +The customer provides a Datadog API key, and Datadog periodically polls the ClickHouse Cloud API to collect metrics using a push-based method authenticated via an OAuth handshake. + +- **Cloud only** — not suitable for OSS ClickHouse +- Metrics are **not** treated as custom metrics by Datadog +- Does **not** prevent the service from idling +- Ships with a pre-configured set of dashboards and monitors +For onboarding steps, see [ClickHouse Cloud & Datadog - Integration](#). + + + This integration is currently in Private Preview. + + +### ClickHouse Cloud Prometheus integration + +The most common and universal way to collect service-level and org-level telemetry from ClickHouse Cloud. + +The customer configures the Datadog Agent with the [OpenMetrics integration](https://docs.datadoghq.com/integrations/openmetrics/) to periodically poll the ClickHouse Cloud API and collect metrics. See the [Prometheus integration page](/products/cloud/features/monitoring/prometheus#integrating-with-datadog) for configuration details. + +- **Cloud only** — not suitable for OSS ClickHouse +- Metrics are treated as **custom metrics** by Datadog +- Does **not** prevent the service from going idle + +### ClickHouse Datadog Agent integration + +The most common way to get data from on-premises ClickHouse services into Datadog. It also works with ClickHouse Cloud, with some caveats. + +The Datadog Agent periodically polls the ClickHouse instance and collects metrics and logs. This integration ships with a pre-configured set of dashboards. + +**OSS ClickHouse:** logs and metrics fully supported. + +**ClickHouse Cloud (partial support):** +- Metrics only — logs are not supported +- Requires `datadog-cluster-agent` instead of `datadog-agent` +- **Will prevent the service from going idle** + + +### ClickHouse Datadog DBM + +Database Monitoring (DBM) for ClickHouse is developed and maintained by Datadog. It works by configuring the Datadog Agent to collect system tables data from the ClickHouse instance, providing query-level performance insights similar to what the ClickHouse Cloud Console provides natively. ClickHouse has no involvement in this integration — issues should be directed to Datadog or resolved by the customer. + +- Metrics are free; the customer pays extra for logs and system tables data ingestion +- **OSS ClickHouse:** fully supported +- **ClickHouse Cloud (partial support):** requires `datadog-cluster-agent` instead of `datadog-agent`; **will prevent the service from going idle** + + + + + + + ## Billing and Usage API {#billing-usage-api} From 7706086b1efa9b88de528acc33711bd2cab9910a Mon Sep 17 00:00:00 2001 From: Dominic Tran Date: Thu, 18 Jun 2026 16:51:18 -0500 Subject: [PATCH 2/4] Mechanical fixes for CI --- .../features/08_monitoring/integrations.md | 52 ++++++++----------- 1 file changed, 21 insertions(+), 31 deletions(-) diff --git a/docs/cloud/features/08_monitoring/integrations.md b/docs/cloud/features/08_monitoring/integrations.md index 0cbc228b8c0..ae2193a1e6a 100644 --- a/docs/cloud/features/08_monitoring/integrations.md +++ b/docs/cloud/features/08_monitoring/integrations.md @@ -9,6 +9,7 @@ doc_type: 'guide' --- import CommunityMonitoring from '@site/docs/_snippets/_community_monitoring.md'; +import PrivatePreviewBadge from '@theme/badges/PrivatePreviewBadge'; ## Direct Datadog integration {#direct-datadog} @@ -22,71 +23,60 @@ Instead, use the Datadog [Agent](https://docs.datadoghq.com/agent/?tab=Linux) an For Prometheus endpoint setup details, see the [Prometheus integration page](/integrations/prometheus#integrating-with-datadog). -## Direct Datadog integration - ClickHouse has multiple ways of integrating with Datadog, suited to different deployment modes. Each has its own tradeoffs, and some are owned by ClickHouse while others are owned by Datadog. Integrations are listed in recommended order. - + | Integration | Docs | Deployment | Signals | |---|---|---|---| | [ClickHouse Cloud Datadog API integration](#clickhouse-cloud-datadog-api-integration) *(recommended)* | [docs.datadoghq.com](https://docs.datadoghq.com/integrations/clickhouse-cloud/) | Cloud | Metrics | | [ClickHouse Cloud Prometheus integration](#clickhouse-cloud-prometheus-integration) | [clickhouse.com/docs](https://clickhouse.com/docs/integrations/prometheus) | Cloud | Metrics | | [ClickHouse Datadog Agent integration](#clickhouse-datadog-agent-integration) | [docs.datadoghq.com](https://docs.datadoghq.com/integrations/clickhouse/?tab=host) | OSS / Cloud | Logs, Metrics | | [ClickHouse Datadog DBM](#clickhouse-datadog-dbm) | [datadoghq.com](https://www.datadoghq.com/product-preview/database-monitoring-for-clickhouse/) | OSS / Cloud | Logs, Metrics, Query Insights | - -### ClickHouse Cloud Datadog API integration - + +### ClickHouse Cloud Datadog API integration {#clickhouse-cloud-datadog-api-integration} + + + The recommended way to serve service-level metrics from ClickHouse Cloud in Datadog. - + The customer provides a Datadog API key, and Datadog periodically polls the ClickHouse Cloud API to collect metrics using a push-based method authenticated via an OAuth handshake. - + - **Cloud only** — not suitable for OSS ClickHouse - Metrics are **not** treated as custom metrics by Datadog - Does **not** prevent the service from idling - Ships with a pre-configured set of dashboards and monitors For onboarding steps, see [ClickHouse Cloud & Datadog - Integration](#). - - - This integration is currently in Private Preview. - -### ClickHouse Cloud Prometheus integration - +### ClickHouse Cloud Prometheus integration {#clickhouse-cloud-prometheus-integration} + The most common and universal way to collect service-level and org-level telemetry from ClickHouse Cloud. - -The customer configures the Datadog Agent with the [OpenMetrics integration](https://docs.datadoghq.com/integrations/openmetrics/) to periodically poll the ClickHouse Cloud API and collect metrics. See the [Prometheus integration page](/products/cloud/features/monitoring/prometheus#integrating-with-datadog) for configuration details. - + +The customer configures the Datadog Agent with the [OpenMetrics integration](https://docs.datadoghq.com/integrations/openmetrics/) to periodically poll the ClickHouse Cloud API and collect metrics. See the [Prometheus integration page](/integrations/prometheus#integrating-with-datadog) for configuration details. + - **Cloud only** — not suitable for OSS ClickHouse - Metrics are treated as **custom metrics** by Datadog - Does **not** prevent the service from going idle -### ClickHouse Datadog Agent integration - +### ClickHouse Datadog Agent integration {#clickhouse-datadog-agent-integration} + The most common way to get data from on-premises ClickHouse services into Datadog. It also works with ClickHouse Cloud, with some caveats. - + The Datadog Agent periodically polls the ClickHouse instance and collects metrics and logs. This integration ships with a pre-configured set of dashboards. - + **OSS ClickHouse:** logs and metrics fully supported. - + **ClickHouse Cloud (partial support):** - Metrics only — logs are not supported - Requires `datadog-cluster-agent` instead of `datadog-agent` - **Will prevent the service from going idle** +### ClickHouse Datadog DBM {#clickhouse-datadog-dbm} -### ClickHouse Datadog DBM - Database Monitoring (DBM) for ClickHouse is developed and maintained by Datadog. It works by configuring the Datadog Agent to collect system tables data from the ClickHouse instance, providing query-level performance insights similar to what the ClickHouse Cloud Console provides natively. ClickHouse has no involvement in this integration — issues should be directed to Datadog or resolved by the customer. - + - Metrics are free; the customer pays extra for logs and system tables data ingestion - **OSS ClickHouse:** fully supported - **ClickHouse Cloud (partial support):** requires `datadog-cluster-agent` instead of `datadog-agent`; **will prevent the service from going idle** - - - - - - ## Billing and Usage API {#billing-usage-api} From 238133f88a3af9bfe2a58bb6b9e1c71c57aaad99 Mon Sep 17 00:00:00 2001 From: Dominic Tran Date: Thu, 18 Jun 2026 16:51:41 -0500 Subject: [PATCH 3/4] aspell and header --- scripts/aspell-ignore/en/aspell-dict.txt | 4 +++- styles/ClickHouse/Headings.yml | 1 + 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/scripts/aspell-ignore/en/aspell-dict.txt b/scripts/aspell-ignore/en/aspell-dict.txt index 5428b1e8a3f..b28c8aad987 100644 --- a/scripts/aspell-ignore/en/aspell-dict.txt +++ b/scripts/aspell-ignore/en/aspell-dict.txt @@ -1,4 +1,4 @@ -personal_ws-1.1 en 4047 +personal_ws-1.1 en 4049 AArch ACLs AICPA @@ -307,6 +307,7 @@ DB's DBAPI DBAs DBFS +DBM DBMSs DBPedia DBeaver @@ -2163,6 +2164,7 @@ damerauLevenshteinDistance dashboarding datacenter datacenters +datadoghq datafiles dataframe datagrip diff --git a/styles/ClickHouse/Headings.yml b/styles/ClickHouse/Headings.yml index ef4bcc1437a..563f1dde11e 100644 --- a/styles/ClickHouse/Headings.yml +++ b/styles/ClickHouse/Headings.yml @@ -65,6 +65,7 @@ exceptions: - Docker - Docker Compose - DigitalOcean Spaces + - Datadog Agent - Duo SAML - EDOT - Elastic Agent From 8d04dec3cbf5664d7fd39d2049b78095ce9e9642 Mon Sep 17 00:00:00 2001 From: Mihir G <99999231+mihir119CH@users.noreply.github.com> Date: Thu, 18 Jun 2026 16:15:21 -0700 Subject: [PATCH 4/4] Revise Datadog integration documentation Updated the section on Datadog integration to clarify recommendations and removed outdated warnings about ClickHouse Cloud compatibility. --- docs/cloud/features/08_monitoring/integrations.md | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/docs/cloud/features/08_monitoring/integrations.md b/docs/cloud/features/08_monitoring/integrations.md index ae2193a1e6a..6f167e94825 100644 --- a/docs/cloud/features/08_monitoring/integrations.md +++ b/docs/cloud/features/08_monitoring/integrations.md @@ -11,19 +11,11 @@ doc_type: 'guide' import CommunityMonitoring from '@site/docs/_snippets/_community_monitoring.md'; import PrivatePreviewBadge from '@theme/badges/PrivatePreviewBadge'; -## Direct Datadog integration {#direct-datadog} - -Datadog offers a ClickHouse Monitoring plugin for its agent which queries system tables directly. This integration provides comprehensive database monitoring with cluster awareness through `clusterAllReplicas` functionality. - -:::warning[Not recommended for ClickHouse Cloud] -The direct Datadog agent integration that queries system tables isn't recommended for ClickHouse Cloud deployments due to incompatibility with cost-optimizing idle behavior and operational limitations of the cloud proxy layer. -::: - -Instead, use the Datadog [Agent](https://docs.datadoghq.com/agent/?tab=Linux) and [OpenMetrics integration](https://docs.datadoghq.com/integrations/openmetrics/) to collect metrics from the ClickHouse Cloud Prometheus endpoint. This approach respects service idling behavior and maintains operational separation between monitoring and production workloads. For configuration guidance, see [Datadog's Prometheus and OpenMetrics integration documentation](https://docs.datadoghq.com/integrations/openmetrics/). +## Datadog integration {#direct-datadog} For Prometheus endpoint setup details, see the [Prometheus integration page](/integrations/prometheus#integrating-with-datadog). -ClickHouse has multiple ways of integrating with Datadog, suited to different deployment modes. Each has its own tradeoffs, and some are owned by ClickHouse while others are owned by Datadog. Integrations are listed in recommended order. +For users interested in monitoring their ClickHouse deployment in Datadog, ClickHouse offers multiple integrations, suited to different deployment modes. Each has its own tradeoffs, and some are owned by ClickHouse while others are owned by Datadog. Integrations are listed in recommended order. | Integration | Docs | Deployment | Signals | |---|---|---|---|