API リファレンス

ClickStack では、ダッシュボード、アラート、データソースをプログラムで管理するための REST API を提供しています。この API は Managed ClickStack (ClickHouse Cloud) と ClickStack Open Source の両方のデプロイで利用できますが、エンドポイントと認証方式は両者で異なります。

Managed ClickStack
Open Source ClickStack

Managed ClickStack では、API には ClickHouse Cloud API 経由でアクセスします。ClickStack のエンドポイントは、Cloud API 仕様で利用できます。利用可能なエンドポイントは次のとおりです。

リソース	操作
ダッシュボード	ダッシュボードの作成、一覧表示、取得、更新、削除
アラート	アラートの作成、一覧表示、取得、更新、削除
SOURCES	データソースの一覧表示

Open Source ClickStack では、完全な API 仕様は HyperDX リポジトリで管理されており、対話的に参照することも、OpenAPI 仕様としてダウンロードすることもできます。

利用可能なエンドポイントは次のとおりです。

リソース	操作
ダッシュボード	ダッシュボードの作成、一覧表示、取得、更新、削除
アラート	アラートの作成、一覧表示、取得、更新、削除
チャート	時系列データをクエリ (POST のみ)
SOURCES	データソースの一覧表示
Webhooks	Webhooks の一覧表示

認証

Managed ClickStack
Open Source ClickStack

Managed ClickStack では、HTTP Basic Authentication による認証に ClickHouse Cloud API key を使用します。API key の作成と管理については、API key の管理を参照してください。HTTP Basic Authentication を使用して、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

ClickStack Open Source では、Personal API Access Key を使用した Bearer token による認証を使用します。API key を取得するには、次の手順を実行します。

ClickStack の URL で HyperDX を開きます (例: http://localhost:8080)
必要に応じてアカウントを作成するか、ログインします
Team Settings → API Keys に移動します
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 header に key を含めます。

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

ベースURLとリクエスト形式

Managed ClickStack
Open Source ClickStack

Managed ClickStack API へのリクエストはすべて、ClickHouse Cloud API に送信されます。

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

Organization ID は、ClickHouse Cloudコンソールの Organization → Organization details で確認できます。Service 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 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