mackerel-plugin-axslog

mackerel-plugin-axslog

mackerel-plugin-axslog は、Nginx などのアクセスログを読み取り、Mackerel のカスタムメトリクスとして送信するプラグインです。JSON および LTSV 形式に対応し、応答時間・ステータスコードのフィールド名をログ形式に合わせて指定できます。

mackerel-plugin-accesslog の代替として、高速なログ解析を目的にしています。

日本語の紹介記事: https://kazeburo.hatenablog.com/entry/2019/04/05/093000

インストール

Mackerel のプラグイン管理コマンド mkr を使用します。

mkr plugin install monitoring-forge/mackerel-plugin-axslog

リリースページからバイナリを直接ダウンロードして配置する方法も利用できます。

前提となるログ形式

各ログ行には、応答時間と HTTP ステータスコードが含まれている必要があります。デフォルトでは次のキーを読み取ります。

LTSV の例です。

time:2026-08-28T12:00:00+09:00\tstatus:200\tptime:0.123\trequest:/api/items

JSON の例です。

{"time":"2026-08-28T12:00:00+09:00","status":200,"ptime":0.123,"request":"/api/items"}

値が空または - の行、応答時間またはステータスコードを取得できない行は集計対象外です。

使い方

LTSV ログを直接読み取る例です。

mackerel-plugin-axslog \
  --logfile /var/log/nginx/access.log \
  --key-prefix nginx

応答時間のキーが request_time の場合は --ptime-key を指定します。

mackerel-plugin-axslog \
  --logfile /var/log/nginx/access.log \
  --key-prefix nginx \
  --ptime-key request_time

JSON ログを読む場合は --format json を指定します。

mackerel-plugin-axslog \
  --logfile /var/log/nginx/access.json.log \
  --format json \
  --key-prefix nginx_json \
  --ptime-key request_time

複数のログを合算するには、--logfile にカンマ区切りで指定します。

mackerel-plugin-axslog \
  --logfile /var/log/nginx/access.log,/var/log/nginx/api.log \
  --key-prefix nginx

複数の候補からステータスコードを取得したい場合は、--status-key を繰り返して指定します。指定順で最初に見つかったキーを使います。

mackerel-plugin-axslog \
  --logfile /var/log/nginx/access.log \
  --key-prefix nginx \
  --status-key status \
  --status-key upstream_status

主なオプション

mackerel-agent での設定

/etc/mackerel-agent/mackerel-agent.conf にプラグイン定義を追加します。command には、command -v mackerel-plugin-axslog で確認した絶対パスを指定してください。

[plugin.metrics.axslog]
command = "/usr/local/bin/mackerel-plugin-axslog --logfile /var/log/nginx/access.log --key-prefix nginx --ptime-key request_time"

JSON ログの場合の例です。

[plugin.metrics.axslog-json]
command = "/usr/local/bin/mackerel-plugin-axslog --logfile /var/log/nginx/access.json.log --format json --key-prefix nginx_json --ptime-key request_time"

設定後にエージェントを再起動します。

sudo systemctl restart mackerel-agent

macOS などでサービス管理方法が異なる場合は、その環境の手順で mackerel-agent を再起動してください。エージェントの実行ユーザーがログファイルを読み取れることも確認してください。

プラグインは読み取り済み位置を Mackerel プラグインの作業ディレクトリに保持するため、通常は新しく追記されたログ行だけを処理します。ログローテーション後も継続して監視できるよう、ログファイルへの読み取り権限を維持してください。

動作速度とリソース利用

LTSV は専用パーサー、JSON は必要なキーを直接検索するパーサーで処理し、応答時間の集計値とステータス別カウンターのみを保持します。全ログを構造体として展開しないため、大きなアクセスログを定期収集する用途を想定した実装です。

参考値として、100 万行(240MB)のログを 0.1 秒強で読み取れます。実際の処理時間は、ログ形式・各行のサイズ・フィルターの有無・ディスク性能などの実行環境により変動します。

初回実行時や位置情報が失われた場合は、未処理範囲を読み取るため、ログ量に応じて CPU・I/O を使用します。読み取り量を制限したい場合は --max-read-size を設定してください。複数ログは並列に処理しますが、レイテンシのパーセンタイル計算では対象ログ行の応答時間を保持するため、非常に大きな未処理区間ではメモリ使用量にも注意してください。

出力されるメトリクス

--key-prefix nginx を指定した場合、以下のメトリクスが出力されます。応答時間の単位はログに記録された値に従います。Nginx の $request_time を使う場合は秒です。

access_num と access_total は、今回処理したログの時間幅から算出するレートです。処理対象がない場合、レイテンシおよび割合のメトリクスは出力されません。

ライセンス

MIT License で提供しています。