mackerel-plugin-jsonl

JSON Lines 形式のログからメトリックを生成し、Mackerelに投稿するためのカスタムプラグインです。

インストール方法

mkrを使うと楽です

mkr plugin install --upgrade monitoring-forge/mackerel-plugin-jsonl

基本的な使い方

./mackerel-plugin-jsonl \
	--key-name count \
	--json-key foo.bar \
	--aggregator count \
	--log-file /path/to/your.log \
	--prefix custom.jsonl

複数のキーや集計方法を指定する場合は、--key-name, --json-key, --aggregator を同じ数だけ指定してください。

コマンドオプション

オプション	短縮形	説明
`--version`	`-v`	バージョン情報を表示します。
`--key-name`	`-k`	メトリック名に使用するキー名を指定します（必須）。複数指定できます。
`--json-key`	`-j`	ログから値を抽出するJSONキーを指定します（必須）。パイプ区切りで変換関数を指定できます。複数指定できます。
`--aggregator`	`-a`	集計方法を指定します（必須）。`count`、`sum`、`group_by`、`group_by_with_percentage`、`percentile`、`percentile(...)` が指定可能です。複数指定できます。
`--log-file`	`-l`	読み込むJSON Lines形式のログファイルパスを指定します（必須）。
`--prefix`		Mackerelメトリック名のプレフィックスを指定します（必須）。
`--filter`		ログ行をフィルタする文字列を指定します。指定した文字列を含む行のみ対象となります。
`--ignore`		ログ行を除外する文字列を指定します。指定した文字列を含む行は無視されます。
`--skip-until-json`		JSONの `{` まで読み飛ばします。プレーンテキストのヘッダーが含まれるJSONログで利用します。
`--per-second`		1秒あたりの値で出力します。未指定時は1分あたりの値で出力されます。
`--log-archive-dir`		ログのローテート済みアーカイブディレクトリを指定します。
`--verbose`		詳細なログを標準エラーに出力します。

mackerel-agent.conf 設定例

[plugin.metrics.jsonl]
command = "/path/to/mackerel-plugin-jsonl --key-name count --json-key foo.bar --aggregator count --log-file /var/log/app.log --prefix custom.jsonl"

aggregatorの種類と説明

--aggregator には以下の種類を指定できます。

count : 対象となるキーが存在する行をカウントします
- 例: json.total.count 80000.000000 1760281381
sum : 指定した数値キーを合計します
- 例: json.bytes_sent.sum 75000.000000 1760281381
group_by : 指定したキーの値ごとに件数を集計します。
- 例: json.status.2xx 24769.733333 1760281381
group_by_with_percentage : group_byの各値ごとの割合（%）も出力します。
- 例: json.status_percentage.5xx 23.139667 1760281381
percentile : 指定した数値キーの平均値とパーセンタイル（mean, p90, p95, p99）を出力します。
- 例: json.latency.p95 0.030000 1760281381

複数のaggregatorを同時に指定することで、複数のメトリクスを一度に出力できます。

percentile の出力項目をカスタマイズする

percentile(...) の引数に、出力したい統計値・パーセンタイルをカンマ区切りで指定できます。計算には sampdo を使用します。

./mackerel-plugin-jsonl \
  --key-name latency \
  --json-key reqtime \
  --aggregator 'percentile("max","min","mean","50","70",90,99.9)' \
  --log-file /path/to/your.log \
  --prefix json

統計値は max（最大値）、min（最小値）、mean（平均値）を指定できます。
パーセンタイルは 0 以上 100 以下の数値で、小数も指定できます。
引数は引用符あり・なしのどちらでも指定できます。
統計値の出力名はそのまま max、min、mean です。数値は先頭に p を付け、小数点を _ に変換します（99.9 → p99_9）。

上記の例では、json.latency.max、json.latency.min、json.latency.mean、json.latency.p50、json.latency.p70、json.latency.p90、json.latency.p99_9 のみを指定順に出力します。

従来の --aggregator percentile は引き続き mean、p90、p95、p99 を出力します。percentile() のような空の指定、未対応の統計名、範囲外の数値はエラーになります。対象データがない場合は出力しません。

json-keyの変換関数

--json-key にはパイプ（|）区切りで変換関数を指定できます。

例: foo.bar|tolower|replace('a','b')|trimspace

利用可能な変換関数

関数	説明	利用できる aggregator
`tolower`	値を小文字に変換します。	`group_by`, `group_by_with_percentage`
`toupper`	値を大文字に変換します。	`group_by`, `group_by_with_percentage`
`trimspace`	値の前後の空白を除去します。	`group_by`, `group_by_with_percentage`
`replace('pattern','repl')`	正規表現で値を置換します。	`group_by`, `group_by_with_percentage`
`have('key1','key2','key3')`	集計結果に指定したキーをあらかじめ `0` で追加します。集計した値がない場合でもメトリックを出力できます。	`group_by`, `group_by_with_percentage`
`multiply(factor)`	数値に指定した係数を掛けます。	`count`, `sum`, `group_by`, `group_by_with_percentage`, `percentile`

注意事項

数値変換関数（multiply）は、すべての aggregator で利用できます。
文字列変換関数（tolower、toupper、trimspace、replace）と have() は group_by および group_by_with_percentage のみで利用できます。
multiply() は count では件数、group_by/group_by_with_percentage では各値の件数、percentile では各統計値に係数を掛けます。

例:

--json-key "user.name|trimspace|tolower"
--json-key "message|replace('error','warn')"
--json-key "status|tolower|have('2xx','3xx','4xx','5xx')"