mackerel metric plugin for CPU/FDs/Memory usage of each linux process.
各LinuxプロセスのCPU・ファイルディスクリプタ・メモリ使用量を監視し、mackerelにメトリクスを送信するためのプラグインです。
- プロセス単位での詳細なメトリクス取得: PIDを指定することで、個々のプロセスの資源使用状況を詳細に監視できます
- 軽量な設計:
procfsを直接参照する仕組みにより、最小限のオーバーヘッドでメトリクスを取得できます - ファイルディスクリプタの監視: 開いているFD数とシステム制限値の割合を追跡できます
- メモリ使用量の可視化: プロセスが使用するメモリ量とシステム全体のメモリに対する割合を監視できます
mkr コマンドがインストールされている場合、次のコマンドでプラグインをインストールできます：
mkr plugin install monitoring-forge/mackerel-plugin-linux-process-statusGitHub Releasesページ から、お使いの環境に適したバイナリをダウンロードして使用してください。
Usage:
mackerel-plugin-linux-process-status [OPTIONS]
Application options:
-p, --pid= PID 監視対象のプロセスのPID
--key-prefix= メトリクスキーのプレフィックス
-v, --version バージョン情報を表示
Help options:
-h, --help ヘルプメッセージを表示
監視対象のプロセスのPIDを指定して実行します。--key-prefix オプションでメトリクスキーのプレフィックスを指定できます（省略不可）。
./mackerel-plugin-linux-process-status --key-prefix postgres -p 54321PostgreSQLプロセス（PID: 54321）を監視する場合：
./mackerel-plugin-linux-process-status --key-prefix postgres -p 54321出力例：
process-status.fds_postgres.count 6 1606457504
process-status.fds_postgres.max 65535 1606457504
process-status.fds_usage_postgres.percentage 0.009155 1606457504
process-status.cpu_postgres.percentage 0.000000 1606457504
process-status.mem_postgres.used 2924544 1606457504
process-status.mem_postgres.max 469286912 1606457504
process-status.mem_usage_postgres.percentage 0.623189 1606457504
注意: 初回実行時はCPU使用率のメトリクスは出力されません。2回目以降の実行で、前回の状態との差分からCPU使用率が計算されます。
PID が起動のたびに変わるサービスを監視する場合、pgrep や pidof などのコマンドと組み合わせて PID を動的に取得できます。
プロセス名に一致する最初の PID を取得します：
./mackerel-plugin-linux-process-status --key-prefix postgres -p "$(pgrep -f postgres)"注意:
pgrepが複数の PID を返す場合、このプラグインは単一の PID のみを受け付けるため、-n（最新のプロセス）や-o（最も古いプロセス）などのオプションで1つに絞るか、headを使ってください。./mackerel-plugin-linux-process-status --key-prefix postgres -p "$(pgrep -n postgres)" ./mackerel-plugin-linux-process-status --key-prefix postgres -p "$(pgrep postgres | head -n 1)"
pidof は実行ファイル名に一致する PID を返します：
./mackerel-plugin-linux-process-status --key-prefix nginx -p "$(pidof nginx)"pidof も複数の PID を返すことがあるため、単一に絞る場合は以下のようにします：
./mackerel-plugin-linux-process-status --key-prefix nginx -p "$(pidof nginx | awk '{print $1}')"mackerel-agent では、シェルのコマンド置換を利用して PID を動的に渡せます。
[plugin.metrics.postgres]
command = "./mackerel-plugin-linux-process-status --key-prefix postgres -p $(pgrep -n postgres)"
[plugin.metrics.nginx]
command = "./mackerel-plugin-linux-process-status --key-prefix nginx -p $(pidof nginx | awk '{print $1}')"プラグインは以下のメトリクスを出力します。各メトリクスにはタイムスタンプ（UNIX時間）が最後に付与されます。
| メトリクス名 | 説明 | 単位 |
|---|---|---|
process-status.fds_{prefix}.count |
プロセスが開いているファイルディスクリプタの数 | 整数 |
process-status.fds_{prefix}.max |
システムが許可する最大ファイルディスクリプタ数 | 整数 |
process-status.fds_usage_{prefix}.percentage |
使用可能なファイルディスクリプタの使用率（%） | 割合（%） |
使用例:
countが6で、maxが65535の場合、使用率percentageは約0.009%になります- 使用率が上昇傾向にある場合は、ファイルディスクリプドリークの兆候である可能性があります
| メトリクス名 | 説明 | 単位 |
|---|---|---|
process-status.cpu_{prefix}.percentage |
プロセスのCPU使用率（ユーザー空間＋システム空間） | 割合（%） |
計算方法:
- プラグインは2回以上の実行間で、プロセスのCPU時間とシステム全体のCPU時間の差分から使用率を計算します
- この仕組みにより、正確なCPU使用率の割合を取得できます
| メトリクス名 | 説明 | 単位 |
|---|---|---|
process-status.mem_{prefix}.used |
プロセスが使用しているメモリ量（RSS: Resident Set Size） | バイト |
process-status.mem_{prefix}.max |
システム全体の総メモリ量（MemTotal） | バイト |
process-status.mem_usage_{prefix}.percentage |
プロセスのメモリ使用量占总メモリの割合 | 割合（%） |
注意:
usedはプロセスのRSS（実物理メモリ使用量）を表しますmaxはシステム全体の物理メモリ量（/proc/meminfoのMemTotal）を使用します- cgroup制限には対応していません。コンテナ環境では注意が必要です
- OS: Linuxのみ（Windows/macOSでは動作しません）
- カーネル: procfsが使用可能な環境（通常のリナックスディストリビューションで対応）
- Go: 1.25.0以上（ソースビルドする場合）
- I/O待機場所含むCPU時間の監視には対応していません
- CPU steal time（仮想化環境でのハイパーバイザによるCPU時間の占有）には対応していません
- Linuxのみの対応です。WindowsやmacOSでは動作しません
- cgroup（コンテナ）の制限には対応していません。
MemTotalを最大値として使用するため、コンテナ環境では正確なメモリ使用率が表示されない場合があります - 初回実行時はCPU使用率のメトリクスは出力されません。2回目以降の実行で差分計算が行われます
- プラグインのワークディレクトリにステータスファイル（JSON）が保存されます。複数プロセスで同じ
--key-prefixを指定した場合、ファイルが上書きされる可能性があります
- プラグインは
/proc/{pid}を直接読み取るため、実行ユーザーに適切な権限が必要です - 通常、
rootまたは対象プロセスと同じユーザーで実行する必要があります