API 참조

대시보드, 알림, 소스를 프로그래밍 방식으로 관리하는 ClickStack API 참조

ClickStack는 대시보드, 알림, 데이터 소스를 프로그래밍 방식으로 관리할 수 있도록 REST API를 제공합니다. 이 API는 Managed ClickStack(ClickHouse Cloud)과 ClickStack Open Source 배포 모두에서 사용할 수 있지만, 두 환경에서는 엔드포인트와 인증 방식이 서로 다릅니다.

​

API 참조 문서

Managed ClickStack

Managed ClickStack에서는 ClickHouse Cloud API를 통해 API를 사용합니다. ClickStack 엔드포인트는 Cloud API 사양에서 확인할 수 있습니다.

다음 엔드포인트를 사용할 수 있습니다:

리소스	작업
Dashboards	대시보드 생성, 목록 조회, 조회, 업데이트, 삭제
Alerts	알림 생성, 목록 조회, 조회, 업데이트, 삭제
Sources	데이터 소스 목록 조회

Open Source ClickStack

Open Source ClickStack의 전체 API 사양은 HyperDX 리포지토리에서 관리되며, 대화형으로 확인하거나 OpenAPI 사양으로 다운로드할 수 있습니다:

• 대화형 API 참조
• OpenAPI 사양 다운로드(JSON)

다음 엔드포인트를 사용할 수 있습니다:

리소스	작업
Dashboards	대시보드 생성, 목록 조회, 조회, 업데이트, 삭제
Alerts	알림 생성, 목록 조회, 조회, 업데이트, 삭제
Charts	시계열 데이터 쿼리(POST만 지원)
Sources	데이터 소스 목록 조회
Webhooks	웹훅 목록 조회

​

인증

Managed ClickStack

Managed ClickStack에서는 HTTP 기본 인증을 통해 ClickHouse Cloud API key를 사용해 인증합니다. API key를 생성하고 관리하는 방법은 API key 관리를 참조하십시오.

HTTP 기본 인증을 사용해 key ID와 secret을 포함하십시오:

export KEY_ID=<your_key_id>
export KEY_SECRET=<your_key_secret>

curl --user $KEY_ID:$KEY_SECRET \
  https://api.clickhouse.cloud/v1/organizations/<ORG_ID>/services/<SERVICE_ID>/clickstack/dashboards

Open Source ClickStack

ClickStack Open Source는 Personal API Access Key를 사용하는 Bearer token 방식으로 인증합니다.

API key를 발급받으려면 다음 단계를 수행하십시오.

1. ClickStack URL(예: http://localhost:8080)에서 HyperDX를 엽니다
2. 필요한 경우 계정을 만들거나 로그인합니다
3. Team Settings → API Keys로 이동합니다
4. Personal API Access Key를 복사합니다

이 키는 Team Settings에서 확인할 수 있는 수집 API key와 다릅니다. 수집 API key는 OpenTelemetry collector로 전송되는 텔레메트리 데이터의 인증에 사용됩니다.

API server는 기본적으로 8000 포트에서 실행됩니다(8080 포트에서 실행되는 UI와는 별도). all-in-one Docker image를 사용하는 경우 이 포트를 명시적으로 매핑하십시오.

docker run -p 8080:8080 -p 8000:8000 -p 4317:4317 -p 4318:4318 docker.hyperdx.io/hyperdx/hyperdx-all-in-one

키를 Authorization 헤더에 포함하십시오:

curl -H "Authorization: Bearer <YOUR_API_KEY>" \
  http://localhost:8000/api/v2/dashboards

​

기준 URL 및 요청 형식

Managed ClickStack

모든 Managed ClickStack API 요청은 ClickHouse Cloud API로 전송됩니다.

https://api.clickhouse.cloud/v1/organizations/<ORG_ID>/services/<SERVICE_ID>/clickstack/<resource>

조직 ID는 ClickHouse Cloud 콘솔의 Organization → Organization details에서 확인할 수 있습니다. 서비스 ID는 서비스 URL 또는 서비스 세부 정보 페이지에 표시됩니다.

​

예시: 대시보드 목록 조회

curl --user $KEY_ID:$KEY_SECRET \
  https://api.clickhouse.cloud/v1/organizations/<ORG_ID>/services/<SERVICE_ID>/clickstack/dashboards

​

예시: 알림 생성

curl -X POST --user $KEY_ID:$KEY_SECRET \
  -H "Content-Type: application/json" \
  -d '{
    "dashboardId": "<DASHBOARD_ID>",
    "tileId": "<TILE_ID>",
    "threshold": 100,
    "interval": "1h",
    "source": "tile",
    "thresholdType": "above",
    "channel": {
      "type": "webhook",
      "webhookId": "<WEBHOOK_ID>"
    },
    "name": "Error Spike Alert",
    "message": "Error rate exceeded 100 in the last hour"
  }' \
  https://api.clickhouse.cloud/v1/organizations/<ORG_ID>/services/<SERVICE_ID>/clickstack/alerts

Open Source ClickStack

모든 Open Source ClickStack API 요청은 포트 8000에서 실행되는 HyperDX API 서버로 전송됩니다.

http://<YOUR_HYPERDX_HOST>:8000/api/v2/<resource>

예를 들어, 기본 로컬 배포에서는 다음과 같습니다.

http://localhost:8000/api/v2/dashboards

​

예시: 대시보드 목록 조회

curl -H "Authorization: Bearer <YOUR_API_KEY>" \
  http://localhost:8000/api/v2/dashboards

​

예시: 알림 생성

curl -X POST \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "dashboardId": "<DASHBOARD_ID>",
    "tileId": "<TILE_ID>",
    "threshold": 100,
    "interval": "1h",
    "source": "tile",
    "thresholdType": "above",
    "channel": {
      "type": "webhook",
      "webhookId": "<WEBHOOK_ID>"
    },
    "name": "Error Spike Alert",
    "message": "Error rate exceeded 100 in the last hour"
  }' \
  http://localhost:8000/api/v2/alerts

​

예시: 차트 시리즈 데이터 쿼리

curl -X POST \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "startTime": 1647014400000,
    "endTime": 1647100800000,
    "granularity": "1h",
    "series": [
      {
        "sourceId": "<SOURCE_ID>",
        "aggFn": "count",
        "where": "SeverityText:error",
        "groupBy": []
      }
    ]
  }' \
  http://localhost:8000/api/v2/charts/series