Skip to content

Commit 844505a

Browse files
ArctypeZachArctypeZach
committed
Add filtered metrics request param to prom endpoint
1 parent d86e33e commit 844505a

File tree

1 file changed

+83
-81
lines changed

1 file changed

+83
-81
lines changed

‎docs/en/integrations/prometheus.md

Lines changed: 83 additions & 81 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ slug: /en/integrations/prometheus
33
sidebar_label: Prometheus
44
title: Prometheus
55
description: Export ClickHouse metrics to Prometheus
6-
keywords: [prometheus, grafana, monitoring, metrics, exporter]
6+
keywords: [prometheus, grafana, monitoring, metrics, exporter]
77
---
88

99
# Prometheus Integration
@@ -16,16 +16,18 @@ To get started, [generate an API key](/en/cloud/manage/openapi).
1616

1717
### API Reference
1818

19-
|Method|Path|
20-
|---|---|
21-
|GET|https://api.clickhouse.cloud/v1/organizations/:organizationId/services/:serviceId/prometheus|
19+
| Method | Path | Description |
20+
| ------ | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ |
21+
| GET | https://api.clickhouse.cloud/v1/organizations/:organizationId/services/:serviceId/prometheus | Returns the full set of metrics |
22+
| GET | https://api.clickhouse.cloud/v1/organizations/:organizationId/services/:serviceId/prometheus?filtered_metrics=true | Returns a filtered list of metrics to reduce response payload size |
2223

2324
**Request Parameters**
2425

25-
|Name|Type|
26-
|---|---|
27-
|Organization ID|uuid|
28-
|Service ID|uuid|
26+
| Name | Type |
27+
| ---------------- | ------------------ |
28+
| Organization ID | uuid |
29+
| Service ID | uuid |
30+
| filtered_metrics | boolean (optional) |
2931

3032
### Authentication
3133

@@ -39,7 +41,7 @@ export KEY_SECRET=<key_secret>
3941
export KEY_ID=<key_id>
4042
export ORG_ID=<org_id>
4143
export SERVICE_ID=<service_id>
42-
curl --silent --user $KEY_ID:$KEY_SECRET https://api.clickhouse.cloud/v1/organizations/$ORG_ID/services/$SERVICE_ID/prometheus
44+
curl --silent --user $KEY_ID:$KEY_SECRET https://api.clickhouse.cloud/v1/organizations/$ORG_ID/services/$SERVICE_ID/prometheus
4345
```
4446

4547
### Sample Response
@@ -74,23 +76,23 @@ ClickHouseProfileEvents_Seek{clickhouse_org="c2ba4799-a76e-456f-a71a-b021b1fafe6
7476

7577
All metrics have the following labels:
7678

77-
|Label|Description|
78-
|---|---|
79-
|clickhouse_org|Organization ID|
80-
|clickhouse_service|Service ID|
81-
|clickhouse_service_name|Service name|
79+
| Label | Description |
80+
| ----------------------- | --------------- |
81+
| clickhouse_org | Organization ID |
82+
| clickhouse_service | Service ID |
83+
| clickhouse_service_name | Service name |
8284

8385
### Information Metrics
8486

8587
ClickHouse Cloud provides a special metric `ClickHouse_ServiceInfo` which is a `gauge` that always has the value of `1`. This metric contains all the **Metric Labels** as well as the following labels:
8688

87-
|Label|Description|
88-
|---|---|
89-
|clickhouse_cluster_status|Status of the service. Could be one of the following: [`awaking` \| `running` \| `degraded` \| `idle` \| `stopped`]|
90-
|clickhouse_version|Version of the ClickHouse server that the service is running|
91-
|scrape|Indicates the status of the last scrape. Could be either `full` or `partial`|
92-
|full|Indicates that there were no errors during the last metrics scrape|
93-
|partial|Indicates that there were some errors during the last metrics scrape and only `ClickHouse_ServiceInfo` metric was returned.|
89+
| Label | Description |
90+
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
91+
| clickhouse_cluster_status | Status of the service. Could be one of the following: [`awaking` \| `running` \| `degraded` \| `idle` \| `stopped`] |
92+
| clickhouse_version | Version of the ClickHouse server that the service is running |
93+
| scrape | Indicates the status of the last scrape. Could be either `full` or `partial` |
94+
| full | Indicates that there were no errors during the last metrics scrape |
95+
| partial | Indicates that there were some errors during the last metrics scrape and only `ClickHouse_ServiceInfo` metric was returned. |
9496

9597
Requests to retrieve metrics will not resume an idled service. In the case that a service is in the `idle` state, only the `ClickHouse_ServiceInfo` metric will be returned.
9698

@@ -105,7 +107,7 @@ global:
105107
scrape_configs:
106108
- job_name: "prometheus"
107109
static_configs:
108-
- targets: ["localhost:9090"]
110+
- targets: ["localhost:9090"]
109111
- job_name: "clickhouse"
110112
static_configs:
111113
- targets: ["api.clickhouse.cloud"]
@@ -135,35 +137,35 @@ We provide instructions on using these options below, focusing on the details sp
135137
- Configure the Scrape URL to point to the Prometheus endpoint and use basic auth to configure your connection with the API key/secret
136138
- Test the connection to ensure you are able to connect
137139

138-
<img src={require('./images/prometheus-grafana-metrics-endpoint.png').default}
139-
class='image'
140-
alt='Configure Grafana Metrics Endpoint'
141-
style={{width: '600px'}} />
140+
<img src={require('./images/prometheus-grafana-metrics-endpoint.png').default}
141+
class='image'
142+
alt='Configure Grafana Metrics Endpoint'
143+
style={{width: '600px'}} />
142144

143145
<br />
144146

145147
Once configured, you should see the metrics in the drop-down that you can select to configure dashboards:
146148

147-
<img src={require('./images/prometheus-grafana-dropdown.png').default}
148-
class='image'
149-
alt='Grafana Metrics Explorer Drop-down'
150-
style={{width: '400px'}} />
149+
<img src={require('./images/prometheus-grafana-dropdown.png').default}
150+
class='image'
151+
alt='Grafana Metrics Explorer Drop-down'
152+
style={{width: '400px'}} />
151153

152154
<br />
153155

154-
<img src={require('./images/prometheus-grafana-chart.png').default}
155-
class='image'
156-
alt='Grafana Metrics Explorer Chart'
157-
style={{width: '800px'}} />
156+
<img src={require('./images/prometheus-grafana-chart.png').default}
157+
class='image'
158+
alt='Grafana Metrics Explorer Chart'
159+
style={{width: '800px'}} />
158160

159161
### Grafana Cloud with Alloy
160162

161163
If you are using Grafana Cloud, Alloy can be installed by navigating to the Alloy menu in Grafana and following the onscreen instructions:
162164

163-
<img src={require('./images/prometheus-grafana-alloy.png').default}
164-
class='image'
165-
alt='Grafana Alloy'
166-
style={{width: '600px'}} />
165+
<img src={require('./images/prometheus-grafana-alloy.png').default}
166+
class='image'
167+
alt='Grafana Alloy'
168+
style={{width: '600px'}} />
167169

168170
<br />
169171

@@ -173,31 +175,31 @@ The following shows an example configuration for Alloy with a `prometheus.scrape
173175

174176
```yaml
175177
prometheus.scrape "clickhouse_cloud" {
176-
// Collect metrics from the default listen address.
177-
targets = [{
178-
__address__ = "https://api.clickhouse.cloud/v1/organizations/:organizationId/services/:serviceId/Promethues",
178+
// Collect metrics from the default listen address.
179+
targets = [{
180+
__address__ = "https://api.clickhouse.cloud/v1/organizations/:organizationId/services/:serviceId/Promethues",
179181
// e.g. https://api.clickhouse.cloud/v1/organizations/97a33bdb-4db3-4067-b14f-ce40f621aae1/services/f7fefb6e-41a5-48fa-9f5f-deaaa442d5d8/prometheus
180-
}]
182+
}]
181183
182-
honor_labels = true
184+
honor_labels = true
183185
184-
basic_auth {
185-
username = "KEY_ID"
186-
password = "KEY_SECRET"
187-
}
186+
basic_auth {
187+
username = "KEY_ID"
188+
password = "KEY_SECRET"
189+
}
188190
189-
forward_to = [prometheus.remote_write.metrics_service.receiver]
190-
// forward to metrics_service below
191+
forward_to = [prometheus.remote_write.metrics_service.receiver]
192+
// forward to metrics_service below
191193
}
192194
193195
prometheus.remote_write "metrics_service" {
194-
endpoint {
195-
url = "https://prometheus-prod-10-prod-us-central-0.grafana.net/api/prom/push"
196-
basic_auth {
197-
username = "<Grafana API username>"
198-
password = "<grafana API token>"
199-
}
200-
}
196+
endpoint {
197+
url = "https://prometheus-prod-10-prod-us-central-0.grafana.net/api/prom/push"
198+
basic_auth {
199+
username = "<Grafana API username>"
200+
password = "<grafana API token>"
201+
}
202+
}
201203
}
202204
```
203205

@@ -209,30 +211,30 @@ Self-managed users of Grafana can find the instructions for installing the Alloy
209211

210212
```yaml
211213
prometheus.scrape "clickhouse_cloud" {
212-
// Collect metrics from the default listen address.
213-
targets = [{
214-
__address__ = "https://api.clickhouse.cloud/v1/organizations/:organizationId/services/:serviceId/Promethues",
214+
// Collect metrics from the default listen address.
215+
targets = [{
216+
__address__ = "https://api.clickhouse.cloud/v1/organizations/:organizationId/services/:serviceId/Promethues",
215217
// e.g. https://api.clickhouse.cloud/v1/organizations/97a33bdb-4db3-4067-b14f-ce40f621aae1/services/f7fefb6e-41a5-48fa-9f5f-deaaa442d5d8/prometheus
216-
}]
218+
}]
217219
218-
honor_labels = true
220+
honor_labels = true
219221
220-
basic_auth {
221-
username = "KEY_ID"
222-
password = "KEY_SECRET"
223-
}
222+
basic_auth {
223+
username = "KEY_ID"
224+
password = "KEY_SECRET"
225+
}
224226
225-
forward_to = [prometheus.remote_write.metrics_service.receiver]
226-
// forward to metrics_service. Modify to your preferred receiver
227+
forward_to = [prometheus.remote_write.metrics_service.receiver]
228+
// forward to metrics_service. Modify to your preferred receiver
227229
}
228230
```
229231

230232
Once configured, you should see ClickHouse related metrics in your metrics explorer:
231233

232-
<img src={require('./images/prometheus-grafana-metrics-explorer.png').default}
233-
class='image'
234-
alt='Grafana Metrics Explorer'
235-
style={{width: '800px'}} />
234+
<img src={require('./images/prometheus-grafana-metrics-explorer.png').default}
235+
class='image'
236+
alt='Grafana Metrics Explorer'
237+
style={{width: '800px'}} />
236238

237239
<br />
238240

@@ -246,17 +248,17 @@ You can use the Datadog [Agent](https://docs.datadoghq.com/agent/?tab=Linux) and
246248
init_config:
247249
248250
instances:
249-
- openmetrics_endpoint: 'https://api.clickhouse.cloud/v1/organizations/97a33bdb-4db3-4067-b14f-ce40f621aae1/services/f7fefb6e-41a5-48fa-9f5f-deaaa442d5d8/prometheus'
250-
namespace: 'clickhouse'
251-
metrics:
252-
- '^ClickHouse.*'
253-
username: username
254-
password: password
251+
- openmetrics_endpoint: "https://api.clickhouse.cloud/v1/organizations/97a33bdb-4db3-4067-b14f-ce40f621aae1/services/f7fefb6e-41a5-48fa-9f5f-deaaa442d5d8/prometheus"
252+
namespace: "clickhouse"
253+
metrics:
254+
- "^ClickHouse.*"
255+
username: username
256+
password: password
255257
```
256258

257259
<br />
258260

259-
<img src={require('./images/prometheus-datadog.png').default}
260-
class='image'
261-
alt='Prometheus Datadog Integration'
262-
style={{width: '600px'}} />
261+
<img src={require('./images/prometheus-datadog.png').default}
262+
class='image'
263+
alt='Prometheus Datadog Integration'
264+
style={{width: '600px'}} />

0 commit comments

Comments
 (0)