mackerel-agent仕様

この項ではmackerel-agentの最新バージョンについて解説します。

Usage

mackerel-agent [-conf <config-file>] [options]

概要

mackerel-agent はフォアグラウンドで動作し、

  • ホストの情報をMackerelに登録、
  • ホスト上で定期的(1分毎)にリソース情報を収集し、Mackerelに投稿、
  • また、定期的(1時間毎)にホストの情報を更新します。

投稿されたホスト情報、リソース情報はMackerelのウェブインターフェースで確認できます。

設定ファイル

設定ファイルはデフォルトで /etc/mackerel-agent/mackerel-agent.conf が参照されます。

内容はTOMLで記述し、例として以下のようになります。

apikey = "APIKEY"
pidfile = "/path/to/pidfile"
root = "/var/lib/mackerel-agent"

verbose = false

display_name = "My Host"

roles = [ "My-Service:app", "Another-Service:db" ]

include = "/etc/mackerel-agent/conf.d/*.conf"

[host_status]
on_start = "working"
on_stop  = "poweroff"

[filesystems]
ignore = "/dev/ram.*"
use_mountpoint = true

[plugin.metrics.vmstat]
command = "ruby /etc/sensu/plugins/system/vmstat-metrics.rb"

[plugin.checks.ssh]
command = "ruby /path/to/check-ssh.rb"

[plugin.metadata.packages]
command = "perl /path/to/packages.pl"

設定ファイルはエージェントの起動時に読み込まれるので、編集後はエージェントを再起動する必要があります。

APIKEY以外の設定項目はオプショナルなので、デフォルト値のままでよい場合は内容は空でかまいません。

他の設定ファイルを読み込む

設定ファイル中の include 設定項目で、他の設定ファイルを読み込めます。

  • /etc/mackerel-agent/conf.d/*.conf のように、ファイルグロブを指定できます。
  • 文字列、真偽値、配列の設定項目(verboseroles)に関しては、後から読み込まれた設定ファイルに値が存在する場合、上書きされます。
  • 複数の設定ファイルがマッチするとき、それらが読み込まれる順序は不定です。
  • 読み込まれた設定ファイル中の include 設定項目は、無視されます。

サービス、ロールの設定

エージェントの起動時オプションまたは設定ファイルによる指定で、ホストのサービス、ロールを設定できます。指定されたサービス、ロールが存在しない場合、新たに作成されます。 不正な文字列が含まれていると紐付けされませんので、意図通りに動作しない場合は指定内容を確認してください。

例: My-ServiceサービスのappロールおよびAnother-Serviceサービスのdbロールを紐付けたい場合

設定ファイルで、roles 設定項目を指定します。(TOML の配列)

# /etc/mackerel-agent/mackerel-agent.conf
roles = [ "My-Service:app", "Another-Service:db" ]

もしくは

mackerel-agent -role=My-Service:app -role=Another-Service:db …

この設定・紐付けはエージェント起動時に処理されます。また、ウェブ側での変更がエージェントの設定ファイルに同期されることはありません。

管理名の設定

設定ファイルによる指定で、ホストに対して任意の別名を設定することが出来ます。すでに管理名が設定されているホストの場合は新しい名前に更新されます。 また、設定ファイルから指定を削除した場合も管理名は設定されたままとなります。ホストの設定ページから削除することが出来ます。

# /etc/mackerel-agent/mackerel-agent.conf
display_name = "My Host"

HTTP Proxy経由で接続する

以下のようにURLを指定することでHTTP Proxy を設定することができます。

# /etc/mackerel-agent/mackerel-agent.conf
http_proxy = "http://localhost:8080"

また、環境変数 HTTP_PROXY にも対応しています。例えば、次のように指定することで、HTTP Proxy経由のアクセスにすることができます。

% HTTP_PROXY=http://localhost:8080 mackerel-agent

yum/rpmの場合 /etc/sysconfig/mackerel-agent 、apt/debの場合は /etc/default/mackerel-agent ファイルに環境変数の設定を追記することでmackerel-agentに適用させることができます。例えば次のように指定します。

HTTP_PROXY="http://localhost:8080/"

ステータスの設定

設定ファイルによる指定で、ホストのステータスを設定できます。エージェントの起動時、終了時で別々のステータスを指定することが出来ます。

以下のように指定することで、エージェントが起動したときに、ホストのステータスが working に設定され、エージェントが正常終了した際に poweroff に設定されます。

# /etc/mackerel-agent/mackerel-agent.conf
[host_status]
on_start = "working"
on_stop  = "poweroff"

指定できるステータスは、working standby maintenance poweroff です。

特定のファイルシステムを除外

設定ファイルによる指定で、特定のファイルシステムからのメトリック収集を除外できます。

以下のように正規表現を用いて指定することで、指定されたファイルシステムからのメトリックは収集されなくなります。

# /etc/mackerel-agent/mackerel-agent.conf
[filesystems]
ignore = "/dev/ram.*"

マウントポイントごとのfilesystemメトリックの取得

設定ファイルに以下のように指定することで、マウントポイントごとに filesystem メトリックを取得することが可能です。

# /etc/mackerel-agent/mackerel-agent.conf
[filesystems]
use_mountpoint = true

ユーザ定義のメトリックの投稿

設定ファイルの「plugin.metrics.*」セクションで任意のメトリックを登録し、投稿できます。詳しくはユーザ定義のメトリックを投稿するをご覧ください。

チェック監視結果の投稿

設定ファイルの「plugin.checks.*」セクションで任意のチェック監視用の実行ファイルやスクリプトを登録し、実行結果を投稿することができます。詳しくはチェック監視項目を追加するをご覧ください。

メタデータの投稿

設定ファイルの「plugin.metadata.*」セクションで任意のJSONデータをホストに登録することができます。詳しくはメタデータを利用するをご覧ください。

診断モード

エージェントの起動時オプションまたは設定ファイルで有効にすることで、エージェント自身のメモリ使用状況を収集しカスタムメトリックとして投稿します。

# /etc/mackerel-agent/mackerel-agent.conf
diagnostic = true

もしくは

mackerel-agent -diagnostic

以下のメトリックの収集が行われます。

  • custom.agent.memory.alloc
  • custom.agent.memory.sys
  • custom.agent.memory.heapAlloc
  • custom.agent.memory.heapSys

詳しくはhttps://golang.org/pkg/runtime/#MemStatsをご参照ください。

起動オプション

以下の起動オプションが指定できます。設定ファイルを同じ項目を指定した場合、起動オプションが優先されます。

  • -apikey=API_KEY Mackerelのウェブ上で確認できるAPIキーです。この値で、ホストがどのオーガニゼーションに所属するかを識別します。(非推奨。バージョン0.5.1より設定ファイルに記述することを推奨しています。)
  • -conf=/etc/mackerel-agent/mackerel-agent.conf 設定ファイルへのパスです。未指定の場合、デフォルトで/etc/mackerel-agent/mackerel-agent.confが読み込まれます。
  • -pidfile=/var/run/mackerel-agent.pid PIDファイルへのパスです。
  • -root=/var/lib/mackerel-agent mackerel-agentの状態を記録するディレクトリへのパスです。現在はホストを識別するidファイルのみが置かれます。
  • -role=<service>:<role> ホストに割り当てるロールおよびサービスを指定します。
  • -once 一度だけメトリックの収集を実行して標準出力に表示します。投稿は行われません。
  • -diagnostic エージェント自身のメトリックを収集して投稿します。

FAQ

エージェントはどうやってホストを判別していますか?

/var/lib/mackerel-agent/id にホストIDが保存されており、このIDでどのホストか判別します。ホスト名は判別に利用されません。(設定ファイルは起動オプションでrootを変更している場合、そのroot以下にidファイルが作成されます。)

エージェントが起動しません

/var/lib/mackerel-agent/id に正しくないIDが保存されている場合、正しく起動しません。/var/lib/mackerel-agent/id を削除してから起動してみてください。(新規ホストとして認識されます)(設定ファイルは起動オプションでrootを変更している場合、そのroot以下にidファイルが作成されます。)

サブコマンド

エージェントはいくつかのサブコマンドを持ちます。

retire

mackerel-agent retire [-conf <config-file>] [-force] [options]

ホストを退役させます。実行時に確認プロンプトが表示されます。 -force オプションをつけることで、確認プロンプトを出さずに退役処理を行うことができます。

configtest

mackerel-agent configtest

設定ファイル( mackerel-agent.conf )のシンタックスチェックをおこなうことができます。

initスクリプト用設定ファイル

yum/rpmの場合 /etc/sysconfig/mackerel-agent 、apt/debの場合は /etc/default/mackerel-agent ファイルに環境変数の設定を追記することでmackerel-agentに適用させることができます。以下の様な変数が設定可能です。

OTHER_OPTS

mackerel-agentに追加したいオプションを指定します。例えば OTHER_OPTS="-diagnostic -verbose" のように指定すると診断モードが有効になるとともにDEBUGログが出力されます

AUTO_RETIREMENT

この変数に0以外の文字列を指定すると、OSシャットダウン時(正確には /etc/init.d/mackerel-agent stop 時)にホストが自動的に退役されます。

注意 手動で /etc/init.d/mackerel-agent stop を打った場合でもこの指定がされていた場合にはホストは退役されてしまいます。エージェントのバージョンアップ時など、エージェントをstop/startさせたい場合には、/etc/init.d/mackerel-agent reload を使うようにして下さい。