Datadog AgentでVeloDB Cloudメトリクスを収集する

Datadog AgentのOpenMetricsチェックを使用して、VeloDB Cloud Metrics APIから選択したメトリクスを収集し、Datadogの組織に送信します。

VeloDB Cloud Metrics API
        -> Datadog Agent in your environment
        -> Datadog custom metrics
        -> Metrics Explorer

Agentは HTTPS 経由でメトリクスを取得し、Datadogに送信します。VeloDB と Datadog の認証情報は環境内に残ります。この統合はメトリクスのみを送信し、Datadog APM トレースは送信しません。

スコープと互換性

これは Datadog 専用のエンドツーエンド設定ガイドです。Datadog は現在検証済みの外部監視の例です。他のコレクターとのプロトコルレベルの互換性については、External monitoring integrations を参照してください。

Private Preview: Metrics API は現在 Private Preview で利用可能です。開始する前に、組織で有効になっていることを確認してください。エンドポイントの動作、認証、レート制限、ラベルについては、Metrics API を参照してください。

始める前に

以下が必要です：

Metrics API アクセスが有効な VeloDB Cloud ウェアハウス
対象ウェアハウスを読み取り可能な最小権限ロールを持つ VeloDB Cloud API キー。Cloud API Keys を参照してください
対象のプロバイダー、リージョン、ウェアハウス ID。クラスターレベルのメトリクスを収集する場合のみクラスター ID が必要です
Datadog 組織と、Datadog Agent をインストールおよび設定できるホスト
Agent ホストから VeloDB Metrics API への HTTPS 経由のネットワークアクセスと、Datadog site へのアクセス
設定例で使用される VeloDB API キーを解決するための Datadog Agent secret backend

OpenMetrics チェックによって収集されるメトリクスは、Datadog カスタムメトリクスとして課金されます。コストとタグのカーディナリティを制御するため、小さな明示的なメトリクスとラベルの許可リストから開始してください。

1. エンドポイントスコープを選択する

両方のエンドポイントタイプを設定する必要はありません。必要なメトリクスを含むスコープを選択してください：

スコープ	用途	エンドポイント
Warehouse	FE およびサービスメトリクスを含むウェアハウスレベルのデータ。ウェアハウス ID のみが必要なため、最初の接続テストの推奨開始点です。	`https://apps-api.<REGION>.<PROVIDER>.velodb.cloud/v1/warehouse/<WAREHOUSE_ID>/metrics`
Cluster	BE、キャッシュ、I/O、ロード、またはコンパクションメトリクスなど、特定のコンピュートまたはオブザーバークラスターからのメトリクス。	`https://apps-api.<REGION>.<PROVIDER>.velodb.cloud/v1/warehouse/<WAREHOUSE_ID>/cluster/<CLUSTER_ID>/metrics`

初期接続テストでは、1つのウェアハウスエンドポイントを使用してください。動作後、ウェアハウスレベルのメトリクスが必要な場合のみそれを維持し、監視したい各クラスターに対して個別のクラスターエンドポイントを追加してください。すべてのエンドポイントは独立した OpenMetrics インスタンスであり、異なるメトリクスファミリーを公開できます。

表示名やマーケティング名ではなく、ウェアハウス用のプロバイダーとリージョンの識別子を使用してください。

2. Metrics API を検証する

Datadog Agent を設定する前にエンドポイントを検証してください。以下のリクエストは、レスポンスボディを表示せずに HTTP ステータスとレスポンスヘッダーをチェックします：

curl -sS -D - -o /dev/null \
  -H 'X-API-Key: <VELODB_API_KEY>' \
  '<VELODB_METRICS_ENDPOINT>'

レスポンスに以下が含まれていることを確認してください：

ステータス 200 OK
コンテンツタイプ text/plain; version=0.0.4 または他の互換性のあるPrometheusテキストコンテンツタイプ

ラベル値を出力せずに、エンドポイントから返されるメトリック名を一覧表示してください：

curl -fsS \
  -H 'X-API-Key: <VELODB_API_KEY>' \
  '<VELODB_METRICS_ENDPOINT>' \
  | awk '!/^#/ && NF {name=$1; sub(/\{.*/, "", name); print name}' \
  | sort -u

各メトリックファミリーの宣言された型を検査するには：

curl -fsS \
  -H 'X-API-Key: <VELODB_API_KEY>' \
  '<VELODB_METRICS_ENDPOINT>' \
  | awk '$1 == "#" && $2 == "TYPE" {print $3, $4}' \
  | sort -u

APIキー、完全なエンドポイント、レスポンスボディ、またはラベル値をソース管理、チケット、またはスクリーンショットにコピーしないでください。

初期メトリクスを選択する

最初の接続テストのために1つから3つの正確なソースメトリクスを選択してください。メトリクスは選択したエンドポイントに存在する必要があります。常に存在するメトリクスから開始し、監視目標をサポートする場合のみアクティビティまたはリソースメトリクスを追加してください。

このガイドで後述する例は、必須メトリクスや推奨される監視ベースラインではありません。これらは現在値ゲージ、アクティビティカウンター、およびバイト単位で測定されるリソースゲージをマッピングする方法を示しています。

必要な監視カテゴリを選択するにはMetrics catalogを使用してください。生のソースメトリクスの意味やタイプが不明な場合は、Datadogタイプを割り当てる前にVeloDB Supportに連絡してください。メトリクス名やサフィックスのみからタイプを推測しないでください。

Metrics APIでは最低15秒のスクレイプ間隔を推奨しています。このガイドでは30秒を使用します。

3. Datadog Agentをインストールする

VeloDB Metrics APIとDatadogサイトの両方に到達できるホストにDatadog Agentをインストールしてください。お使いのオペレーティングシステム用のDatadog Agentインストールガイドに従ってください。

OpenMetrics設定を追加する前に、Agentが実行されていることを確認してください：

sudo datadog-agent status

4. OpenMetricsチェックを設定する

Datadog Agent設定ディレクトリの下にconf.d/openmetrics.d/conf.yamlを作成してください。

以下の設定では、最新のOpenMetricsモードとVeloDB APIキー用のシークレットハンドルを使用します：

init_config:

instances:
  - openmetrics_endpoint: "<VELODB_METRICS_ENDPOINT>"
    namespace: velodb
    min_collection_interval: 30
    tag_by_endpoint: false

    headers:
      Accept: text/plain
      X-API-Key: "ENC[velodb_metrics_api_key]"

    metrics:
      - "<SOURCE_METRIC_NAME>":
          name: "<DATADOG_METRIC_SUFFIX>"
          type: "<METRIC_TYPE>"

    include_labels:
      - provider
      - region
      - wid
      - cid
      - product

    exclude_labels:
      - instance
      - vpc_id
      - user
      - job
      - exported_job
      - custom_scheme
      - cluster_name

Agent を再起動する前に、すべてのプレースホルダーを置き換えてください：

プレースホルダー	置き換え先
`<VELODB_METRICS_ENDPOINT>`	ステップ1で選択した完全なウェアハウスまたはクラスターエンドポイント。
`<SOURCE_METRIC_NAME>`	選択したエンドポイントによって返される正確で大文字小文字を区別する名前。
`<DATADOG_METRIC_SUFFIX>`	`velodb.` 名前空間に追加する名前。
`<METRIC_TYPE>`	`gauge` または `counter` など、検証済みのタイプ。

選択した各ソースメトリックに対して1つの metrics エントリを追加してください。.* や doris_.* などの広範囲な正規表現は使用しないでください。これらは大量の Datadog カスタムメトリックを作成する可能性があります。

ENC[velodb_metrics_api_key] は、そのハンドルを解決できる Datadog Agent シークレットバックエンドを設定した後にのみ機能します。設定ファイル内でプレーンテキストの本番キーに置き換えないでください。

ラベルリストは控えめな出発点です。ダッシュボードとモニターに必要なディメンションのみを保持してください。データガバナンスポリシーの下で wid や cid などの識別子を確認してください。承認された必要性がない限り、ノードアドレス、VPC ID、ユーザー名、その他の機密性が高いまたは高カーディナリティのラベルは除外したままにしてください。

オプションのマッピング例

選択したエンドポイントが同じソースメトリックを返す場合にのみ、これらのマッピングを使用してください：

metrics:
  - doris_fe_connection_total:
      name: fe.connections
      type: gauge
  - doris_fe_query_total:
      name: fe.queries.count
      type: counter
  - node_memory_Cached_bytes:
      name: node.memory.cached_bytes
      type: gauge

ソースメトリック	送信されるDatadogメトリック	例の目的
`doris_fe_connection_total`	`velodb.fe.connections`	`_total`という接尾辞があるにもかかわらず、ゲージとして表現される現在の接続数。
`doris_fe_query_total`	`velodb.fe.queries.count`	カウンターとして表現される累積クエリアクティビティ。
`node_memory_Cached_bytes`	`velodb.node.memory.cached_bytes`	バイト単位のリソースゲージ。

これら3つのメトリックは例に過ぎません。選択したエンドポイントから返される正確なメトリックであれば、まずその意味とタイプを確認した上で、これらを任意のものに置き換えることができます。

VeloDBは生のメトリックファミリーをuntypedとして公開する場合があるため、この例では各タイプを明示的に設定しています。Datadog Agentのバージョンでは、_totalで終わるカウンター名を正規化できます。ソースファミリーがカウンターとして宣言されている場合、現在のAgentバージョンでは_totalを除いた設定済みソース名を期待し、.countを追加します。datadog-agent check openmetricsによって報告されるメトリック名を権威のあるものとして扱い、必要に応じてマッピングを調整してください。Datadog OpenMetrics configurationを参照してください。

5. 設定の読み込みと検証

お使いのオペレーティングシステム用のコマンドを使用してDatadog Agentを再起動し、次に実行します：

sudo datadog-agent configcheck
sudo datadog-agent check openmetrics
sudo datadog-agent status

以下のすべてを確認してください：

configcheckがconf.d/openmetrics.d/conf.yamlを読み込む
OpenMetricsチェックがゼロより大きなメトリックサンプルを報告する
チェックにHTTP、認証、TLS、パーサー、シークレット解決、またはメトリックマッピングエラーがない
送信されたメトリック名が期待されるvelodb.ネームスペースを使用している

カウンターの動作を評価する前に、少なくとも2つのコレクション間隔を許可してください。

6. Datadogでメトリックを確認する

Datadogで、Metrics > Explorerを開きます。
グローバルDatadog検索ボックスではなく、メトリッククエリフィールドを使用してください。
設定された各メトリックを検索します：velodb.<DATADOG_METRIC_SUFFIX>。
Agentの再起動後、少なくとも2つのコレクション間隔を含む時間範囲を選択してください。
異なる単位や大きさを持つメトリックを比較する際は、One graph per queryを有効にしてください。
最近のポイントに期待されるwarehouseまたはclusterタグがあることを確認してください。
instanceやvpc_idを含む除外されたラベルが存在しないことを確認してください。

Metrics APIが200を返し、Agentチェックにサンプルがありエラーがなく、選択されたvelodb.*メトリックの少なくとも1つがMetrics Explorerに最近のポイントを持つ場合、接続は成功です。

7. インテグレーションを拡張する

最初のメトリックが表示された後：

監視目標に基づいて、正確なメトリックの小さなグループを追加してください。
各ソースメトリックの可用性、セマンティクス、およびタイプを確認してください。
ラベルと期待されるカスタムメトリックカーディナリティを確認してください。
Agentの検証コマンドを再実行してください。
Metrics Explorerで送信された名前とタグを確認してください。

追加のwarehouseまたはclusterエンドポイントごとに、別のinstancesエントリを使用してください。異なるプロバイダーやリージョンのwarehouseは、異なるエンドポイントホストを使用します。メトリック名、タイプ、およびタグが安定した後に、ダッシュボードとモニターを作成してください。

トラブルシューティング

症状	確認すべき項目
APIからの`401`または`403`	APIキーのステータス、割り当てられたロール、組織、およびMetrics APIの権限。
APIからの`404`	warehouseのステータス、プロバイダー、リージョン、warehouseまたはcluster ID、およびエンドポイントパス。
APIからの`429`	キーとエンドポイントのスクレイプ頻度またはターゲット数を減らす。
`200`だがメトリックサンプルがない	正確で大文字小文字を区別するソースメトリックが存在し、明示的なタイプマッピングを持つことを確認する。
型なしメトリックがスキップされる	検証済みの`gauge`または`counter`タイプを明示的に設定する。
カウンター名が予期しない	Agentバージョンの`_total`正規化と`check openmetrics`によって報告される送信名を確認する。
メトリックがMetrics Explorerに表示されない	ネームスペース、Agent出力、選択された時間範囲、およびMetrics Explorerクエリフィールドを確認する。
カスタムメトリック使用量が予期せず高い	正規表現を削除し、メトリックとラベルの許可リストを削減する。

TLS検証を有効にしておいてください。ネットワークや証明書のエラーを回避するために証明書検証を無効にしないでください。

セキュリティ、コスト、およびクリーンアップ

VeloDBとDatadog APIキーをシークレット管理システムに保管し、セキュリティポリシーに従ってローテーションしてください。
完全なエンドポイントがタグとして追加されないよう、tag_by_endpoint: falseを維持してください。
機密性の高いラベルや高カーディナリティのラベルは、必要で承認されている場合を除き除外してください。
メトリックやラベルの許可リストを拡張する前に、Datadogカスタムメトリック課金を確認してください。
インテグレーションを削除するには、そのOpenMetricsインスタンスを削除し、Agentを再起動し、不要になった認証情報を取り消してください。

追加のAgentオプションとバージョン固有の動作については、Datadog OpenMetricsを参照してください。

スコープと互換性​

始める前に​

1. エンドポイントスコープを選択する​

2. Metrics API を検証する​

初期メトリクスを選択する​

3. Datadog Agentをインストールする​

4. OpenMetricsチェックを設定する​

オプションのマッピング例​

5. 設定の読み込みと検証​

6. Datadogでメトリックを確認する​

7. インテグレーションを拡張する​

トラブルシューティング​

セキュリティ、コスト、およびクリーンアップ​