> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Managed Postgres Prometheus integration

> Scrape Managed Postgres metrics into Prometheus, Grafana, Datadog, or any OpenMetrics-compatible collector

export const TrackedLink = ({href, eventName, children, ...rest}) => {
  const handleClick = () => {
    try {
      if (typeof window !== "undefined" && window.galaxy && eventName) {
        window.galaxy.track(eventName, {
          interaction: "click"
        });
      }
    } catch (e) {}
  };
  return <a href={href} onClick={handleClick} {...rest}>
      {children}
    </a>;
};

export const Image = ({img, alt, size}) => {
  return <Frame>
      <img src={img} alt={alt} />
    </Frame>;
};

export const galaxyOnClick = eventName => () => {
  try {
    if (typeof window !== "undefined" && window.galaxy && eventName) {
      window.galaxy.track(eventName, {
        interaction: "click"
      });
    }
  } catch (e) {}
};

export const BetaBadge = ({link, galaxyTrack, galaxyEvent}) => {
  if (link) {
    return <a href={link} target="_blank" rel="noopener noreferrer" className="betaBadge" onClick={galaxyTrack && galaxyEvent ? galaxyOnClick(galaxyEvent) : undefined}>
                <Icon />
                <span>Beta</span>
            </a>;
  }
  return <div className="betaBadge">
            <Icon />
            <span>
                Beta feature. 
                <u>
                    <a href="/docs/beta-and-experimental-features#beta-features">
                        Learn more.
                    </a>
                </u>
            </span>
        </div>;
};

Managed Postgres exposes two Prometheus-compatible metrics endpoints
on the [ClickHouse Cloud API][cloud-api]:

| Endpoint | Path                                                   | Returns                                               |
| -------- | ------------------------------------------------------ | ----------------------------------------------------- |
| Org      | `/v1/organizations/{orgId}/postgres/prometheus`        | Metrics for every Managed Postgres service in the org |
| Instance | `/v1/organizations/{orgId}/postgres/{pgId}/prometheus` | Metrics for a single service                          |

<Note>
  The org-level endpoint returns metrics for up to 100 services. If your
  organization has more than 100 Managed Postgres services, [contact
  support](https://clickhouse.com/support/program).
</Note>

<h2 id="authentication">
  Authentication
</h2>

The endpoint uses the same [API keys] as the rest of the OpenAPI; see
the [OpenAPI guide](/products/managed-postgres/openapi) for how to create
them and look up your organization and service IDs.

```bash theme={null}
KEY_ID=mykeyid
KEY_SECRET=mykeysecret
ORG_ID=myorgid
PG_ID=mypgid
```

<h2 id="scrape-org">
  Scraping all services in an organization
</h2>

```bash theme={null}
curl -s --user "$KEY_ID:$KEY_SECRET" \
    "https://api.clickhouse.cloud/v1/organizations/$ORG_ID/postgres/prometheus"
```

<h2 id="scrape-instance">
  Scraping a single service
</h2>

```bash theme={null}
curl -s --user "$KEY_ID:$KEY_SECRET" \
    "https://api.clickhouse.cloud/v1/organizations/$ORG_ID/postgres/$PG_ID/prometheus"
```

<h2 id="sample-response">
  Sample response
</h2>

```response theme={null}
# HELP PostgresServiceInfo Information about PostgreSQL service, including status and version.
# TYPE PostgresServiceInfo gauge
PostgresServiceInfo{clickhouse_org="ca04a310-730d-4ce0-93dd-39f2cd2d5e6f",postgres_service="0c330583-6396-86d0-82cd-ed0f23b0d38c",postgres_service_name="my-postgres",postgres_status="running",postgres_version="18"} 1

# HELP PostgresServer_ActiveConnections Number of active connections by state.
# TYPE PostgresServer_ActiveConnections gauge
PostgresServer_ActiveConnections{clickhouse_org="ca04a310-730d-4ce0-93dd-39f2cd2d5e6f",postgres_service="0c330583-6396-86d0-82cd-ed0f23b0d38c",postgres_service_name="my-postgres",state="active"} 1
PostgresServer_ActiveConnections{clickhouse_org="ca04a310-730d-4ce0-93dd-39f2cd2d5e6f",postgres_service="0c330583-6396-86d0-82cd-ed0f23b0d38c",postgres_service_name="my-postgres",state="idle"} 4

# HELP PostgresServer_CacheHitRatio Buffer cache hit ratio: blocks served from cache vs. total blocks accessed (%).
# TYPE PostgresServer_CacheHitRatio gauge
PostgresServer_CacheHitRatio{clickhouse_org="ca04a310-730d-4ce0-93dd-39f2cd2d5e6f",postgres_service="0c330583-6396-86d0-82cd-ed0f23b0d38c",postgres_service_name="my-postgres"} 100
```

For the full list of metrics and their meanings, see the
[metrics reference](/products/managed-postgres/monitoring/metrics).

<h2 id="configuring-prometheus">
  Configuring Prometheus
</h2>

This config scrapes the org-level endpoint every 60 seconds:

```yaml theme={null}
scrape_configs:
  - job_name: "managed-postgres"
    scheme: https
    metrics_path: "/v1/organizations/<ORG_ID>/postgres/prometheus"
    static_configs:
      - targets: ["api.clickhouse.cloud"]
    basic_auth:
      username: <KEY_ID>
      password: <KEY_SECRET>
    honor_labels: true
    scrape_interval: 60s
```

The endpoint refreshes metrics once per minute. Scraping faster than
`60s` duplicates samples and produces a stair-step pattern on gauge
panels.

Set `honor_labels: true` so the `postgres_service` and
`postgres_service_name` labels from the endpoint are preserved instead
of being overwritten by Prometheus.

To scrape a single service, append `/<PG_ID>` to the `metrics_path`.

<h2 id="grafana-dashboard">
  Pre-built Grafana dashboard
</h2>

A ready-made Grafana dashboard visualizes every metric the endpoint
exposes — a sortable services table, CPU and memory utilization, disk
usage with threshold alerts, connections by state, transactions and
rollback ratio, tuple activity, I/O, per-database storage, and
deadlocks.

<Image img="https://mintcdn.com/private-7c7dfe99-fix-nav-issues/qT0j4CNmQubVqREl/images/managed-postgres/monitoring/grafana-dashboard.png?fit=max&auto=format&n=qT0j4CNmQubVqREl&q=85&s=a497fb8c4a42a8f02c1bb875dbabfe1a" alt="Grafana dashboard of Managed Postgres Services" size="md" border width="1863" height="1306" data-path="images/managed-postgres/monitoring/grafana-dashboard.png" />

<h3 id="import-dashboard">
  Importing the dashboard
</h3>

<Steps>
  <Step>
    <h4 id="download">
      Download the dashboard JSON
    </h4>

    <TrackedLink href={'/examples/managed-postgres-grafana-dashboard.json'} download="managed-postgres-grafana-dashboard.json" eventName="docs.managed_postgres_grafana_dashboard.download">Download the dashboard JSON</TrackedLink>.
  </Step>

  <Step>
    <h4 id="open-import">
      Open the import flow in Grafana
    </h4>

    Go to **Dashboards → New → Import**. Upload the JSON file or paste its contents.
  </Step>

  <Step>
    <h4 id="pick-datasource">
      Pick your Prometheus datasource
    </h4>

    When prompted for the `DS_PROMETHEUS` input, select the Prometheus datasource scraping the endpoint configured in the [previous section](#configuring-prometheus).
  </Step>
</Steps>

For provisioned Grafana deployments, drop the JSON into your
dashboards provisioning path. Grafana matches the `${DS_PROMETHEUS}`
reference to a Prometheus datasource available in the instance.

<h3 id="template-variables">
  Template variables
</h3>

The dashboard exposes three variables:

* **Data source** — the Prometheus datasource backing the dashboard.
* **Service** — multi-select filter over `postgres_service_name`.
  Defaults to *All*; pick one or more services to scope every panel.
* **Scrape interval** — hidden constant, defaults to `60s`. Drives
  Grafana's `$__rate_interval` calculation. Change this value in the
  JSON if your scrape interval differs.

<h3 id="drill-in">
  Filter to a single service for drill-in
</h3>

Several panels are designed for drill-in once you filter to a single
service via the **Service** variable. The CPU by mode panel, for
example, stacks `user`, `system`, `iowait`, `steal`, and other CPU
modes so you can tell whether a spike is application code, kernel
work, disk waits, or hypervisor contention.

<h2 id="third-party-integrations">
  Integrating with Grafana and Datadog
</h2>

The endpoint follows the same shape as the [ClickHouse Prometheus
endpoint](/products/cloud/features/monitoring/prometheus), so the Grafana Cloud, Grafana
Alloy, and Datadog OpenMetrics agent configurations described there
apply here too. Point `metrics_path` at the Managed Postgres org or
instance path instead of the ClickHouse one.

[cloud-api]: /products/cloud/features/admin-features/api/index "Cloud API"

[API keys]: /products/cloud/features/admin-features/api/openapi "Managing API Keys"