エージェントからのユーザー定義の指標

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

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

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

指標の詳細については、次のドキュメントをご覧ください。

注: この機能は、Linux で実行されているエージェントでのみ使用できます。Windows では使用できません。

始める前に

  • 最新の 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 フィルタ チェーンを使用して、指標のメタデータを変更できます。フィルタ チェーンはデータソースのリストを変更できず、ユーザー定義の指標は 1 つのデータソースのみをサポートするため、この機能で使用する collectd 指標には単一のデータソースが必要です。

例

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

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

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

  3. Monitoring エージェントの要件に合わせて、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 type:
      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 user-defined 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 aren't
  # in the list of curated metrics and don't have
  # the user-defined 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

    推奨される命名規則は、ユーザーが指標を追跡しやすい階層形式です。指標タイプではハイフンを使用できません。正確な命名規則については、指標タイプとラベルの命名をご覧ください。

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

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

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

  • 関連付けられている指標記述子のタイプ。

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

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

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

指標記述子の作成

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

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

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

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

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

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

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

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

料金

一般に、Cloud Monitoring システムの指標は無料であり、外部システム、エージェント、またはアプリケーションの指標はそうではありません。課金対象の指標は、取り込まれたバイト数とサンプル数のいずれかによって課金されます。

Cloud Monitoring の料金の詳細については、次のドキュメントをご覧ください。

上限

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

作成した指標記述子が不要になった場合は、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"}]