こんにちは。 Mackerel チームの 
id:astj です。
本日、Amazon CloudWatch Logs 上のログを監視するチェック監視プラグイン check-aws-cloudwatch-logs-insights のベータ版を GitHub 上で公開します。これは、 CloudWatch Logs Insights の API を利用することで、流量の多いロググループに対してもログ監視を実現できるようにすることを意図したプラグインです。
Amazon CloudWatch Logs 上のログを監視する Mackerel の公式チェックプラグインは check-aws-cloudwatch-logs *1 が既に存在します。 check-aws-cloudwatch-logs は流量の少ないロググループに対しては十分に動作しますが、流量の多いロググループを対象とした場合はログの読み込みに時間がかかり、場合によってはタイムアウトにより正常に監視が行えないことがありました。 この check-aws-cloudwatch-logs-insights は、 CloudWatch Logs Insights の API を利用することで、流量の多いロググループであってもログ監視を行えるようにするためのものです。
2021/06/23 追記
本プラグインは、 2021/06/23 に正式版をリリースしました。正式版についての情報は、正式版のリリース告知をご覧ください。
利用方法
check-aws-cloudwatch-logs-insights は以下の手順で利用することができます。
プラグインの入手
プラグインの入手には、 mkr plugin install を利用する方法と、 GitHub 上から直接ダウンロードする方法があります。
mkr plugin install を利用する場合、以下のコマンドで /opt/mackerel-agent/plugins/bin/ 以下に v0.0.2 の実行ファイルが展開されます。（最新版は GitHub 上でご確認ください）
sudo mkr plugin install mackerelio-labs/check-aws-cloudwatch-logs-insights@v0.0.2
また、 mkr のインストール機能を利用せずに実行ファイルを GitHub Releases からダウンロードすることもできます。 お使いの OS / アーキテクチャにあった物をダウンロードしてください。
Releases · mackerelio/check-aws-cloudwatch-logs-insights · GitHub
コマンドの利用方法
コマンドの利用方法は README をご確認ください。
ログを絞り込むための --filter オプションは CloudWatch Logs Insights query syntax - Amazon CloudWatch Logs にあるクエリが利用できます。
また、このプラグインは AWS の API を利用するため、監視対象のロググループに対して logs:GetQueryResults logs:StartQuery logs:StopQuery の3つのアクションが実行可能な IAM ユーザー / ロールの認証情報が利用できるようにしてください。 EC2 のインスタンスプロファイルや、 AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY 環境変数によるアクセスキーの直接指定、 AWS_PROFILE 環境変数による名前付きプロファイルの利用のいずれにも対応しています。
以下はいくつかのサンプルです。
/aws/lambda/some-lambda-function ログストリームに、 "ERROR" という文字列を含むログが1件以上見つかった時に WARNING 、10件以上見つかった時に CRITICAL の監視ステータスになる例です。
% AWS_REGION=ap-northeast-1 /path/to/check-aws-cloudwatch-logs-insights --log-group-name=/aws/lambda/some-lambda-function --filter='filter @message like /ERROR/' -warning-over 1 -critical-over 10
上記と同様の監視設定を mackerel-agent の設定ファイルに記述する場合の設定内容です。
[plugin.checks.aws-cloudwatch-logs-insights-sample]
command = ["/path/to/check-aws-cloudwatch-logs-insights", "--log-group-name", "/aws/lambda/some-lambda-function", "--filter", "filter @message like /ERROR/", "--critical-over", "10", "--warning-over", "1"]
env = { AWS_REGION = "ap-northeast-1" }
CloudWatch Logs Insights のクエリ記法を利用することにより、より高度なログ絞り込みを行うこともできます。
次の例では、 JSON 形式の中に level というキーがあり、その値が "error" という文字列の場合のものを対象とします。
% AWS_REGION=ap-northeast-1 /path/to/check-aws-cloudwatch-logs-insights --log-group-name=... --filter='filter level = "error"' ...
check-aws-cloudwatch-logs との使い分け
この記事の冒頭で触れたように、このプラグインは流量の多いロググループを対象とした際に check-aws-cloudwatch-logs がうまく監視を行えない問題に対処するために開発しているものです。そのため、現在 check-aws-cloudwatch-logs がタイムアウトするようなケースでは是非お試しいただければと思っていますが、 check-aws-cloudwatch-logs と比較して以下の違い、制約があります。
- CloudWatch Logs Insights の API リクエストにより AWS 側の費用が発生する点
- 現在時刻の5分前までを対象に監視を行うため、 check-aws-cloudwatch-logs よりリアルタイム性が低い点
- ログの絞り込みに用いる表現が異なる点
CloudWatch Logs Insights の API リクエストにより AWS 側の費用が発生する点
オリジナルの check-aws-cloudwatch-logs は CloudWatch Logs の FilterLogEvents API を利用しており、この API リクエスト自体では AWS 側の費用は発生しませんが、check-aws-cloudwatch-logs-insights が利用している CloudWatch Logs Insights ではスキャンしたログのデータ量に対して費用が発生します。費用の詳細は AWS 側のページをご確認ください。(2020年10月現在、東京リージョンでは1GBあたり0.005USDです）
現在時刻の5分前までを対象に監視を行うため、 check-aws-cloudwatch-logs よりリアルタイム性が低い点
CloudWatch Logs の API の仕様上、このプラグインでは現在時刻の5分前までのログを対象に監視を行います。check-aws-cloudwatch-logs はこの制限を受けないため、よりリアルタイム性の高い監視を行うことができます。
ログの絞り込みに用いる表現が異なる点
check-aws-cloudwatch-logs では CloudWatch Logs の FilterLogEvents API を利用しているため、この API の構文で絞り込み条件を記述していました。
check-aws-cloudwatch-logs-insights では、「コマンドの利用方法」の項で触れたように CloudWatch Logs Insights の API を利用するため、こちらの構文で記述する必要があります。
注意点・おねがい
このプラグインは現在はベータ版という位置づけとなっています。今後しばらくの間はこの位置づけで公開し、ユーザーのみなさまからフィードバックをいただき改善を進めていきたいと考えております。このプラグインの仕様や振る舞い、あるいは（このプラグインに限らず） CloudWatch Logs 監視に関するご要望などがございましたら、是非フィードバックいただけましたらと思います。フィードバックには GitHub リポジトリの issue のほか、 Mackerel サポート窓口、 Mackerel User Group Slack の #check-aws-cloudwatch-logs-insights チャンネルなどをご利用ください。
Mackerel User Group Slack はこちらの URL よりご参加いただけます。
mackerel-ug-slackin.herokuapp.com
将来的にはこのプラグインの正式版をリリースすることを予定しています。その際には、正式版としての利用方法を改めてご案内させていただきます。
また、このベータ版の期間はプラグインの仕様を予告なく変更することがあります。最新の情報は GitHub のリポジトリ上をご覧下さい。
ぜひご利用下さい
以上、 Amazon CloudWatch Logs の監視に利用できる新しいプラグインをベータ版公開したことをご案内させていただきました。 Amazon CloudWatch Logs のログ監視、特に流量の多いロググループを対象とした監視に興味をお持ちでしたら、このプラグインを是非お試しいただければと思います。
備考: mackerelio-labs について
mackerel-agent など、 Mackerel が公開する多くの OSS リポジトリは https://github.com/mackerelio/ で公開していますが、https://github.com/mackerelio-labs/ では、それとは別に Mackerel チームが開発している実験的あるいは開発中のプロダクトを公開しています。 今回の check-aws-cloudwatch-logs-insights もその一環となります。将来的に正式版をリリースする際には mackerelio オーガニゼーションで改めて公開する予定です。
