読者です 読者をやめる 読者になる 読者になる

ホストのカスタムメトリックを投稿する

ホストごとのメトリックには「loadavg5」や「cpu.user」などエージェントが自動で投稿するメトリックに加えて、任意の値(カスタムメトリック)を定期的にエージェントから投稿できます。

後述のsensuプラグイン互換のフォーマットで計測値を出力するコマンドを登録すると、その出力がデフォルトのメトリックと共にMackerelに送信され、別個のグラフに可視化されるようになります。

公式のプラグイン集も提供しています。公式プラグインの使い方などについては公式プラグイン集を使うを参照してください。

また、公式プラグインで利用している、ヘルパーライブラリである、github.com/mackerelio/go-mackerel-plugin-helper を利用したプラグインの開発方法については、go-mackerel-plugin-helperを利用してカスタムメトリックプラグインを作成する をご覧ください。

設定

エージェントの設定ファイルに、以下のような項目を追加します(例):

[plugin.metrics.vmstat]
command = "ruby /path/to/vmstat-metrics.rb"
  • 項目名: 設定ファイル用のキーで、エージェントからは利用されません。"plugin.metrics." で始まっている必要があり、含まれるドットの数はちょうど2である必要があります。
  • command: エージェントが定期的に実行し、その標準出力を計測結果として使用するコマンドです。コマンドは後述する仕様に沿って動作する必要があります。

注意: PowerShell スクリプトを利用する場合

Windows PowerShell スクリプトの実行ポリシーによっては PowerShell スクリプトで書かれたプラグインが実行できないことがあります。 そのような場合、下記のような バッチファイルを用意してプラグインのコマンドに指定すると実行することが出来ます。

@echo off
cd %~dp0

powershell Set-ExecutionPolicy RemoteSigned
powershell .\sample-plugin.ps1

メトリックの投稿

設定ファイルで指定するコマンドは、標準出力の各行に以下のフォーマットの出力をすることが期待されます(\t はタブ文字です):

{metric name}\t{metric value}\t{epoch seconds}
  • 名前の最後のドットまでが共通するメトリックがひとつのグラフにまとめられ、ホスト詳細で閲覧できます。
  • メトリック名の先頭には自動的に"custom."という文字列が付与されます。
  • メトリック名に使える文字は英数字もしくはハイフン(-)、アンダースコア(_)、ドット(.)のいずれか(/[-a-zA-Z0-9_.]/)です。

例: example.fooexample.bar という名前のメトリックを投稿した場合

custom.example.* と名付けられたグラフがホスト詳細に現れます。このグラフには example.fooexample.bar の系列データが描画されます。

グラフ定義を指定する

ユーザ定義メトリックを投稿することで作られるグラフの表示設定を、実行されるコマンドから JSON で指定できます。

mackerel-agent は起動時に、設定ファイルで指定されたコマンドを MACKEREL_AGENT_PLUGIN_META 環境変数を "1" に設定した状態で起動します。この時、当該コマンドの出力が以下のフォーマットに従っていると、mackerel-agent はプラグインのメタ情報として解釈し、グラフ定義を Mackerel に送信します。これによって、ユーザ定義メトリックの表示設定をウェブ上で行わずにあらかじめ指定できます。

出力は、必ず以下の行から始めてください。最初の行がこの内容でなかった場合、mackerel-agent はこのプラグインがメタ情報を出力しないものとして、グラフ定義の設定を行いません。

# mackerel-agent-plugin

続けて、以下のような設定を JSON フォーマットで出力します。

{
  "graphs": {
    {graph}: {
      "label": GRAPH_LABEL,
      "unit": UNIT_TYPE
      "metrics": [
        {
          "name": METRIC_NAME,
          "label": METRIC_LABEL
        },
        ...
      ]
    },
    GRAPH_NAME: ...
  }
}
…

それぞれの項目は、以下のような意味を持ちます。

項目 説明
graphs.{graph}.label ユーザ定義メトリック {graph}.* に対応するグラフの表示名。{graph} にはドット(.)を含むことができます。
graphs.{graph}.unit ユーザ定義メトリック {graph}.* に対応するグラフの値の種類。可能な値は "float", "integer", "percentage", "bytes", "bytes/sec", "iops" のいずれか。
graphs.{graph}.metrics ユーザ定義メトリック {graph}.* に対応するメトリック定義の配列。

メトリック定義は以下のようなキーを持ちます。

キー 説明
name このメトリックがユーザ定義メトリック {graph}.{name} に対応することを表す。この値にドット(.)を含むことはできません。使用できる文字は英数字もしくはハイフン(-)、アンダースコア(_)のいずれか(/[-a-zA-Z0-9_]/)です。また、ワイルドカード#, * を使用することもできます。詳しくは API仕様(v0)/ グラフ定義の投稿 を参照してください。
labal ユーザ定義メトリック {graph}.{name} に対応する時系列の表示名。
stacked ユーザ定義メトリック {graph}.{name} に対応する時系列を積み上げ表示するかどうか。false なら線分で表示する。

Ruby によるサンプル

6面ダイスおよび20面ダイスの値を Mackerel に投稿するプラグインです。

if ENV['MACKEREL_AGENT_PLUGIN_META'] == '1'
  require 'json'

  meta = {
    :graphs => {
      'super.dice' => {
        :label   => 'My Dice',
        :unit    => 'integer',
        :metrics => [
          {
            :name  => 'd6',
            :label => 'Die (d6)'
          }, {
            :name  => 'd20',
            :label => 'Die (d20)'
          }
        ]
      }
    }
  }

  puts '# mackerel-agent-plugin'
  puts meta.to_json
  exit 0
end

puts [ 'super.dice.d6',  rand( 6)+1, Time.now.to_i ].join("\t")
puts [ 'super.dice.d20', rand(20)+1, Time.now.to_i ].join("\t")

このプラグインで、以下のようなグラフを生成できます。

f:id:mackerelio:20140807163034p:plain

更新履歴

  • 2014-11-17
    • メトリック名に使用できる文字を明記
  • 2014-10-02
    • 「グラフ定義を指定する」のexperimentalを外しました
  • 2014-09-05
    • 設定において「type: "metric" を指定してください。」を削除
    • 公式プラグイン集について記述を追加
  • 2014-08-22
  • 2014-08-07
  • 2014-05-27
    • 設定」の項目名を"sensu.checks."から"plugin.metrics."に変更
    • メトリックの投稿」をメトリック名の先頭に"custom."が付与される仕様に基づいて変更