BYOC Observability

### Authentication[​](#authentication "Direct link to Authentication")

The metrics endpoint requires authentication using ClickHouse credentials. We recommend use `default` user or creating a dedicated user with minimal permissions specifically for metric scraping.

**Required Permissions:**

- `REMOTE` permission to connect to the service
- `SELECT` permissions on relevant system tables

**Example User Setup:**

```
CREATE USER scrapping_user IDENTIFIED BY 'secure_password';
GRANT REMOTE ON *.* TO scrapping_user;
GRANT SELECT ON system._custom_metrics_dictionary_custom_metrics_tables TO scrapping_user;
GRANT SELECT ON system._custom_metrics_dictionary_database_replicated_recovery_time TO scrapping_user;
GRANT SELECT ON system._custom_metrics_dictionary_failed_mutations TO scrapping_user;
GRANT SELECT ON system._custom_metrics_dictionary_group TO scrapping_user;
GRANT SELECT ON system._custom_metrics_dictionary_shared_catalog_recovery_time TO scrapping_user;
GRANT SELECT ON system._custom_metrics_dictionary_table_read_only_duration_seconds TO scrapping_user;
GRANT SELECT ON system._custom_metrics_view_error_metrics TO scrapping_user;
GRANT SELECT ON system._custom_metrics_view_histograms TO scrapping_user;
GRANT SELECT ON system._custom_metrics_view_metrics_and_events TO scrapping_user;
GRANT SELECT(description, metric, value) ON system.asynchronous_metrics TO scrapping_user;
GRANT SELECT ON system.custom_metrics TO scrapping_user;
GRANT SELECT(name, value) ON system.errors TO scrapping_user;
GRANT SELECT(description, event, value) ON system.events TO scrapping_user;
GRANT SELECT(description, labels, metric, value) ON system.histogram_metrics TO scrapping_user;
GRANT SELECT(description, metric, value) ON system.metrics TO scrapping_user;
```

### Configuring Prometheus[​](#configuring-prometheus "Direct link to Configuring Prometheus")

Configure your Prometheus instance to scrape the ClickHouse metrics endpoint:

```
global:
  scrape_interval: 15s

scrape_configs:
  - job_name: "clickhouse"
    static_configs:
      - targets: ["<service-subdomain>.<byoc-subdomain>.<region>.<provider>.byoc.clickhouse-byoc.com:8443"]
    scheme: https
    metrics_path: "/metrics_all"
    basic_auth:
      username: <username>
      password: <password>
    honor_labels: true
```

Replace:

- `<service-subdomain>.<byoc-subdomain>.<region>.<provider>.byoc.clickhouse-byoc.com:8443` with your actual service endpoint
- `<username>` and `<password>` with your scraping user credentials

## ClickHouse Mixin[​](#clickhouse-mixin "Direct link to ClickHouse Mixin")

For teams that want a ready-made set of dashboards, ClickHouse provides a Prometheus **ClickHouse Mixin**. This is a pre-built Grafana dashboard designed specifically for monitoring ClickHouse clusters.

### Setting up Grafana & Importing the ClickHouse Mix-in[​](#setup-grafana-mixin "Direct link to Setting up Grafana & Importing the ClickHouse Mix-in")

Once your Prometheus instance is integrated with your ClickHouse monitoring stack, you can visualize metrics in Grafana by following these steps:

1. **Add Prometheus as a Data Source in Grafana**  
   Go to "Data sources" in the Grafana sidebar, click "Add data source," and select "Prometheus." Enter your Prometheus instance URL and any required credentials to connect.

2. **Import the ClickHouse Dashboard**  
   In Grafana, navigate to the dashboard area and choose "Import." You can either upload the dashboard JSON file or paste its contents directly. Obtain the JSON file from the ClickHouse mixin repository:  
   [ClickHouse Mix-in Dashboard JSON](https://github.com/ClickHouse/clickhouse-mixin/blob/main/dashboard_byoc.json)

3. **Explore Your Metrics**  
   Once the dashboard is imported and configured with your Prometheus data source, you should see real-time metrics from your ClickHouse Cloud services.

- [Prometheus Monitoring Approaches](#prometheus-monitoring)
  - [Comparing Monitoring Methods](#monitoring-approaches-comparison)- [The Built-in BYOC Prometheus Stack](#builtin-prometheus-stack)
    - [Accessing the Prometheus Stack](#accessing-prometheus-stack)- [Integrating with Your Monitoring Tools](#prometheus-stack-integration)- [ClickHouse service Prometheus Integration](#direct-prometheus-integration)
      - [Accessing the Metrics Endpoint](#metrics-endpoint)- [Authentication](#authentication)- [Configuring Prometheus](#configuring-prometheus)- [ClickHouse Mixin](#clickhouse-mixin)
        - [Setting up Grafana & Importing the ClickHouse Mix-in](#setup-grafana-mixin)

Was this page helpful?