チェックプラグイン - check-log

check-logはアプリケーションやミドルウェアなどのサーバー上のログファイルの監視を行うプラグインです。

監視対象のログファイルの出力差分に対して正規表現によるパターンマッチングを行い、アラートを発生させます。

監視仕様

監視対象のログ

check-log プラグインは実行のたびに監視対象ファイルの読み込んだバイト数と inode番号（Linuxのみ）を Stateファイル に記録し、次に実行する際は前回からの差分のみを監視する仕組みとなっています。

対応するローテーション方式について

check-log プラグインは、監視対象となるログのローテーション方式として create（ファイル移動後、新たに同名ファイルを作成する）方式に対応しています。copytruncate（ファイルコピー後、コピー元ファイルの中身を削除する）方式の場合、ローテーションの際にコピーされたファイルへの追跡は行わず、内容が削除された元ファイルに対する先頭からの確認のみ行います。

指定可能なオプション

オプション 省略形 説明 初期値
--file -f 監視対象ファイルのパスを指定（glob形式での指定可）
--pattern -p 検出したいパターンを正規表現で指定 *1
--exclude -E 検出から除外するパターンを正規表現で指定 *1
--warning-over -w 検出パターンにマッチする行数が指定値を超えたらWarningアラートを発生
--critical-over -c 検出パターンにマッチする行数が指定値を超えたらCriticalアラートを発生
--warning-level 検出パターンで抽出した数値が指定値を超えたらWarningアラートを発生
--critical-level 検出パターンで抽出した数値が指定値を超えたらCriticalアラートを発生
--return -r パターンにマッチしたログ行をアラートで通知する *2
--search-in-directory 監視対象ファイルがあるディレクトリパスを指定（Windows環境において--file-patternと併用）
--file-pattern -F 監視対象ファイルを正規表現で指定
--icase -i 大小文字を区別せずにマッチングを行う
--state-dir -s Stateファイルの保存先ディレクトリパスを指定
--no-state Stateファイルを使用せず全てのログを対象とする
--encoding 監視対象ファイルの文字エンコーディングを指定
--missing 監視対象ファイルが存在しなかった場合のアラートレベルを指定 UNKNOWN
--check-first ファイルの初回チェック時に内容のチェックを行う *3
--suppress-pattern 検出パターンをホスト詳細画面に表示しない

Stateファイルについて

--state-dirオプションを指定しない場合、OSごとに以下所定の保存先の配下に監視対象のログファイルと同じディレクトリ階層を作り、{監視対象ファイル}-<hash文字列>.jsonの形式でファイルを作成します。たとえば/var/log配下のログを監視対象にしている場合は、/var/tmp/mackerel-agent/check-log/var/logというディレクトリ配下に保存されます。

  • Linuxの場合
    • mackerel-agent 経由で実行した場合
      • /var/tmp/mackerel-agent/check-log
    • 手動実行した場合
      • /tmp/check-log
  • Windowsの場合
    • mackerel-agent 経由で実行した場合
      • C:\Windows\Temp\check-log
    • 手動実行した場合
      • ログインユーザの Temp フォルダ配下の check-log フォルダ（Temp フォルダの場所は Windows 環境変数の TEMP を確認）

エージェントへの設定例

Linuxサーバーでの監視例

/var/log/access.log に ERROR という文字列を含むログが出力されたことを検知する設定は以下のようになります。

[plugin.checks.access_log]
command = ["check-log", "--file", "/var/log/access.log", "--pattern", "ERROR", "--return"]

上記設定をターミナルなどから直接実行して確認するには、以下のように実行してください。

check-log --file /var/log/access.log --pattern "ERROR" --return --no-state

Windowsサーバーでの監視例

C:\log\access.log に ERROR という文字列を含むログが出力されたことを検知する設定は以下のようになります。Windows 環境のパス区切り文字 \ は本来 1 つですが、mackerel-agent.conf に設定する際は 2 つ記述する必要があります。

[plugin.checks.access_log]
command = ["check-log", "--file", "C:\\log\\access.log", "--pattern", "ERROR", "--return"]

上記設定をコマンドプロンプトなどから直接実行して確認するには、以下のように実行してください。

check-log --file "C:\log\access.log" --pattern "ERROR" --return --no-state

Tips

AND条件で複数のパターンにマッチする場合にアラートを発報する

--pattern や --exclude を複数指定すると AND 条件となり、指定したすべての条件に一致するログをアラートの対象にできます。

以下は PRODUCTION と ERROR という文字列を含むログが検出された場合にアラートが発生します。

[plugin.checks.access_log]
command = ["check-log", "--file", "/var/log/access.log", "--pattern", "PRODUCTION", "--pattern", "ERROR", "--return"]

OR条件で何れかにマッチする場合にアラートを発報する

--pattern や --exclude にパイプ | 区切りで複数の条件を指定した場合は OR 条件となり、指定したいずれかの条件に一致するログをアラートの対象にできます。

以下は FATAL もしくは ERROR という文字列を含むログが検出された場合にアラートが発生します。

[plugin.checks.access_log]
command = ["check-log", "--file", "/var/log/access.log", "--pattern", "FATAL|ERROR", "--return"]

正規表現のメタ文字を文字列として扱う

--pattern や --exclude において、正規表現のメタ文字（[] などの特殊な意味を持つ文字）を単純な文字列として扱いたい場合は、メタ文字に対してエスケープ処理（メタ文字の前にエスケープ文字 \ を記述する）が必要です。

以下は [ERROR] という文字列を含むログを検出する場合の設定例です。

--pattern の引数をシングルクォーテーション ' で囲む場合はエスケープ文字を 1 つ記述します。

command = ['check-log', '--file', '/var/log/access.log', '--pattern', '\[ERROR\]', '--return']

--pattern の引数をダブルクォーテーション " で囲む場合はエスケープ文字を 2 つ記述します。

command = ["check-log", "--file", "/var/log/access.log", "--pattern", "\\[ERROR\\]", "--return"]

--pattern の引数をダブルクォーテーション " で囲む場合に、ダブルクォーテーション " を検出条件の文字に指定したい場合は、エスケープ文字を 3 つ記述します。以下の例では "ERROR" という文字列を含むログを検出します。

command = ["check-log", "--file", "/var/log/access.log", "--pattern", "\\\"ERROR\\\"", "--return"]

Windows 環境において監視対象ファイルを正規表現で指定する場合の注意点

Windows 環境において監視対象ファイルの指定に --file-pattern による正規表現を用いる場合、ディレクトリの区切り文字 \ と正規表現のエスケープ処理との競合を回避するために、--search-in-directory オプションを併用してください。

たとえば C:\log\access.log.{yyyy}-{mm}-{dd}のような形式のファイルを正規表現で指定する場合は以下のようになります。なお、ディレクトリパスを正規表現で指定することはできません。ディレクトリごとに監視ルールを設定してください。

[plugin.checks.access_log]
command = ["check-log", "--search-in-directory", "C:\\log\\", "--file-pattern", "access.log.\\d{4}-\\d{2}-\\d{2}", "--pattern", "ERROR", "--return"]

トラブルシューティング

条件にマッチするログ行が出力されたのに検知されない

以下のようなケースが多く見受けられますので、設定などの見直しをお願いします。

  • --check-first オプションが指定されているか確認してください。
    • 未指定の場合、監視対象ファイルの初回チェック時は内容のチェックは行いません。
    • ログローテーションなどでファイルが切り替わった際の初回のチェック時も同様です。
  • --pattern オプションに指定した検出パターンが正しいか確認してください。
    • 検出パターンは正規表現として評価されるため、半角カッコなど正規表現のメタ文字として解釈される文字を含む場合はエスケープをしてください。
    • 正規表現のメタ文字を文字列として扱う もあわせてご覧ください。
  • ローテーション方式としてcreate方式が採用されているか確認してください。
    • copytruncate方式でローテーションされたログでは、ローテーション前にcheck-logが実行されてからローテーションが行われるまでに追記されたログの確認が行えません。
  • 該当するログ行が改行されているか確認してください。
    • 行の末尾に改行コードがないログは検出できません。

また、ローテーション後にcheck-logを実行した際のファイルサイズがローテーション前に実行した際のファイルサイズよりも大きい場合、ローテーションを検知できず、ローテーション前にcheck-logが確認したサイズまでに記載されたログに対して検知が行えません。

LOG UNKNOWN: unexpected end of JSON input のアラートが発報される

check-logプラグインが監視状態を記録しているStateファイルが破損している可能性があります。

Stateファイルを削除もしくはリネームすることで解消が見込めますので、Stateファイルについて を参考にご対応ください。 またこの対応を行うと監視状態がリセットされるため、初回実行時と同様の挙動となります。

リポジトリ

https://github.com/mackerelio/go-check-plugins/tree/master/check-log