Metrics API
セルフホスト型のPrometheusまたはGrafanaスタックに、生のVeloDB Cloudメトリクスをスクレイプします。
Metrics APIは現在Private Previewで利用可能です。組織で有効にするには、VeloDBサポートチームにお問い合わせください。
Metrics APIを使用して、Metricsカタログの背後にある生メトリクスを独自の可観測性スタックにプルします。warehouse レベルとclusterレベルの両方のレスポンスには、これらのカテゴリの生メトリクスが含まれます。違いは返されるデータのスコープです。
Endpoints
Metrics APIは2つのエンドポイントを公開します：
| API | Path | Description |
|---|---|---|
| QueryWarehouseMetrics | GET /v1/warehouse/{warehouseId}/metrics | warehouseの生メトリクス。 |
| QueryClusterMetrics | GET /v1/warehouse/{warehouseId}/cluster/{clusterId}/metrics | 指定されたclusterの生メトリクス。 |
両方のエンドポイントはPrometheus exposition形式のテキストを返します：
Content-Type: text/plain; version=0.0.4; charset=utf-8
Prometheusはstatic_configsまたはfile_sd_configsを使用してエンドポイントを直接スクレイプできます。
リージョンエンドポイント
各リージョンとクラウドプロバイダーには独自のエンドポイントがあります：
https://apps-api.<region>.<provider>.velodb.cloud
Management APIから返される安定したcloudProviderとregion識別子を使用してください。マーケティング名やローカライズされたラベルは使用しないでください。
利用可能なクラウドプロバイダーとリージョンを発見するには：
- クラウドプロバイダーをリスト表示:
GET /v1/cloud-providers - クラウドプロバイダーのリージョンをリスト表示:
GET /v1/cloud-providers/{cloudProvider}/regions
# List cloud providers.
curl -H "X-API-Key: sk-xxxx" \
https://api.velodb.cloud/v1/cloud-providers
# List regions for a cloud provider.
curl -H "X-API-Key: sk-xxxx" \
https://api.velodb.cloud/v1/cloud-providers/aws/regions
クイックリファレンス:
| Provider | Region | Endpoint |
|---|---|---|
aws | us-east-1 | https://apps-api.us-east-1.aws.velodb.cloud |
aws | ap-northeast-1 | https://apps-api.ap-northeast-1.aws.velodb.cloud |
aws | ap-southeast-1 | https://apps-api.ap-southeast-1.aws.velodb.cloud |
gcp | us-central1 | https://apps-api.us-central1.gcp.velodb.cloud |
warehouseは、その独自のリージョンとクラウドプロバイダーのエンドポイントを通してのみアクセス可能です。クロスリージョンまたはクロスプロバイダーのリクエストは
404 Not Foundを返すか、認証に失敗します。
プライベートエンドポイントアクセス
Metrics APIは、パブリックネットワークの代わりにプライベートエンドポイント経由でスクレイプできます。VeloDB Cloudは、Metrics APIとウェアハウス固有のConsoleエンドポイントに同じクラウドプロバイダー固有のリージョンEndpoint Serviceを使用します。ウェアハウスのリージョンにある既存のエンドポイントを再利用するか、Endpoint Servicesにあるクラウドプロバイダー別のリファレンスに従って作成してください。
クラウドプロバイダーの手順では、完全なapps-api.<region>.<provider>.velodb.cloudホスト名にPrivate DNSを設定します。その手順に従って、正しいレコードタイプとエンドポイント接続先を選択し、DNS、TLS、およびHTTPの確認を完了してください。
Prometheusやその他のクライアントでは、引き続きhttps://apps-api.<region>.<provider>.velodb.cloudを使用してください。元のホスト名はTLS検証とリクエストルーティングに必要なため、Private EndpointのIPアドレスやクラウドプロバイダーが生成したホスト名を使用しないでください。認証の説明に従って認証済みリクエストを送信し、Metrics APIへのアクセスを確認します。
認証
すべてのMetrics APIリクエストは、HTTPヘッダーにAPI keyを含める必要があります:
X-API-Key: sk-xxxxxxxxxxxxxxxxxxxx
APIキーは組織に紐づけられ、キー作成時に選択されたロールを継承します。キーは自身の組織内のwarehouseにのみアクセスできます。
APIキーを作成するには、API Keysを参照してください。完全なキーは作成時に一度だけ表示されます。すぐにコピーして保存してください。
認証に失敗すると401 Unauthorizedが返されます：
{
"code": "Unauthorized.InvalidApiKey",
"message": "invalid API key"
}
レート制限
各APIキーは、エンドポイントごとに1分間あたり100回の読み取りリクエストが許可されています。制限を超えると429 Too Many Requestsが返されます。
Prometheusスクレイピングの場合、スクレイプ間隔は最低15秒、エンドポイントあたりのターゲット数は約30個以下にすることを推奨します。
Query warehouse metrics
QueryWarehouseMetricsは、warehouse内のFEノードの生のPrometheusメトリクスを返します。
リクエスト
GET /v1/warehouse/{warehouseId}/metrics
Host: apps-api.<region>.<provider>.velodb.cloud
X-API-Key: sk-xxxx
パスパラメータ
| パラメータ | 説明 |
|---|---|
warehouseId | Warehouse ID、例：XXZ0RP |
レスポンス
| フィールド | 説明 |
|---|---|
| Status | 200 OK |
| Content type | text/plain; version=0.0.4; charset=utf-8 |
| Body | Prometheus exposition format のテキスト。返されるデータは、warehouse スコープでの Resource Metrics と Service Metrics を含みます。 |
例：
curl -H "X-API-Key: sk-xxxx" \
https://apps-api.ap-northeast-1.aws.velodb.cloud/v1/warehouse/XXZ0RP/metrics
# TYPE doris_fe_connection_total untyped
doris_fe_connection_total{cid="m-mqx8vdlm6b671apzob",custom_scheme="http",instance="10.29.12.139:8080",job="AWVA10OB",product="SAAS",provider="aws",region="us-east-1",user="admin",vpc_id="vpc-03313d4774a52fb93",wid="AWVA10OB"} 10 1780738809054
doris_fe_query_latency_ms_sum{cid="m-mqx8vdlm6b671apzob",custom_scheme="http",instance="10.29.12.139:8080",job="AWVA10OB",product="SAAS",provider="aws",region="us-east-1",vpc_id="vpc-03313d4774a52fb93",wid="AWVA10OB"} 35.55555555555556 1780733289054
# TYPE doris_fe_query_total untyped
doris_fe_query_total{cid="m-mqx8vdlm6b671apzob",cluster_id="c-v7hi1dbm6b6rimgod7",cluster_name="initial_cluster",custom_scheme="http",instance="10.29.12.139:8080",job="AWVA10OB",product="SAAS",provider="aws",region="us-east-1",vpc_id="vpc-03313d4774a52fb93",wid="AWVA10OB"} 21 1780733289054
# TYPE node_disk_io_time_seconds_total untyped
node_disk_io_time_seconds_total{cid="m-mqx8vdlm6b671apzob",device="nvme1n1",instance="10.29.12.139:9100",job="AWVA10OB",product="SAAS",provider="aws",region="us-east-1",vpc_id="vpc-03313d4774a52fb93",wid="AWVA10OB"} 220.19 1780733285342
# TYPE node_memory_Buffers_bytes untyped
node_memory_Buffers_bytes{cid="m-mqx8vdlm6b671apzob",instance="10.29.12.139:9100",job="AWVA10OB",product="SAAS",provider="aws",region="us-east-1",vpc_id="vpc-03313d4774a52fb93",wid="AWVA10OB"} 2.0322304e+08 1780733285342
# TYPE node_memory_Cached_bytes untyped
node_memory_Cached_bytes{cid="m-mqx8vdlm6b671apzob",instance="10.29.12.139:9100",job="AWVA10OB",product="SAAS",provider="aws",region="us-east-1",vpc_id="vpc-03313d4774a52fb93",wid="AWVA10OB"} 2.207244288e+09 1780733285342
クラスターメトリクスの照会
QueryClusterMetricsは、指定されたクラスターの生のPrometheusメトリクスを返します。
リクエスト
GET /v1/warehouse/{warehouseId}/cluster/{clusterId}/metrics
Host: apps-api.<region>.<provider>.velodb.cloud
X-API-Key: sk-xxxx
パスパラメータ
| パラメータ | 説明 |
|---|---|
warehouseId | Warehouse ID。 |
clusterId | Cluster ID。o-プレフィックスはobserverクラスタを意味します。c-プレフィックスはcomputeクラスタを意味します。 |
レスポンス
| フィールド | 説明 |
|---|---|
| Status | 200 OK |
| Content type | text/plain; version=0.0.4; charset=utf-8 |
| Body | Prometheus exposition形式のテキスト。返されるデータは、クラスタスコープでのResource MetricsとService Metricsをカバーします。 |
例：
curl -H "X-API-Key: sk-xxxx" \
https://apps-api.us-east-1.aws.velodb.cloud/v1/warehouse/XXZ0RP/cluster/m-fexxxxxxx/metrics
# TYPE doris_be_load_bytes untyped
doris_be_load_bytes{cid="c-v7hi1dbm6b6rimgod7",custom_scheme="http",instance="10.29.2.192:8040",job="AWVA10OB-c-v7hi1dbm6b6rimgod7",product="SAAS",provider="aws",region="us-east-1",vpc_id="vpc-03313d4774a52fb93",wid="AWVA10OB"} 3.042252e+06 1780735183262
# TYPE doris_be_num_io_bytes_read_from_cache untyped
doris_be_num_io_bytes_read_from_cache{cid="c-v7hi1dbm6b6rimgod7",custom_scheme="http",instance="10.29.2.192:8040",job="AWVA10OB-c-v7hi1dbm6b6rimgod7",product="SAAS",provider="aws",region="us-east-1",vpc_id="vpc-03313d4774a52fb93",wid="AWVA10OB"} 4.649776e+07 1780735183262
# TYPE doris_be_num_io_bytes_read_total untyped
doris_be_num_io_bytes_read_total{cid="c-v7hi1dbm6b6rimgod7",custom_scheme="http",instance="10.29.2.192:8040",job="AWVA10OB-c-v7hi1dbm6b6rimgod7",product="SAAS",provider="aws",region="us-east-1",vpc_id="vpc-03313d4774a52fb93",wid="AWVA10OB"} 4.649776e+07 1780735183262
# TYPE doris_be_streaming_load_requests_total untyped
doris_be_streaming_load_requests_total{cid="c-v7hi1dbm6b6rimgod7",custom_scheme="http",instance="10.29.2.192:8040",job="AWVA10OB-c-v7hi1dbm6b6rimgod7",product="SAAS",provider="aws",region="us-east-1",vpc_id="vpc-03313d4774a52fb93",wid="AWVA10OB"} 1357 1780735183262
# TYPE doris_be_tablet_base_max_compaction_score untyped
doris_be_tablet_base_max_compaction_score{cid="c-v7hi1dbm6b6rimgod7",custom_scheme="http",instance="10.29.2.192:8040",job="AWVA10OB-c-v7hi1dbm6b6rimgod7",product="SAAS",provider="aws",region="us-east-1",vpc_id="vpc-03313d4774a52fb93",wid="AWVA10OB"} 1 1780735183262
# TYPE doris_be_tablet_cumulative_max_compaction_score untyped
doris_be_tablet_cumulative_max_compaction_score{cid="c-v7hi1dbm6b6rimgod7",custom_scheme="http",instance="10.29.2.192:8040",job="AWVA10OB-c-v7hi1dbm6b6rimgod7",product="SAAS",provider="aws",region="us-east-1",vpc_id="vpc-03313d4774a52fb93",wid="AWVA10OB"} 4 1780735183262
Prometheusとの統合
Metrics APIは直接Prometheus exposition formatを返すため、Prometheusは各エンドポイントをscrapeターゲットとして扱うことができます。
重要なポイント：
- schemeとして
httpsを使用してください。 - 各パスにはwarehouse IDまたはcluster IDが含まれているため、ターゲットごとに
__metrics_path__ラベルを設定してください。 X-API-KeyHTTPヘッダーを通じてAPI keyを渡してください。- 複数のwarehouseとclusterを管理するために
file_sd_configsを使用してください。異なるリージョンのwarehouseは、それぞれのendpoint hostを指すべきです。
Prometheus 2.43+では
http_headersを通じてカスタムヘッダーをサポートしています。
推奨されるディレクトリレイアウト：
prometheus/
prometheus.yml
targets/
warehouse.yml
例 prometheus.yml:
scrape_configs:
- job_name: velodb-warehouse
scheme: https
http_headers:
X-API-Key:
values:
- sk-xxxxxxxxxxxxxxxxxxxx
file_sd_configs:
- files:
- targets/warehouse.yml
refresh_interval: 1m
例 targets/warehouse.yml:
- targets:
- apps-api.us-east-1.aws.velodb.cloud
labels:
__metrics_path__: /v1/warehouse/XXZ0RP/metrics
warehouse: XXZ0RP
name: warehouse-a
- targets:
- apps-api.ap-northeast-1.aws.velodb.cloud
labels:
__metrics_path__: /v1/warehouse/XXZ0RQ/metrics
warehouse: XXZ0RQ
name: warehouse-b
- targets:
- apps-api.us-central1.gcp.velodb.cloud
labels:
__metrics_path__: /v1/warehouse/GCP0RS/cluster/CLUSTER001/metrics
warehouse: GCP0RS
cluster: CLUSTER001
name: cluster-name1
お使いのPrometheusバージョンがhttp_headersをサポートしていない場合は、Prometheusのauthorization設定を使用するか、スクレイパーの前にNginxやEnvoyなどのリバースプロキシを配置してX-API-Keyを注入してください。
Grafanaでの可視化
PrometheusがMetrics APIをスクレイピングすると、コンソールに表示されるResource MetricsやService Metricsと同じ内容を反映する事前構築済みのGrafanaダッシュボードをインポートできます。
monitoring-stacksリポジトリに、すぐに使用できる2つのダッシュボードテンプレートが公開されています：
| ダッシュボード | ファイル | スコープ |
|---|---|---|
| VeloDB Warehouse Monitoring | grafana_dashboard_warehouse.json | FEノードリソース、QPS、クエリレイテンシ、接続、ロードジョブ、routine load、workload group。 |
| VeloDB Cluster Monitoring | grafana_dashboard_cluster.json | BEノードリソース、デッドノード、クエリパフォーマンス、キャッシュヒット率、リモートS3スループット、ロードスループット、tabletコンパクションスコア。 |
ダッシュボードのインポート
- GrafanaでDashboardsを開き、New、次にImportを選択します。
- JSONファイルをアップロードするか、GitHubから生のコンテンツを貼り付けます。
- プロンプトが表示されたら、Metrics APIをスクレイピングするPrometheusデータソースを選択します。これにより
DS_PROMETHEUSテンプレート変数がバインドされます。 - Importをクリックします。
テンプレート変数
両方のダッシュボードはMetric labelsで説明された固定ラベルを読み取ります。インポート後、ダッシュボード上部のドロップダウンを使用してビューのスコープを設定します：
| 変数 | ダッシュボード | ソース | 目的 |
|---|---|---|---|
DS_PROMETHEUS | 両方 | インポート時に選択 | Prometheusデータソース。 |
wid | 両方 | label_values(doris_fe_connection_total, wid) | ウェアハウスセレクター。 |
cid | Cluster | label_values(up{wid="$wid", cid!=""}, cid) | 選択されたウェアハウスにスコープされたクラスターセレクター。 |
interval | 両方 | 静的リスト（30s、1m、5m、10m、30m、1h） | 時系列パネルのレートと集計ウィンドウ。 |
インポート後にwidまたはcidが空の場合は、PrometheusがMetrics APIエンドポイントを正常にスクレイピングしており、X-API-Keyヘッダーが注入されていることを確認してください。
Metricラベル
すべてのサンプルには、VeloDB Cloudによって注入される固定ラベルが含まれています：
| ラベル | 意味 |
|---|---|
provider | aws、gcp、azureなどのクラウドプロバイダー。 |
region | us-east-1やap-northeast-1などのクラウドリージョン。 |
wid | ウェアハウスID。 |
cid | クラスターID。 |
instance | 10.29.0.7:8080のようなノードアドレス。 |
vpc_id | ウェアハウスをホストするVPC ID。 |
product | プロダクト識別子。 |
各サンプル行の末尾の整数は、Prometheus側の収集タイムスタンプ（ミリ秒単位）です。
FAQ
/api/v1/queryのようなPromQLクエリエンドポイントはありますか？
いいえ。Metrics APIは、Prometheusスクレイピング用の生メトリクスエンドポイントを公開します。インタラクティブな探索には、VeloDB Cloudコンソール内の組み込みMetricsページを使用するか、メトリクスをスクレイピングした後に独自のPrometheusをクエリしてください。
標準的な/metricsパスはサポートされていますか？
いいえ。/v1/warehouse/{warehouseId}/metricsまたは/v1/warehouse/{warehouseId}/cluster/{clusterId}/metricsを使用してください。
AuthorizationとX-API-Keyのどちらを使用すべきですか？
X-API-Keyを使用してください。HTTPヘッダー名は大文字小文字を区別しません。
プロバイダー、リージョン、ウェアハウスID、クラスターIDはどこで確認できますか？
VeloDB Cloudコンソールで確認できます。自動化の場合は、Management APIを使用してください：
GET /v1/cloud-providersGET /v1/cloud-providers/{cloudProvider}/regionsGET /v1/warehousesGET /v1/warehouses/{warehouseId}/clusters
プライベートエンドポイントやIP許可リストはサポートされていますか？
Metrics APIエンドポイントは、APIキー認証とレート制限によって保護されたパブリックHTTPSエンドポイントです。プライベート接続が必要な場合は、VeloDB Cloudサポートにお問い合わせください。
次のステップ
- Metrics：コンソールで同じメトリクスをインタラクティブに表示します。
- External monitoring integrations：外部監視プラットフォームにメトリクスをエクスポートします。
- Alerts：メトリクスが閾値を超えたときに通知を受け取ります。