Kubernetes Prometheus および OpenMetrics メトリクスの収集

概要

Datadog Agent と OpenMetrics または Prometheus インテグレーションを併用して、Kubernetes 内で実行されているアプリケーションから、公開されている Prometheus および OpenMetrics メトリクスを収集します。デフォルトでは、一般的な Prometheus チェックによって取得されたメトリクスはすべてカスタムメトリクスと見なされます。

バージョン 6.5.0 より、Agent には OpenMetrics および Prometheus チェックが用意され、Prometheus エンドポイントをスクレイピングできます。Prometheus テキスト形式を効率よくフルにサポートできるため、Datadog では OpenMetrics チェックの 使用をお勧めします。カスタムチェックの記述を含む OpenMetricsCheck インターフェイスの高度な使用方法については、開発ツールのセクションを参照してください。Prometheus チェックは、メトリクスのエンドポイントがテキスト形式をサポートしていない場合にのみ使用してください。

このページでは、Prometheus のエンドポイントからカスタムメトリクスをスクレイピングするための、これらのチェックの基本的な使い方を説明します。Prometheus や OpenMetrics のメトリクスと Datadog のメトリクスのマッピング方法については、Prometheus メトリクスと Datadog メトリクスのマッピングガイドを参照してください。

セットアップ

インストール

Kubernetes クラスターに Datadog Agent をデプロイします。OpenMetrics および Prometheus チェックは Datadog Agent パッケージに含まれています。コンテナまたはホストに追加でインストールする必要はありません。

構成

OpenMetrics/Prometheus のメトリクスを公開する pod に以下の annotations を適用し、オートディスカバリーを使用して OpenMetrics または Prometheus のチェックを構成します。

注: AD Annotations v2 は、インテグレーション構成を簡素化するために、Datadog Agent バージョン 7.36 で導入されました。Datadog Agent の以前のバージョンでは、AD Annotations v1 を使用してください。

# (...)
metadata:
  #(...)
  annotations:
    ad.datadoghq.com/<CONTAINER_IDENTIFIER>.checks: |
      {
        "openmetrics": {
          "init_config": {},
          "instances": [
            {
              "openmetrics_endpoint": "http://%%host%%:%%port%%/<PROMETHEUS_ENDPOINT> ",
              "namespace": "<METRICS_NAMESPACE_PREFIX_FOR_DATADOG>",
              "metrics": [{"<METRIC_TO_FETCH>":"<NEW_METRIC_NAME>"}]
            }
          ]
        }
      }      

spec:
  containers:
    - name: '<CONTAINER_IDENTIFIER>'
# (...)
metadata:
  #(...)
  annotations:
    ad.datadoghq.com/<CONTAINER_IDENTIFIER>.check_names: |
      ["openmetrics"]      
    ad.datadoghq.com/<CONTAINER_IDENTIFIER>.init_configs: |
      [{}]      
    ad.datadoghq.com/<CONTAINER_IDENTIFIER>.instances: |
      [
        {
          "openmetrics_endpoint": "http://%%host%%:%%port%%/<PROMETHEUS_ENDPOINT> ",
          "namespace": "<METRICS_NAMESPACE_PREFIX_FOR_DATADOG>",
          "metrics": [{"<METRIC_TO_FETCH>":"<NEW_METRIC_NAME>"}]
        }
      ]      
spec:
  containers:
    - name: '<CONTAINER_IDENTIFIER>'

コンフィギュレーションには次のプレースホルダー値を使用します。

プレースホルダー説明
<CONTAINER_IDENTIFIER>annotations で使用される識別子は、メトリクスを公開しているコンテナ name と一致しなければならない。
<PROMETHEUS_ENDPOINT>コンテナによって処理されたメトリクスの URL パス (Prometheus 形式)。
<METRICS_NAMESPACE_PREFIX_FOR_DATADOG>Datadog で表示するときに、すべてのメトリクスの前にネームスペースを付加します。
<METRIC_TO_FETCH>Prometheus エンドポイントから取得される Prometheus メトリクスキー。
<NEW_METRIC_NAME>Datadog の <METRIC_TO_FETCH> メトリクスキーを <NEW_METRIC_NAME> に変換します。

The metrics configuration is a list of metrics to retrieve as custom metrics. Include each metric to fetch and the desired metric name in Datadog as key value pairs, for example, {"<METRIC_TO_FETCH>":"<NEW_METRIC_NAME>"}. To prevent excess custom metrics charges, Datadog recommends limiting the scope to only include metrics that you need. You can alternatively provide a list of metric names strings, interpreted as regular expressions, to bring the desired metrics with their current names. If you want all metrics, then use ".*" rather than "*".

注: 正規表現では、多くのカスタムメトリクスを送信できる可能性があります。

namespacemetrics など、インスタンスで利用可能なパラメーターの一覧は、構成例 openmetrics.d/conf.yaml を参照してください。

はじめに

シンプルなメトリクスの収集

  1. Datadog Agent を起動します

  2. Prometheus prometheus.yaml を使用して、ポッドにオートディスカバリーの構成をした Prometheus Deployment の例を起動します。

    注: AD Annotations v2 は、インテグレーション構成を簡素化するために、Datadog Agent バージョン 7.36 で導入されました。Datadog Agent の以前のバージョンでは、AD Annotations v1 を使用してください。

      # (...)
     spec:
       template:
         metadata:
           annotations:
             ad.datadoghq.com/prometheus-example.checks: |
               {
                 "openmetrics": {
                   "instances": [
                     {
                       "openmetrics_endpoint": "http://%%host%%:%%port%%/metrics",
                       "namespace": "documentation_example_kubernetes",
                       "metrics": [
                           {"promhttp_metric_handler_requests": "handler.requests"},
                           {"promhttp_metric_handler_requests_in_flight": "handler.requests.in_flight"},
                           "go_memory.*"
                         ]
                     }
                   ]
                 }
               }           
         spec:
           containers:
           - name: prometheus-example
           # (...)
    
      # (...)
     spec:
       template:
         metadata:
           annotations:
             ad.datadoghq.com/prometheus-example.check_names: |
               ["openmetrics"]           
             ad.datadoghq.com/prometheus-example.init_configs: |
               [{}]           
             ad.datadoghq.com/prometheus-example.instances: |
               [
                 {
                   "openmetrics_endpoint": "http://%%host%%:%%port%%/metrics",
                   "namespace": "documentation_example_kubernetes",
                   "metrics": [
                     {"promhttp_metric_handler_requests": "handler.requests"},
                     {"promhttp_metric_handler_requests_in_flight": "handler.requests.in_flight"},
                     "go_memory.*"
                   ]
                 }
               ]           
         spec:
           containers:
           - name: prometheus-example
           # (...)
    

    Prometheus Deployment を作成するコマンド:

    kubectl create -f prometheus.yaml
    
  3. Metric summary ページにアクセスし、このサンプルポッドから収集されたメトリクスを確認します。この構成では、promhttp_metric_handler_requestspromhttp_metric_handler_requests_in_flight、および go_memory で始まるすべての公開メトリクスを収集することになります。

    Kubernetes で収集された Prometheus メトリクス

Prometheus アノテーションによるメトリクスの収集

Prometheus Autodiscovery を使用して、Datadog Agent でネイティブ Prometheus アノテーション(prometheus.io/scrapeprometheus.io/pathprometheus.io/port など)を検出し、Kubernetes で自動的に Prometheus メトリクスを収集するよう OpenMetrics チェックをスケジュールできます。

要件

  • Datadog Agent v7.27 以降または v6.27 以降 (Pod チェックの場合)
  • Datadog Cluster Agent v1.11 以降(サービスおよびエンドポイントチェックの場合)

構成

この機能を有効にする前に、まずどのポッドやサービスが prometheus.io/scrape=true アノテーションを持っているかをチェックすることをお勧めします。これは以下のコマンドで行うことができます。

kubectl get pods -o=jsonpath='{.items[?(@.metadata.annotations.prometheus\.io/scrape=="true")].metadata.name}' --all-namespaces

kubectl get services -o=jsonpath='{.items[?(@.metadata.annotations.prometheus\.io/scrape=="true")].metadata.name}' --all-namespaces

Prometheus スクレイピング機能が有効になると、Datadog Agent はこれらのリソースからカスタムメトリクスを収集します。これらのリソースからカスタムメトリクスを収集したくない場合は、このアノテーションを削除するか、高度な構成セクションで説明されているようにオートディスカバリールールを更新することができます。

Note: Enabling this feature without advanced configuration can cause a significant increase in custom metrics, which can lead to billing implications. See the advanced configuration section to learn how to only collect metrics from a subset of containers/pods/services.

基本のコンフィギュレーション

Update your Datadog Operator configuration to contain the following:

datadog-agent.yaml

apiVersion: datadoghq.com/v2alpha1
kind: DatadogAgent
metadata:
  name: datadog
spec:
  global:
    credentials:
      apiKey: <DATADOG_API_KEY>

  features:
    prometheusScrape:
      enabled: true
      enableServiceEndpoints: true

変更後、以下のコマンドを使用して新しい構成を適用します。

kubectl apply -n $DD_NAMESPACE -f datadog-agent.yaml

Update your Helm configuration to contain the following:

datadog-values.yaml

datadog:
  # (...)
  prometheusScrape:
    enabled: true
    serviceEndpoints: true
  # (...)

After making your changes, upgrade your Datadog Helm chart using the following command:

helm upgrade -f datadog-values.yaml <RELEASE NAME> datadog/datadog

Agent 用の DaemonSet マニフェスト daemonset.yaml に、Agent コンテナ用の以下の環境変数を追加します。

- name: DD_PROMETHEUS_SCRAPE_ENABLED
  value: "true"
- name: DD_PROMETHEUS_SCRAPE_VERSION
  value: "2"

Cluster Agent が有効な場合、そのマニフェスト cluster-agent-deployment.yaml 内に、Cluster Agent コンテナ用の以下の環境変数を追加します。

- name: DD_PROMETHEUS_SCRAPE_ENABLED
  value: "true"
- name: DD_PROMETHEUS_SCRAPE_SERVICE_ENDPOINTS
  value: "true"

これにより、Datadog Agent がネイティブ Prometheus アノテーションのあるポッドを検出し、対応する OpenMetrics チェックを生成するよう指示します。

また、Datadog Cluster Agent(有効な場合)にネイティブ Prometheus アノテーションのあるサービスを検出し、対応する OpenMetrics チェックを生成するよう指示します。

  • prometheus.io/scrape=true: 必須。
  • prometheus.io/path: 任意。デフォルトは /metrics
  • prometheus.io/port: 任意。デフォルトは %%port%% で、container/service により置換されるテンプレート変数

このコンフィギュレーションでは、OpenMetrics インテグレーションのデフォルトコンフィギュレーションを使用して、公開されたすべてのメトリクスを収集するチェックを生成します。

高度なコンフィギュレーション

You can further configure metric collection (beyond native Prometheus annotations) with the additionalConfigs field.

Additional OpenMetrics check configurations

Use additionalConfigs.configurations to define additional OpenMetrics check configurations. See the list of supported OpenMetrics parameters that you can pass in additionalConfigs.

Custom Autodiscovery rules

Use additionalConfigs.autodiscovery to define custom Autodiscovery rules. These rules can be based on container names, Kubernetes annotations, or both.

additionalConfigs.autodiscovery.kubernetes_container_names
A list of container names to target, in regular expression format.
additionalConfigs.autodiscovery.kubernetes_annotations
Two maps (include and exclude) of annotations to define discovery rules.

Default:

include:
   prometheus.io/scrape: "true"
exclude:
   prometheus.io/scrape: "false"

If both kubernetes_container_names and kubernetes_annotations are defined, AND logic is used (both rules must match).

The following configuration targets a container named my-app running in a pod with the annotation app=my-app. The OpenMetrics check configuration is customized to enable the send_distribution_buckets option and define a custom timeout of 5 seconds.

Update your Datadog Operator configuration to contain the following:

datadog-agent.yaml

apiVersion: datadoghq.com/v2alpha1
kind: DatadogAgent
metadata:
  name: datadog
spec:
  global:
    credentials:
      apiKey: <DATADOG_API_KEY>

  features:
    prometheusScrape:
      enabled: true
      enableServiceEndpoints: true
      additionalConfigs:
        - autodiscovery:
            kubernetes_container_names:
              - my-app
            kubernetes_annotations:
              include:
                app: my-app
          configurations:
            - timeout: 5
              send_distribution_buckets: true

datadog-values.yaml

datadog:
  # (...)
  prometheusScrape:
    enabled: true
    serviceEndpoints: true
    additionalConfigs:
      - autodiscovery:
          kubernetes_container_names:
            - my-app
          kubernetes_annotations:
            include:
              app: my-app
        configurations:
          - timeout: 5
            send_distribution_buckets: true

For DaemonSet, advanced configuration is defined in the DD_PROMETHEUS_SCRAPE_CHECKS environment variable, not an additionalConfigs field.

- name: DD_PROMETHEUS_SCRAPE_ENABLED
  value: "true"
- name: DD_PROMETHEUS_SCRAPE_CHECKS
  value: "[{\"autodiscovery\":{\"kubernetes_annotations\":{\"include\":{\"app\":\"my-app\"}},\"kubernetes_container_names\":[\"my-app\"]},\"configurations\":[{\"send_distribution_buckets\":true,\"timeout\":5}]}]"
- name: DD_PROMETHEUS_SCRAPE_VERSION
  value: "2"

カスタムインテグレーションを公式インテグレーションに

デフォルトでは、汎用の Prometheus チェックによって取得されるすべてのメトリクスが、カスタムメトリクスだと見なされます。既製ソフトウェアを監視されて、公式のインテグレーションにするべきだと思われた場合は、ぜひご提供をお願いします

公式インテグレーションは、それぞれ専用のディレクトリを持ちます。汎用のチェックには、デフォルトの構成とメトリクスメタデータをハードコードするためのデフォルトのインスタンスメカニズムがあります。たとえば、kube-proxy インテグレーションを参照します。

その他の参考資料