Metrics

VeloDB Cloudは、コンソール内にビルトインメトリックを提供し、Metrics APIを通じて生メトリックを公開します。コンソールを使用してwarehouseやclusterの健全性をインタラクティブに検査するか、Metrics APIをお使いのPrometheusやGrafanaスタックに接続して一元的な可観測性を実現できます。

コンソールでメトリックを表示

Metricsページでは次のことが可能です：

warehouseまたはcluster別にメトリックを表示
Starredを使用して、warehouseやclusterをまたがって関心のあるメトリックをピン留めして一緒に表示
時間セレクターを調整して過去15日までの履歴データを確認
自動更新を有効にしてリアルタイムに近い更新（5秒間隔）を実現

メトリックは2つのカテゴリーに分類されます：Basic Metrics（物理リソース使用率）とService Metrics（クエリ/ワークロード性能）。

Basic Metrics

Basic metricsはclusterのnode別物理使用率を追跡します。これにより、指定した時間範囲でclusterが健全かどうか、また履歴や現在のクエリが性能に影響を与えているかを判断できます。これはスケールアップ、スケールダウン、またはSQLの最適化を計画する際に有用な入力となります。

metrics basic

Metric	表示内容
CPU Utilization	全node間のCPU使用率パーセンテージ。スケーリングや他のリソース集約的な操作のための空き時間帯を見つけるのに有用。
Memory Usage	全nodeで消費されているメモリ。持続的に高い使用量はスケールアップのサインです。
Memory Utilization	全nodeのメモリ使用率。持続的に高い使用率はスケールアップのサインです。
I/O Utilization	ディスクI/O使用率。持続的に高い値は、クエリ性能向上のためにより多くのnodeを追加することを示唆。
Network Outbound Throughput	node当たりの1秒間の平均送信速度（MB/s）。ネットワーク経由でデータを読み込むクエリは低速になります。ネットワーク読み込みを減らすためにキャッシュを設定してください。
Network Inbound Throughput	node当たりの1秒間の平均受信速度（MB/s）。
Cache Read Throughput	1秒当たりのキャッシュ読み込みスループット（MB/s）。
Cache Write Throughput	1秒当たりのキャッシュ書き込みスループット（MB/s）。

サポート範囲：

Metric	Warehouse	Cluster
CPU Utilization	✓	✓
Memory Usage	✓	✓
Memory Utilization	✓	✓
I/O Utilization	✓	✓
Network Outbound Throughput	✓	✓
Network Inbound Throughput	✓	✓
Cache Read Throughput	—	✓
Cache Write Throughput	—	✓

Service Metrics

Service metricsはクエリとワークロードの挙動を追跡します：クエリの実行速度、成功数、書き込みパスの挙動など。

metrics query

Metric	表示内容
Query Per Second (QPS)	1秒当たりのクエリリクエスト数。ピークQPSはclusterサイジング時の有用な入力です。
Query Success Rate	成功したクエリのパーセンテージ、毎分更新。異常な低下はclusterやnodeの障害を示している可能性があります。
Dead Nodes	cluster内の停止node数。
Average Query Runtime	平均クエリ時間、毎分更新。異常な上昇は調査が必要なサインです。
Query 99th Latency	99パーセンタイルクエリの応答時間。低速クエリの速度を反映します。
Cache Hit Rate	キャッシュから提供されたI/O操作のパーセンテージ。低い値はキャッシュポリシーの見直しやキャッシュ容量の増加を示唆。
Remote Storage Read Throughput	単位時間当たりにリモートストレージから読み込まれるデータ量。
Sessions	warehouseのセッション数（cluster別には分割されません）。
Load Rows Per Second	レコードが正常に書き込まれている割合。
Load Bytes Per Second	データ量が書き込まれている割合。
Finished Load Tasks	最近の期間で完了したロードタスク数。急激な変化はビジネス異常を示している可能性があります。
Compaction Score	データファイルマージの圧力。スコアが高いほどマージ圧力が大きいことを意味します。
Transaction Latency	書き込みタスクのトランザクションレイテンシ。低いほどデータがより早くクエリ可能になります。

サポート範囲：

Metric	Warehouse	Cluster
Query Per Second	✓	✓
Query Success Rate	✓	✓
Dead Nodes	—	✓
Average Query Time	✓	✓
Query 99th Latency	✓	✓
Cache Hit Rate	—	✓
Remote Storage Read Throughput	—	✓
Sessions	✓	—
Load Rows Per Second	✓	✓
Load Bytes Per Second	✓	✓
Finished Load Tasks	✓	—
Compaction Score	—	✓
Transaction Latency	✓	—

Metrics API

Metrics APIを使用して、上記で説明したBasic MetricsとService Metricsの背後にある生メトリックを、セルフホスト型のPrometheusやGrafana環境にスクレイピングします。warehouse レベルとclusterレベルの両方の応答には、これらのカテゴリーの生メトリックが含まれます。違いは返されるデータのスコープです。

Metrics APIは2つのエンドポイントを公開します：

API	Path	Description
QueryWarehouseMetrics	`GET /v1/warehouse/{warehouseId}/metrics`	warehouseの生メトリック。
QueryClusterMetrics	`GET /v1/warehouse/{warehouseId}/cluster/{clusterId}/metrics`	指定されたclusterの生メトリック。

両方のエンドポイントはPrometheus exposition formatのテキストを返します：

Content-Type: text/plain; version=0.0.4; charset=utf-8

Prometheusはstatic_configsまたはfile_sd_configsを使用してエンドポイントを直接スクレイプできます。

Endpoint

各リージョンとクラウドプロバイダーには独自のエンドポイントがあります：

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は、その独自のリージョンとクラウドプロバイダーのendpointを通してのみアクセス可能です。クロスリージョンまたはクロスプロバイダーのリクエストは404 Not Foundを返すか、認証に失敗します。

認証

すべてのMetrics APIリクエストには、HTTPヘッダーにAPI keyを含める必要があります:

X-API-Key: sk-xxxxxxxxxxxxxxxxxxxx

APIキーは組織に紐付けられ、キー作成時に選択されたロールを継承します。キーは自身の組織内のウェアハウスにのみアクセスできます。

APIキーを作成するには、API Keysを参照してください。完全なキーは作成時に一度だけ表示されます。すぐにコピーして保存してください。

認証に失敗すると401 Unauthorizedが返されます：

{
  "code": "Unauthorized.InvalidApiKey",
  "message": "invalid API key"
}

レート制限

各APIキーは、エンドポイントあたり毎分100回の読み取りリクエストが許可されています。制限を超えると429 Too Many Requestsが返されます。

Prometheusスクレイピングの場合、スクレイプ間隔は最低15秒、エンドポイントあたり約30ターゲット以下を推奨します。

Query Warehouse Metrics

QueryWarehouseMetricsは、ウェアハウス内のFEノードの生のPrometheusメトリクスを返します。

リクエスト

GET /v1/warehouse/{warehouseId}/metrics
Host: apps-api.<region>.<provider>.velodb.cloud
X-API-Key: sk-xxxx

パスパラメータ

Parameter	Description
`warehouseId`	Warehouse ID、例：`XXZ0RP`

レスポンス

Field	Description
Status	`200 OK`
Content type	`text/plain; version=0.0.4; charset=utf-8`
Body	Prometheus exposition format テキスト。返されるデータはwarehouse スコープのBasic 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

Query Cluster Metrics

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形式のテキスト。返されるデータは、クラスタスコープのBasic 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エクスポジション形式を直接返すため、Prometheusは各エンドポイントをスクレイプターゲットとして扱うことができます。

主要なポイント：

スキームとしてhttpsを使用する。
各パスにはwarehouse IDまたはcluster IDが含まれているため、ターゲットごとに__metrics_path__ラベルを設定する。
X-API-Key HTTPヘッダーを通じてAPIキーを渡す。
file_sd_configsを使用して複数のwarehouseとclusterを管理する。異なるリージョンのwarehouseは、それぞれのエンドポイントホストを指すようにする。

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をスクレイピングすると、コンソールに表示されるBasic MetricsとService Metricsを反映した構築済みのGrafanaダッシュボードをインポートできます。

すぐに使用できる2つのダッシュボードテンプレートがmonitoring-stacksリポジトリで公開されています：

ダッシュボード	ファイル	スコープ
VeloDB Warehouse Monitoring	`grafana_dashboard_warehouse.json`	FEノードリソース、QPS、クエリレイテンシ、接続、ロードジョブ、ルーチンロード、ワークロードグループ。
VeloDB Cluster Monitoring	`grafana_dashboard_cluster.json`	BEノードリソース、デッドノード、クエリパフォーマンス、キャッシュヒット率、リモートS3スループット、ロードスループット、タブレットコンパクションスコア。

ダッシュボードのインポート

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 Labels

すべてのサンプルには、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を使用してください：

プライベートエンドポイントやIP許可リストはサポートされていますか？

Metrics APIエンドポイントは、APIキー認証とレート制限によって保護されたパブリックHTTPSエンドポイントです。プライベート接続が必要な場合は、VeloDB Cloudサポートにお問い合わせください。

コンソールでメトリックを表示​

Basic Metrics​

Service Metrics​

Metrics API​

Endpoint​

認証​

レート制限​

Query Warehouse Metrics​

Query Cluster Metrics​

Prometheusとの統合​

Grafanaでの可視化​

Metric Labels​

FAQ​