チェックプラグイン - check-aws-cloudwatch-logs

check-aws-cloudwatch-logs は CloudWatch Logs のロググループの監視を行うプラグインです。CloudWatch Logs のフィルターとパターンの構文で記述した条件に一致するログが検出された場合にアラートが発生します。このプラグインを実行するには CloudWatch Logs の FilterLogEvents API を利用するための設定が必要です。詳細は認証と必要なポリシーについてを参照してください。

監視仕様
指定可能なオプション
- --pattern の記述方法
- State ファイルについて
エージェントへの設定例
- リージョンの指定方法
- 認証と必要なポリシーについて
トラブルシューティング
- Unknown: command timed out が発生する
リポジトリ

監視仕様

check-aws-cloudwatch-logs は初回実行時、現在時刻から 1 分前までのログを監視対象にします。

例: 12:00 に初回実行する場合
- 11:59（startTime）〜 12:00（endTime）が対象

また、実行の度に endTime の時刻を State ファイルに記録し、2 回目以降は現在時刻からその時刻までのログを監視対象にします。

例: 12:00 に初回実行され、12:05 に 2 回目を実行する場合
- 12:00（startTime）〜 12:05（endTime）が対象

なお、前回の実行から 1 時間以上経過している場合は、初回実行と同様に現在時刻から 1 分前までのログが監視対象になります。

指定可能なオプション

オプション	省略形	説明	デフォルト値
--log-group-name		監視対象のロググループを指定
--log-stream-name-prefix		ストリーム名をプレフィックスで絞り込み
--pattern	-p	監視を行うための検索文字列を CloudWatch Logs のフィルターとパターンの構文で記述
--warning-over	-w	検出パターンにマッチする行が指定値を超えたら Warning アラートを発生	0
--critical-over	-c	検出パターンにマッチする行が指定値を超えたら Critical アラートを発生	0
--state-dir	-s	State ファイルの保存先ディレクトリパスを指定	State ファイルについてを参照
--return	-r	パターンにマッチしたログ行をアラートに通知する（最大 1024 文字まで）
--max-retries	-t	CloudWatch Logs への最大問い合わせ試行回数の指定	3
--help	-h	ヘルプを表示

--pattern の記述方法

CloudWatch Logs のフィルターとパターンの構文で記述します。記述方法は AWS のドキュメントを参照してください。

docs.aws.amazon.com

State ファイルについて

--state-dir オプションを指定しない場合、State ファイルは以下のディレクトリに {監視対象ロググループ名}-<hash文字列>.json の形式で保存されます。

mackerel-agent 経由で実行した場合
- /var/tmp/mackerel-agent/check-cloudwatch-logs
手動実行した場合
- /tmp/check-cloudwatch-logs

エージェントへの設定例

CloudWatch Logs のロググループ /aws/lambda/sample_log_group に Error が出力されたことを検知する設定は以下のようになります。

[plugin.checks.aws-cloudwatch-logs-sample]
command = ["check-aws-cloudwatch-logs", "--log-group-name", "/aws/lambda/sample_log_group", "--pattern", "Error"]
env = { AWS_REGION = "ap-northeast-1" }

リージョンの指定方法

リージョンはオプションではなく以下のように環境変数で指定します。AWS_PROFILE 環境変数による名前付きプロファイルなどにも対応しています。

env = { AWS_REGION = "ap-northeast-1" }

認証と必要なポリシーについて

check-aws-cloudwatch-logs は CloudWatch Logs の FilterLogEvents API を利用します。監視対象のロググループに対して以下のアクションを実行可能な IAM ユーザー / ロールの認証情報が利用できるようにしてください。

logs:FilterLogEvents

認証情報の設定は以下の方法に対応しています。

インスタンスプロファイルを使用する（EC2 のインスタンスから監視する場合）
AWS_PROFILE 環境変数による名前付きプロファイルを使用する
プラグイン設定の env = {} で AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY 環境変数を直接記述する

トラブルシューティング

Unknown: command timed out が発生する

流量の多いログストリームやストリーム数の多いロググループでは、プラグインの実行がタイムアウトすることがあります。タイムアウトはプラグインの設定に timeout_seconds を指定することで伸ばせます。ただし、check_interval を超えないように指定する必要があります。詳しくはチェック監視項目を追加するを参照してください。

なお、ログの量が多い場合にタイムアウトになるのは構造上避けられない問題です。対策としてはログの量を減らしたり、サンプリングするなどがあります。それが難しい場合は、流量の多いロググループの監視にも対応する check-aws-cloudwatch-logs-insights の利用を検討してください。

リポジトリ

https://github.com/mackerelio/go-check-plugins/tree/master/check-aws-cloudwatch-logs