エージェントからのカスタム指標

このガイドでは、Monitoring エージェントがアプリケーション指標を認識し、Cloud Monitoring にエクスポートするように設定する方法について説明します。

モニタリング エージェントは collectd デーモンです。エージェントは、Cloud Monitoring に多くの定義済みシステム指標とサードパーティ指標をエクスポートするだけでなく、独自の collectd アプリケーション指標をカスタム指標として Monitoring にエクスポートできます。collectd プラグインは、Monitoring にエクスポートすることもできます。

アプリケーション指標を Monitoring にエクスポートする別の方法として、StatsD を使用することもできます。Cloud Monitoring には、StatsD 指標をカスタム指標にマップするデフォルト構成が用意されています。そのマッピングだけで十分な場合は、以下に説明するカスタマイズ手順を実施する必要はありません。 詳細については、StatsD プラグインをご覧ください。

Monitoring のカスタム指標についての基本的な情報については、指標、時系列、リソース時系列の構造カスタム指標の使用をご覧ください。

始める前に

  • 最新のモニタリング エージェントを VM インスタンスにインストールし、正しく機能することを確認します。エージェントを更新するには、エージェントの更新をご覧ください。

  • アプリケーションからモニタリング データを収集するように collectd を構成します。 collectd は、読み取りプラグインを通じて多くのアプリケーション フレームワークや標準のモニタリング エンドポイントをサポートします。ご使用の環境で適切に機能する読み取りプラグインを探してください。

  • (省略可)エージェントの collectd リファレンス ドキュメントをシステムの man ページに追加しておくと便利です。そのためには、次のように MANPATH 変数を更新して mandb を実行します。

    export MANPATH="$MANPATH:/opt/stackdriver/collectd/share/man"
        sudo mandb
        

    man ページは stackdriver-collectd 用です。

重要なファイルとディレクトリ

エージェントをインストールすると、次のファイルとディレクトリが作成されます。これらは Monitoring エージェント(collectd)の構成に関連しています。

/etc/stackdriver/collectd.conf

エージェントによって使用される collectd 構成ファイル。このファイルを編集して一般構成を変更します。

/etc/stackdriver/collectd.d/

ユーザーが追加する構成ファイル用のディレクトリ。エージェントからカスタム指標を送信するには、後述する必要な構成ファイルをこのディレクトリに配置します。下位互換性のために、エージェントは /opt/stackdriver/collectd/etc/collectd.d/ 内のファイルも検索します。

/opt/stackdriver/collectd/share/man/*

エージェントの collectd バージョンのドキュメント。これらのページをシステムの一連の man ページに追加できます。詳細については、始める前にをご覧ください。

/etc/init.d/stackdriver-agent

エージェントの初期化スクリプト。

Monitoring による collectd 指標の処理方法

バックグラウンドとして、Monitoring エージェントは collectd 指標を処理して Monitoring に送信します。Monitoring は各指標を次のいずれかのカテゴリのメンバーとして扱います。

  • カスタム指標。collectd 指標のうち、メタデータキーが stackdriver_metric_typeデータソースを 1 つだけ持つものはカスタム指標として処理され、Monitoring API の projects.timeSeries.create メソッドを使用して Monitoring に送信されます。

  • キュレートされる指標。その他すべての collectd 指標は、内部 API を使用して Monitoring に送信されます。キュレートされる指標のリスト内の指標だけが受け入れられ、処理されます。

  • 破棄される指標。キュレートされる指標のリストに存在せず、カスタム指標でもない collectd 指標は、Monitoring によって通知なく破棄されます。エージェント自体は、どの指標が受け入れられ、どの指標が破棄されるかを知りません。

エージェントでのカスタム指標の作成

Monitoring に指標データポイントを送信するようにエージェントを構成します。指標記述子で定義したカスタム指標に各ポイントを関連付ける必要があります。これらのコンセプトについては、指標、時系列、リソースで紹介しています。詳細については、時系列の構造カスタム指標の使用をご覧ください。

適切なメタデータを指標に追加することで、collectd 指標をカスタム指標として扱うことができます。

  • stackdriver_metric_type:(必須)エクスポートされる指標の名前。 例: custom.googleapis.com/my_custom_metric

  • label:[LABEL]:(省略可)エクスポートされる指標の追加ラベル。たとえば、color という名前の Monitoring STRING ラベルが必要な場合、メタデータキーは label:color のようになり、キーの値は "blue" にすることができます。指標タイプごとに最大 10 個のラベルを作成できます。

collectd フィルタ チェーンを使用して、指標のメタデータを変更できます。フィルタ チェーンはデータソースのリストを変更できず、カスタム指標は単一のデータソースのみをサポートするため、この機能で使用する collectd 指標には単一のデータソースが必要です。

この例では、2 つの Nginx サービス my_service_amy_service_b からアクティブな Nginx 接続をモニタリングします。カスタム指標を使用してこれらの接続を Monitoring に送信します。手順は次のとおりです。

  1. 各 Nginx サービスの collectd 指標を識別します。

  2. Monitoring の指標記述子を定義します。

  3. モニタリング エージェントの要件に合わせて、collectd 指標にメタデータを追加するように collectd フィルタ チェーンを構成します。

受信 collectd 指標

collectd の指標は次のコンポーネントで構成されている必要があります。最初の 5 つのコンポーネントが指標の collectd 識別子を構成します。

        Host, Plugin, Plugin-instance, Type, Type-instance, [value]
    

この例では、カスタム指標として送信する指標は次のような値を持ちます。

コンポーネント 期待される値
ホスト 任意
プラグイン curl_json
プラグイン インスタンス nginx_my_service_a または
nginx_my_service_b1
gauge
タイプ インスタンス active-connections
[value] 任意値2

:
1 この例では、この値でアプリケーション(Nginx)と接続サービス名の両方をエンコードしています。
2 この値は通常、タイムスタンプと倍精度数です。Monitoring は、さまざまな種類の値の解釈に詳細に対応しています。現在、複合値は Monitoring エージェントによってサポートされていません。

Monitoring の指標記述子と時系列

Monitoring 側でカスタム指標の指標記述子を設計します。この例のデータでは次の記述子を使用するのが妥当です。

  • 名前: custom.googleapis.com/nginx/active_connections
  • ラベル:
    • service_name(STRING): Nginx に接続されるサービスの名前。
  • 種類: GAUGE
  • 型: DOUBLE

設計した指標記述子は、projects.metricDescriptors.create を使用して作成することも、以下で説明する時系列メタデータから自動的に作成することもできます。詳しくは、このページの指標記述子の作成をご覧ください。

指標記述子の定義方法のため、この指標記述子の時系列データには次の情報が含まれる必要があります。

  • 指標名: custom.googleapis.com/nginx/active_connections
  • 指標ラベルの値:
    • service_name: "my_service_a" または "my_service_b"

その他の時系列情報、たとえば関連付けられたモニタリング対象リソース(データを送信する VM インスタンス)や指標のデータポイントなどは、エージェントがすべての指標について自動的に取得します。特に何も行う必要はありません。

フィルタ チェーン

次のコードを含むファイル /opt/stackdriver/collectd/etc/collectd.d/nginx_curl_json.conf を作成します。

LoadPlugin match_regex
    LoadPlugin target_set
    LoadPlugin target_replace

    # Insert a new rule in the default "PreCache" chain, to divert your metrics.
    PreCacheChain "PreCache"
    <Chain "PreCache">
      <Rule "jump_to_custom_metrics_from_curl_json">
        # If the plugin name and instance match, this is PROBABLY a metric we're looking for:
        <Match regex>
          Plugin "^curl_json$"
          PluginInstance "^nginx_"
        </Match>
        <Target "jump">
          # Go execute the following chain; then come back.
          Chain "PreCache_curl_json"
        </Target>
      </Rule>
      # Continue processing metrics in the default "PreCache" chain.
    </Chain>

    # Following is a NEW filter chain, just for your metric.
    # It is only executed if the default chain "jumps" here.
    <Chain "PreCache_curl_json">

      # The following rule does all the work for your metric:
      <Rule "rewrite_curl_json_my_special_metric">
        # Do a careful match for just your metrics; if it fails, drop down
        # to the next rule:
        <Match regex>
          Plugin "^curl_json$"                   # Match on plugin.
          PluginInstance "^nginx_my_service_.*$" # Match on plugin instance.
          Type "^gauge$"                         # Match on type.
          TypeInstance "^active-connections$"    # Match on type instance.
        </Match>

        <Target "set">
          # Specify the metric descriptor name:
          MetaData "stackdriver_metric_type" "custom.googleapis.com/nginx/active_connections"
          # Specify a value for the "service_name" label; clean it up in the next Target:
          MetaData "label:service_name" "%{plugin_instance}"
        </Target>

        <Target "replace">
          # Remove the "nginx_" prefix in the service_name to get the real service name:
          MetaData "label:service_name" "nginx_" ""
        </Target>
      </Rule>

      # The following rule is run after rewriting your metric, or
      # if the metric wasn't one of your custom metrics. The rule returns to
      # the default "PreCache" chain. The default processing
      # will write all metrics to Cloud Monitoring,
      # which will drop any unrecognized metrics: ones that are not
      # in the list of curated metrics and do not have
      # the custom metric metadata.
      <Rule "go_back">
        Target "return"
      </Rule>
    </Chain>
    

新しい構成の読み込み

VM インスタンスで次のコマンドを実行することにより、エージェントを再起動して新しい構成を読み込みます。

sudo service stackdriver-agent restart
    

これで、カスタム指標の情報が Monitoring に流れ込みます。

リファレンスとベスト プラクティス

指標記述子と時系列

Cloud Monitoring の指標の概要については、指標、時系列、リソースをご覧ください。 詳細については、カスタム指標の使用時系列の構造をご覧ください。

指標記述子。指標記述子には次の重要な要素があります。

  • 形式 custom.googleapis.com/[NAME1]/.../[NAME0]名前。例:

    custom.googleapis.com/my_measurement
        custom.googleapis.com/instance/network/received_packets_count
        custom.googleapis.com/instance/network/sent_packets_count
        

    カスタム指標の名前は custom.googleapis.com/ で始まる必要があります。推奨される命名規則は、ユーザーが指標を追跡しやすい階層形式です。指標名にハイフンを使用することはできません。厳密な命名規則については、指標タイプとラベルの命名をご覧ください。

  • 指標データにアノテーションを付けるラベル(device_namefault_typeresponse_code など)。最大 10 個のラベルを付けることができます。ラベルの値は指標記述子で指定されていません。

  • データポイントの種類と型(「DOUBLE 型のゲージ値」など)。詳しくは、MetricKindValueType をご覧ください。

時系列。指標データポイントには次の重要な要素があります。

  • 関連付けられている指標記述子の名前。

  • 指標記述子のすべてのラベルの値。

  • 型と種類が指標記述子と一致している、タイムスタンプ付きの値。

  • データの送信元であるモニタリング対象リソース。通常これは VM インスタンスです。このリソースのためのスペースは組み込まれているため、記述子でこのリソース用のラベルを別に定義する必要はありません。

指標記述子の作成

事前に指標記述子を作成しておく必要はありません。 データポイントが Monitoring に到着したときに、ポイントの指標名、ラベル、ポイントの値を使用してゲージ指標記述子または累積指標記述子を自動的に作成できます。詳しくは、カスタム指標の自動作成をご覧ください。

ただし、独自の指標記述子を作成すると、次のようなメリットがあります。

  • 指標とそのラベルに関する周到なドキュメントを含めることができます。

  • 指標に対する追加の種類と型を指定できます。エージェントがサポートする(種類、型)の組み合わせは、(GAUGE、DOUBLE)と(CUMULATIVE、INT64)のみです。詳しくは、指標の種類と値の型をご覧ください。

  • STRING 以外のラベルの型を指定できます。

定義されていない指標名を使用するデータポイントを Monitoring に書き込むと、そのデータポイントに対して新しい指標記述子が作成されます。これは、指標データを書き込むコードをデバッグする場合に問題になる可能性があります。指標名のスペルを間違えると、誤った指標記述子が作成されます。

手動で作成した指標記述子、または自動的に作成された指標記述子を変更することはできません。たとえば、ラベルを追加または削除することはできません。指標記述子を削除して(指標記述子のすべてのデータが削除されます)、必要な記述子を作成し直すことは可能です。

指標記述子の作成方法については、指標の定義をご覧ください。

コストと制限

collectd 指標に対しては、料金が発生します。これはユーザー定義のものとエージェント指標の両方が対象であり、金額は受信したメトリック データの量に基づいて計算されます。詳細については、Google Cloud のオペレーション スイートの料金設定をご覧ください。

料金とは別に、Cloud Monitoring では GCP プロジェクト内の指標の時系列の数とユーザー定義の指標記述子の数に制限があります。詳細については、割り当てと制限をご覧ください。

作成した指標記述子が不要になった場合は、Monitoring API を使用してその記述子を見つけて削除できます。詳細については、projects.metricDescriptors をご覧ください。

トラブルシューティング

ここでは、Monitoring エージェントの write_log プラグインを構成して、メタデータを含む指標ポイントの全データをダンプ出力する方法を説明します。これを使用すると、変換が必要なポイントを特定し、変換動作が意図したとおりであることを確認できます。

write_log の有効化

write_log プラグインは stackdriver-agent パッケージに含まれています。プラグインを有効にするには次の手順を行います。

  1. root として、次の構成ファイルを編集します。

    /etc/stackdriver/collectd.conf
        
  2. LoadPlugin write_gcm の直後に、次を追加します。

    LoadPlugin write_log
        
  3. <Plugin "write_gcm">…</Plugin> の直後に、次を追加します。

    <Plugin "write_log">
          Format JSON
        </Plugin>
        
  4. <Target "write">…</Target> を検索し、すべての Plugin "write_gcm" の後に次を追加します。

    Plugin "write_log"
        
  5. 変更を保存し、エージェントを再起動します。

    sudo service stackdriver-agent restart
        

この変更により、報告される指標値ごとに 1 行のログが出力されます。このログには、完全な collectd 識別子、メタデータ エントリ、値が含まれます。

write_log の出力

前のステップが正常に完了すると、システムログに write_log の出力が表示されます。

  • Debian ベースの Linux: /var/log/syslog
  • Red Hat ベースの Linux: /var/log/messages

以下のサンプル行は読みやすいように書式設定されています。

Dec  8 15:13:45 test-write-log collectd[1061]: write_log values:#012[{
        "values":[1933524992], "dstypes":["gauge"], "dsnames":["value"],
        "time":1481210025.252, "interval":60.000,
        "host":"test-write-log.c.test-write-log.internal",
        "plugin":"df", "plugin_instance":"udev", "type":"df_complex", "type_instance":"free"}]

    Dec  8 15:13:45 test-write-log collectd[1061]: write_log values:#012[{
        "values":[0], "dstypes":["gauge"], "dsnames":["value"],
        "time":1481210025.252, "interval":60.000,
        "host":"test-write-log.c.test-write-log.internal",
        "plugin":"df", "plugin_instance":"udev", "type":"df_complex", "type_instance":"reserved"}]