CloudWatch Logs FilterLogEventsのstartFromHead=falseで降順取得を試してみた
はじめに
2026年6月18日、CloudWatch LogsのFilterLogEvents APIが更新され、startFromHead パラメータで false を指定できるようになりました。
何が変わったか
startFromHead=false を指定すると、指定条件に一致するイベントを新しい側から降順で取得できます。これにより、フィルターパターンで絞り込みつつ、条件に一致するログを新しい順に確認する使い方が可能になりました。AWS CLIでは --no-start-from-head オプションに対応します。デフォルトはドキュメント記載の通り true（昇順）であり、未指定時の動作はこれまでと変わりません。
FilterLogEvents と GetLogEvents の違い
CloudWatch Logsでログイベントを直接取得する代表的なAPIとして、FilterLogEvents と GetLogEvents を比較します。
| FilterLogEvents | GetLogEvents | |
|---|---|---|
| 対象 | ロググループ内のイベント（複数ストリーム横断、ストリーム指定も可能） | 単一ログストリーム |
| フィルターパターン | 使える | 使えない |
| startFromHead=falseの指定 | 今回追加 | 以前から可能 |
GetLogEventsは単一ストリームの閲覧向けで、フィルターパターンに対応していません。この2つのAPIで比較すると、「ERRORを含むログを最新から取得したい」「REJECTのフローログを直近分だけ確認したい」といった用途にはFilterLogEventsが適しています。今回、そこに降順取得が追加されました。
制約事項
startFromHead=false を使う際の制約があります。
startTimeを2024年1月1日（UTC）以降に設定する必要がある- それ以前の日付を指定すると
InvalidParameterExceptionが返る
公式ドキュメントから引用します。
Setting startFromHead to false is supported only when startTime is on or after Jan 1, 2024 00:00:00 UTC. A request with startFromHead set to false and a startTime before this date returns an InvalidParameterException.
やってみた
VPCフローログをCloudWatch Logsに送信し、FilterLogEventsの昇順・降順の挙動を確認します。
検証環境
- AWS CLI 2.35.8
- リージョン： ap-northeast-1
- ロググループ：
/vpc/flow-logs/test-filter-log-events（VPCフローログ、集約間隔60秒）
検証1: 昇順（--start-from-head）で取得
まず従来動作の昇順で取得します。全検証で共通して --start-time 1704067200000（2024-01-01T00:00:00Z）を指定しています。
aws logs filter-log-events \
--log-group-name "/vpc/flow-logs/test-filter-log-events" \
--start-time 1704067200000 \
--limit 3 \
--start-from-head \
--region ap-northeast-1
{
"events": [
{
"logStreamName": "eni-013191c0a72b6xxxx-all",
"timestamp": 1782063972000,
"message": "2 123456789012 eni-013191c0a72b6xxxx x.x.x.x 192.168.27.87 443 48368 6 1 76 1782063972 1782064001 ACCEPT OK",
"ingestionTime": 1782064035668
},
{
"logStreamName": "eni-013191c0a72b6xxxx-all",
"timestamp": 1782063972000,
"message": "2 123456789012 eni-013191c0a72b6xxxx x.x.x.x 192.168.27.87 443 35209 6 14 2565 1782063972 1782064001 ACCEPT OK",
"ingestionTime": 1782064035668
},
{
"logStreamName": "eni-013191c0a72b6xxxx-all",
"timestamp": 1782063972000,
"message": "2 123456789012 eni-013191c0a72b6xxxx x.x.x.x 192.168.27.87 443 23647 6 3 180 1782063972 1782064001 ACCEPT OK",
"ingestionTime": 1782064035668
}
]
}
先頭イベントのtimestampは 1782063972000 で、古い側のイベントから昇順で返されています。
検証2: 降順（--no-start-from-head）で取得
次に --no-start-from-head を指定して降順で取得します。
aws logs filter-log-events \
--log-group-name "/vpc/flow-logs/test-filter-log-events" \
--start-time 1704067200000 \
--limit 3 \
--no-start-from-head \
--region ap-northeast-1
{
"events": [
{
"logStreamName": "eni-03971bd72581dxxxx-all",
"timestamp": 1782064430000,
"message": "2 123456789012 eni-03971bd72581dxxxx 192.168.23.213 192.168.27.87 2049 65221 6 6 434 1782064430 1782064432 ACCEPT OK",
"ingestionTime": 1782064456349
},
{
"logStreamName": "eni-03971bd72581dxxxx-all",
"timestamp": 1782064430000,
"message": "2 123456789012 eni-03971bd72581dxxxx 192.168.27.87 192.168.23.213 65221 2049 6 7 510 1782064430 1782064432 ACCEPT OK",
"ingestionTime": 1782064456349
},
{
"logStreamName": "nat-11f9b13f38e22xxxx-all",
"timestamp": 1782064404000,
"message": "2 123456789012 - - - - - - - - 1782064404 1782064423 - SKIPDATA",
"ingestionTime": 1782064452153
}
]
}
先頭イベントのtimestampは 1782064430000 で、指定条件に一致するイベントのうち新しい側から返されています。配列内のtimestampも 1782064430000 → 1782064430000 → 1782064404000 と並んでおり、events 配列がtimestampの新しい順で返されることを確認できました。
検証3: フィルターパターン + 降順で取得
FilterLogEventsの強みであるフィルターパターンと降順取得を組み合わせます。ここでは ACCEPT をフィルターパターンとして指定し、降順で取得します。
aws logs filter-log-events \
--log-group-name "/vpc/flow-logs/test-filter-log-events" \
--start-time 1704067200000 \
--filter-pattern "ACCEPT" \
--limit 3 \
--no-start-from-head \
--region ap-northeast-1
{
"events": [
{
"logStreamName": "eni-03971bd72581dxxxx-all",
"timestamp": 1782064430000,
"message": "2 123456789012 eni-03971bd72581dxxxx 192.168.23.213 192.168.27.87 2049 65221 6 6 434 1782064430 1782064432 ACCEPT OK",
"ingestionTime": 1782064456349
},
{
"logStreamName": "eni-03971bd72581dxxxx-all",
"timestamp": 1782064430000,
"message": "2 123456789012 eni-03971bd72581dxxxx 192.168.27.87 192.168.23.213 65221 2049 6 7 510 1782064430 1782064432 ACCEPT OK",
"ingestionTime": 1782064456349
},
{
"logStreamName": "nat-11f9b13f38e22xxxx-all",
"timestamp": 1782064404000,
"message": "2 123456789012 - 192.168.27.87 x.x.x.x 38256 443 6 3 180 1782064404 1782064423 ACCEPT OK",
"ingestionTime": 1782064452153
}
]
}
フィルターパターンで条件に合うイベントのみに絞り込んだうえで、降順で取得できました。検証2で3件目に含まれていた SKIPDATA レコードが除外され、ACCEPT を含むイベントのみが返されています。
結果の比較
| パラメータ | 先頭イベントの timestamp | 並び順 |
|---|---|---|
--start-from-head（昇順） |
1782063972000（取得範囲の古い側） | 古い → 新しい |
--no-start-from-head（降順） |
1782064430000（取得範囲の新しい側） | 新しい → 古い |
--filter-pattern "ACCEPT" + --no-start-from-head |
1782064430000（取得範囲の新しい側） | 新しい → 古い |
フィルターパターンを指定した場合も、条件に一致したイベントが新しいtimestampから古いtimestampの順で返されました。
まとめ
FilterLogEvents APIに startFromHead=false が追加されたことで、フィルターパターンと降順取得をAPI単体で組み合わせられるようになりました。マネジメントコンソールでは以前から最新ログを確認する手段が用意されていましたが、今回の更新によりCLIやSDKからも --no-start-from-head を付けるだけで同様の取得ができます。障害対応時にエラーパターンで絞って直近のログだけ見る、デプロイ後に特定キーワードを含む最新ログを確認する、といった操作がロググループ単位で、かつ1コマンドで実現できます。
