こんにちは。 Mackerel チームの 
id:astj です。
昨年の10月に、Amazon CloudWatch Logs 上のログを監視する新しいチェック監視プラグイン check-aws-cloudwatch-logs-insights をベータ版として公開していました。ベータ版をお試しいただいたユーザーの皆様にはこの場で改めて感謝を申し上げます。
そして、本日、このプラグインを正式リリースしたことをお知らせします。ベータ版として公開していた v0.0.2 と比べて内部実装に変化はありませんが、 mkr plugin install を用いたインストール方法が一部変更になりました。ベータ版から正式版へのアップグレード手順についても本記事に記載しています。
ベータ版として公開した際の記事の内容と重複する部分もありますが、改めてプラグインについての説明やインストール方法について以下に記載しました。これまでベータ版をご利用いただいていた方も、今回初めて利用を検討される方もお読みいただけると幸いです。
Amazon CloudWatch Logs 上のログを監視する Mackerel の公式チェックプラグインは check-aws-cloudwatch-logs *1 が既に存在します。 check-aws-cloudwatch-logs は流量の少ないロググループに対しては十分に動作しますが、流量の多いロググループを対象とした場合はログの読み込みに時間がかかり、場合によってはタイムアウトにより正常に監視が行えないことがありました。 この check-aws-cloudwatch-logs-insights は、 CloudWatch Logs Insights の API を利用することで、流量の多いロググループであってもログ監視を行えるようにするためのものです。
利用方法
check-aws-cloudwatch-logs-insights は以下の手順で利用することができます。
プラグインの入手
プラグインの入手には、 mkr plugin install を利用する方法と、 GitHub 上から直接ダウンロードする方法があります。
mkr plugin install を利用する場合、以下のコマンドで /opt/mackerel-agent/plugins/bin/ 以下に最新バージョンの実行ファイルが展開されます。
sudo mkr plugin install check-aws-cloudwatch-logs-insights
なお、プラグインの実行ファイルは GitHub Releases にて公開しているため、 mkr のインストール機能を利用せずに Web ブラウザから直接ダウンロードすることもできます。 お使いの OS / アーキテクチャにあった物をダウンロードしてください。
Releases · mackerelio/check-aws-cloudwatch-logs-insights · GitHub
ベータ版から正式版へのアップグレード
既にベータ版を導入していた環境で正式版にアップグレードを行う場合は以下の手順で行うことができます。通常のインストールと異なり、 mkr plugin install に --overwrite オプションをつけて実行する必要があることにご注意ください。
sudo mkr plugin install --overwrite check-aws-cloudwatch-logs-insights
コマンドの利用方法
コマンドの利用方法は 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 側のページをご確認ください。(2021年6月現在、東京リージョンでは1GBあたり0.0076USDです）
現在時刻の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 を利用するため、こちらの構文で記述する必要があります。
ぜひご利用下さい
以上、 Amazon CloudWatch Logs の監視に利用できる新しいプラグインの正式版を公開したことをご案内させていただきました。 Amazon CloudWatch Logs のログ監視、特に流量の多いロググループを対象とした監視に興味をお持ちでしたら、このプラグインを是非ご利用いただければと思います。
