본문으로 바로가기
본문으로 바로가기

Prometheus 연동

Private preview

Managed Postgres는 ClickHouse Cloud API를 통해 Prometheus와 호환되는 2개의 메트릭 엔드포인트를 노출합니다

엔드포인트경로반환값
조직/v1/organizations/{orgId}/postgres/prometheus조직 내 모든 Managed Postgres 서비스의 메트릭
인스턴스/v1/organizations/{orgId}/postgres/{pgId}/prometheus단일 서비스의 메트릭
참고

조직 수준 엔드포인트는 최대 100개 서비스의 메트릭을 반환합니다. 조직에 Managed Postgres 서비스가 100개를 초과하는 경우 지원팀에 문의하십시오.

인증​

이 엔드포인트에서는 다른 OpenAPI와 동일한 [API 키]를 사용합니다. 이를 생성하고 조직 및 서비스 ID를 확인하는 방법은 OpenAPI 가이드를 참조하십시오.

KEY_ID=mykeyid
KEY_SECRET=mykeysecret
ORG_ID=myorgid
PG_ID=mypgid

조직 내 모든 서비스 스크레이핑​

curl -s --user "$KEY_ID:$KEY_SECRET" \
    "https://api.clickhouse.cloud/v1/organizations/$ORG_ID/postgres/prometheus"

단일 서비스 스크레이핑​

curl -s --user "$KEY_ID:$KEY_SECRET" \
    "https://api.clickhouse.cloud/v1/organizations/$ORG_ID/postgres/$PG_ID/prometheus"

예시 응답​

# 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

전체 메트릭 목록과 각 메트릭의 의미는 메트릭 참고 문서를 참조하십시오.

Prometheus 설정​

이 구성은 60초마다 조직 수준 엔드포인트를 스크레이프하도록 설정되어 있습니다:

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

엔드포인트는 메트릭을 1분에 한 번 갱신합니다. 60s보다 더 빠르게 스크레이프하면 샘플이 중복되고 gauge 패널에 계단형 패턴이 나타납니다.

honor_labels: true를 설정하여 엔드포인트의 postgres_service 및 postgres_service_name 레이블이 Prometheus에 의해 덮어써지지 않고 유지되도록 하십시오.

단일 서비스를 스크레이프하려면 metrics_path에 /<PG_ID>를 추가하십시오.

사전 구축된 Grafana 대시보드​

바로 사용할 수 있는 Grafana 대시보드는 엔드포인트에서 노출하는 모든 메트릭을 시각화합니다. 정렬 가능한 서비스 테이블, CPU 및 메모리 사용률, 임계값 알림이 포함된 디스크 사용량, 상태별 연결, 트랜잭션 및 롤백 비율, Tuple 활동, I/O, 데이터베이스별 스토리지, 그리고 교착 상태를 확인할 수 있습니다.

Managed Postgres Services용 Grafana 대시보드

대시보드 가져오기​

대시보드 JSON 다운로드​

대시보드 JSON 다운로드.

Grafana에서 가져오기 화면 열기​

Dashboards → New → Import로 이동하세요. JSON 파일을 업로드하거나 내용을 붙여넣으십시오.

Prometheus 데이터 소스 선택​

DS_PROMETHEUS 입력값을 요청받으면, 이전 섹션에서 구성한 엔드포인트를 스크레이프하는 Prometheus 데이터 소스를 선택하십시오.

Grafana를 프로비저닝 방식으로 배포한 경우, JSON 파일을 대시보드 프로비저닝 경로에 넣으십시오. Grafana는 ${DS_PROMETHEUS} 참조를 해당 인스턴스에서 사용할 수 있는 Prometheus 데이터 소스에 자동으로 매칭합니다.

템플릿 변수​

이 대시보드에는 세 가지 변수가 있습니다:

  • 데이터 소스 — 대시보드의 기반이 되는 Prometheus 데이터 소스입니다.
  • 서비스 — postgres_service_name에 대한 다중 선택 필터입니다. 기본값은 All이며, 하나 이상의 서비스를 선택하면 모든 패널이 해당 서비스 범위로 제한됩니다.
  • 스크레이프 인터벌 — 숨겨진 상수이며 기본값은 60s입니다. 이 값은 Grafana의 $__rate_interval 계산에 사용됩니다. 스크레이프 인터벌이 다르면 JSON에서 이 값을 변경하십시오.

드릴인을 위해 단일 서비스로 필터링​

여러 패널은 Service 변수를 사용해 단일 서비스로 필터링한 후 드릴인할 수 있도록 설계되어 있습니다. 예를 들어 CPU by mode 패널은 user, system, iowait, steal 및 기타 CPU 모드를 누적해서 표시하므로, 급증의 원인이 애플리케이션 코드, 커널 작업, 디스크 대기 또는 하이퍼바이저 경합인지 파악할 수 있습니다.

Grafana 및 Datadog와 통합하기​

이 엔드포인트는 ClickHouse Prometheus 엔드포인트와 동일한 형식을 따르므로, 해당 문서에 설명된 Grafana Cloud, Grafana Alloy 및 Datadog OpenMetrics agent 구성도 여기에서 그대로 적용할 수 있습니다. metrics_path는 ClickHouse 경로 대신 Managed Postgres 조직 또는 인스턴스 경로를 가리키도록 설정하십시오.