はじめに
このブログ記事では AWS のログ分析サービスである Amazon CloudWatch Logs Insights の基本的な使い方と主要なクエリコマンドを解説します。実際にクエリを試しながら読み進めてみてください。
準備
CloudWatch Logs Insights を利用するには、分析対象のログが CloudWatch Logs に保存されている必要があります。
CloudWatch コンソールに移動し、左側のナビゲーションペインから「ログ」セクション内の「ログのインサイト」を選択します。
上記スクリーンショットのようにロググループを選択する画面が表示されます。分析したいロググループを選びましょう。(※ロググループの作成については割愛します。)
基本的なクエリ構造
CloudWatch Logs Insights のクエリは複数のコマンドをパイプ (|) で繋いで記述します。データは左から右へ順に処理されます。
fields @timestamp, @message | filter level = 'ERROR' | sort @timestamp desc | limit 20
この例ではまず fields コマンドで表示するフィールドを指定します。次に filter コマンドで level が ERROR のログを絞り込みます。そして sort コマンドでタイムスタンプの降順に並べ替えます。最後に limit コマンドで最初の 20件を表示します。
主要なコマンド
CloudWatch Logs Insights でよく使う主要なコマンドを紹介します。
1. fields
fields コマンドは表示するログフィールドを指定します。指定しない場合は全てのフィールドが表示されます。
主な予約済みフィールド:
| フィールド | 説明 |
|---|---|
@timestamp |
ログイベントのタイムスタンプです。UTC で格納されます。 |
@message |
生のログメッセージ本文です。 |
@logStream |
ログイベントが属するログストリームです。 |
@log |
ログイベントが属するロググループです (アカウント ID:ロググループ名)。 |
@ingestionTime |
CloudWatch Logs がログイベントを受信した時刻です。 |
クエリ例:
fields @timestamp, @message, level | limit 5
このクエリを実行します。タイムスタンプとメッセージそして level フィールドが 5件表示されることを確認できます。
2. filter
filter コマンドは条件に一致するログイベントのみを抽出します。
利用可能な比較演算子と論理演算子:
| 演算子 | 説明 |
|---|---|
= |
等しい |
!= |
等しくない |
> |
より大きい |
>= |
以上 |
<= |
以下 |
like |
文字列の部分一致 (正規表現も可) |
not like |
文字列の部分不一致 (正規表現も可) |
in |
配列内のいずれかの値に一致 |
not in |
配列内のどの値にも不一致 |
and |
かつ |
or |
または |
not |
否定 |
=~ |
正規表現に一致 |
!~ |
正規表現に不一致 |
クエリ例1: 特定の文字列を含むログを検索
fields @timestamp, @message | filter @message like /ERROR/ | limit 5
このクエリを実行します。メッセージ本文に "ERROR" という文字列が含まれるログが 5件表示されることを確認できます。
クエリ例2: 複数の条件でログを検索
fields @timestamp, @message, statusCode | filter level = 'INFO' and httpStatusCode = 200 | limit 5
このクエリを実行します。level が INFO でかつ httpStatusCode が 200 のログが 5件表示されることを確認できます。(level や httpStatusCode のフィールドはログ設計によって変わります)
3. sort
sort コマンドは指定したフィールドでログイベントを並べ替えます。
asc: 昇順 (デフォルト)desc: 降順
クエリ例:
fields @timestamp, @message | sort @timestamp desc | limit 5
このクエリを実行します。タイムスタンプの新しい順 (降順) にログが 5件表示されることを確認できます。
4. stats
stats コマンドは集計関数を使い統計情報を計算します。by 句と組み合わせ特定のフィールドごとに集計できます。
主な集計関数:
| 関数 | 説明 |
|---|---|
count(*) |
イベント数をカウントします。 |
count(fieldName) |
指定フィールドが存在するイベント数をカウントします。 |
count_distinct(fieldName) |
指定フィールドの一意な値の数をカウントします。 |
avg(numericField) |
数値フィールドの平均値を計算します。 |
sum(numericField) |
数値フィールドの合計値を計算します。 |
min(numericField) |
数値フィールドの最小値を計算します。 |
max(numericField) |
数値フィールドの最大値を計算します。 |
percentile(numericField, N) |
数値フィールドの N パーセンタイル値を計算します。 |
クエリ例:
stats count(*) by level
このクエリを実行します。ログの level フィールド (例: INFO, ERROR, WARN) ごとの件数が集計されて表示されることを確認できます。
5. parse
parse コマンドはログメッセージから一時的なフィールドを抽出します。特に構造化されていないテキストログから情報を抜き出すのに役立ちます。グロブ表現（*）を使ってフィールドを抽出します。
クエリ例:
仮に以下のようなログメッセージがあるとします。
"INFO: User jonhdoe logged in from 192.168.1.100"
fields @message | parse @message "INFO: User * logged in from *" as user, ipAddress | limit 5
このクエリは、「*に何かしらの文字が入りますよ」「その文字はuserとipAddressというフィールド名で扱ってくださいね」というクエリです。
元の @message に加えて user と ipAddress という新しいフィールドが抽出され表示されることが確認できます。
よく使われるクエリの例
ここでは実践的なクエリの例をいくつか紹介します。
1. 直近 10件のエラーログを表示
fields @timestamp, @message | filter level = 'ERROR' or @message like /error|Exception/ | sort @timestamp desc | limit 10
このクエリは level フィールドが ERROR のログまたはメッセージ本文に error か Exception を含むログを検索します。そして新しい順に 10件表示します。実行結果からエラーに関連するログが抽出されていることを確認できます。
2. HTTP ステータスコードごとのリクエスト数を集計
API Gateway や Webサーバーのアクセスログ分析に便利です。
stats count(*) as event_count by httpStatusCode | sort event_count desc
このクエリは (ログに httpStatusCode フィールドが存在する場合) HTTP ステータスコードごとのリクエスト数を集計し件数が多い順に表示します。実行結果から各ステータスコードの発生頻度がわかることを確認できます。
3. 特定の IP アドレスからのアクセスログを抽出
fields @timestamp, @message, client_ip | filter client_ip = '192.168.20.200' # 対象のIPアドレスに置き換えてください | sort @timestamp desc | limit 20
このクエリは (ログに client_ip フィールドが存在する場合) 特定の IP アドレスからのアクセスログを新しい順に 20件表示します。実行結果から指定した IP アドレスの活動履歴を追跡できることを確認できます。
クエリ実行のヒント
- 時間範囲の指定: クエリ実行画面の上部で分析対象の時間範囲を指定します。範囲が広いほどスキャン対象のデータ量が増え料金や実行時間に影響します。
- 小規模データで試す: 最初は短い時間範囲で
limitを使いクエリが期待通り動作するか確認しましょう。 - フィールドの確認: どんなフィールドが利用可能か不明な場合は
fields * | limit 1のように実行すると最初のログイベントの全フィールドを確認できます。 - コスト意識: CloudWatch Logs Insights はスキャンしたデータ量に応じて課金されます。不必要に広範囲なクエリや長期間のクエリは避けましょう。
まとめ
この記事では CloudWatch Logs Insights の基本的なクエリとコマンドを解説しました。fields filter sort limit stats parse といったコマンドを組み合わせることで多様なログ分析が可能です。
実際に手を動かしてクエリを試すことが習得への一番の近道です。日々の運用やトラブルシューティングにぜひ CloudWatch Logs Insights を活用してください。
参考ドキュメント
CloudWatch Logs Insights クエリ構文
https://docs.aws.amazon.com/ja\_jp/AmazonCloudWatch/latest/logs/CWL\_QuerySyntax.html
サンプルクエリ
https://docs.aws.amazon.com/ja\_jp/AmazonCloudWatch/latest/logs/CWL\_QuerySyntax-examples.html
簡単30秒