AWS EmulatorでCloudWatch Logsを検索する方法

​​AWS Emulator​Amazon CloudWatch Logs,AWS CLI

AWS Emulator を手元で動かすと、AWS のアカウントがなくても、AWS CLI で CloudWatch Logs にログを書いて検索できます。アプリのエラーログを CloudWatch Logs から探す処理や、ログの件数を数える集計のクエリを、ローカル環境や CI で本物のログを使わずに試したいときの手順です。ロググループを作ってログを書くところから、フィルターパターンでの検索、CloudWatch Logs Insights のクエリ、aws logs tail での表示まで、検証環境で実行したコマンドと出力のまま載せます。

補足

検証環境は Ubuntu 24.04(x86_64)、AWS Emulator 1.0.486(2026年11月17日リリース)、AWS CLI 2.40.4、jq 1.7 です。AWS のアカウントと認証情報は使っていません。本物の CloudWatch Logs での動き(料金、保持期間が過ぎたログの削除、権限の判定、クエリにかかる時間)は確かめていません。aws logs tail --follow で新しいログを待ち続ける使い方と、フィルターパターンで ? の付いた語とほかの語を混ぜたときの本物の CloudWatch Logs での結果も、試していません。本物の AWS について書いているところは、公式ドキュメントを出どころにしています。出力の中の12桁のアカウントIDは置き換えています。

エミュレーターを起動して、AWS CLI を向ける

AWS Emulator は、AWS の API を手元で受け付けるエミュレーターです。公式ドキュメントによると、AWS のアカウントは要らず、リクエストは AWS に送られません。

入れ方は別の記事「AWS EmulatorをUbuntuに入れて使い始める方法」で詳しく扱っています。ここでは、Linux 向けの手順にある Debian パッケージを、gpg で署名を確かめてから入れました。私は root で作業したので sudo を付けていませんが、下のコマンドでは一般のユーザー向けに付けています。

bash
curl -fsSLO https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest/aws-emulator_amd64.deb
sudo apt-get install -y ./aws-emulator_amd64.deb

起動は aws-emulator です。-t off は、既定で AWS に送られる利用状況のデータ(テレメトリー)を止める指定です。エミュレーターはその端末で動き続けるので、AWS CLI は別の端末で使います。

bash
aws-emulator -t off

別の端末で、公式ドキュメントにある環境変数を設定します。エミュレーターは 127.0.0.1:9297 で待ち受け、この起動でだけ使えるアクセスキーと設定ファイル、証明書を ~/.aws/emulator/9297/ に書き出します。

bash
export AWS_ENDPOINT_URL=https://127.0.0.1:9297
export AWS_SHARED_CREDENTIALS_FILE=~/.aws/emulator/9297/emulator_credentials
export AWS_CONFIG_FILE=~/.aws/emulator/9297/config
export AWS_CA_BUNDLE=~/.aws/emulator/9297/ca.pem
export AWS_EC2_METADATA_DISABLED=true
export AWS_DISABLE_HOST_PREFIX_INJECTION=true
export AWS_REGION=us-east-1
export AWS_DEFAULT_REGION=us-east-1
unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN AWS_PROFILE
注意

公式ドキュメントでは、AWS_ENDPOINT_URL が設定されていないシェルでコマンドを実行すると、見つかった認証情報で本物の AWS に送られると注意しています。本物の認証情報があるマシンでは、上の環境変数をすべて設定したシェルで実行してください。

ARN の最後が user/emulator なら、エミュレーターが答えています。起動した直後は、ロググループは1つもありません。

text
$ aws sts get-caller-identity --query Arn --output text
arn:aws:iam::<12桁のアカウントID>:user/emulator
$ aws logs describe-log-groups
{
    "logGroups": []
}

ロググループとログストリームを作る

CloudWatch Logs のログは、ロググループ、ログストリーム、ログイベントの3段で持ちます。公式の用語の説明によると、ログイベントは「起きた時刻」と「メッセージ」の組で、ログストリームは同じ出どころ(アプリのインスタンスなど)から来たログイベントの並びです。ロググループは、保持期間などの設定をまとめるログストリームの入れ物です。

ここでは、ロググループ /example/app の中に、Web サーバー2台ぶんのつもりでログストリーム web-1 と web-2 を作りました。

text
$ aws logs create-log-group --log-group-name /example/app
$ aws logs create-log-stream --log-group-name /example/app --log-stream-name web-1
$ aws logs create-log-stream --log-group-name /example/app --log-stream-name web-2

どのコマンドも、成功すると何も出力しません(終了コードは 0 でした)。作ったものは describe-log-groups と describe-log-streams で確かめられます。保持期間(retentionInDays)は、指定しないと null でした。

text
$ aws logs describe-log-groups --query "logGroups[].{name: logGroupName, retention: retentionInDays, bytes: storedBytes}"
[
    {
        "name": "/example/app",
        "retention": null,
        "bytes": 0
    }
]
$ aws logs describe-log-streams --log-group-name /example/app --query "logStreams[].logStreamName"
[
    "web-1",
    "web-2"
]

同じ名前のロググループをもう一度作ると、ResourceAlreadyExistsException で断られました。テストの前処理で毎回作るなら、このエラーを無視するか、先に消しておく必要があります。

text
$ aws logs create-log-group --log-group-name /example/app

aws: [ERROR]: An error occurred (ResourceAlreadyExistsException) when calling the CreateLogGroup operation: The specified log group already exists

ログを書く

ログを書くのは aws logs put-log-events です。1つのログイベントは timestamp(1970年1月1日からのミリ秒)と message の組です。シェルでは date +%s%3N で、今の時刻をミリ秒で出せます。

text
$ date +%s%3N
1794899351146

件数が少ないうちは、--log-events に timestamp=...,message=... の形で並べると手早く書けます。

text
$ T=$(date +%s%3N); aws logs put-log-events --log-group-name /example/app --log-stream-name web-1 --log-events timestamp=$T,message="INFO server started" timestamp=$((T+1)),message="ERROR db timeout after 3000 ms"
{
    "nextSequenceToken": "00000000000000000000000000000000000000000000000000000002"
}

JSON 形式のログのように、メッセージに引用符が入るときは、ログイベントの配列を JSON のファイルにして file:// で渡すのが楽です。下では jq で、メッセージを JSON の文字列にしたファイル events.json を作り、web-2 に書きました。

text
$ T=$(date +%s%3N); jq -n -c --argjson t $T '[{timestamp:$t,message:({level:"ERROR",status:500,path:"/api/orders",ms:1200}|tojson)},{timestamp:($t+1),message:({level:"INFO",status:200,path:"/api/orders",ms:35}|tojson)},{timestamp:($t+2),message:({level:"WARN",status:429,path:"/api/users",ms:5}|tojson)}]' > events.json; cat events.json
[{"timestamp":1794899351760,"message":"{\"level\":\"ERROR\",\"status\":500,\"path\":\"/api/orders\",\"ms\":1200}"},{"timestamp":1794899351761,"message":"{\"level\":\"INFO\",\"status\":200,\"path\":\"/api/orders\",\"ms\":35}"},{"timestamp":1794899351762,"message":"{\"level\":\"WARN\",\"status\":429,\"path\":\"/api/users\",\"ms\":5}"}]
$ aws logs put-log-events --log-group-name /example/app --log-stream-name web-2 --log-events file://events.json
{
    "nextSequenceToken": "00000000000000000000000000000000000000000000000000000006"
}

この記事で書くログの置き場所は、下の図のようになります。この後の検索のコマンドが、どこを読むかも書き添えました。

ロググループ /example/app の中に、ログストリーム web-1(テキストのログ)と web-2(JSON のログ)がある。get-log-events は1つのストリームを、filter-log-events・tail・start-query はグループ全体を読む
この記事で作ったロググループと、読むコマンドの範囲

書いたつもりのログが入らないとき

put-log-events は、条件に合わないログイベントがあっても、エラーにならずに成功することがあります。PutLogEvents の API リファレンスには、14日より古いイベントと、2時間より先の未来のイベントは、ほかの正しいイベントを処理しながら拒否する、と書かれています。

エミュレーターで、15日前のログと今のログを1回で書くと、終了コードは 0 で、応答に rejectedLogEventsInfo が付きました。3時間先のログと今のログを書いたときも同じです。

text
$ T=$(date +%s%3N); aws logs put-log-events --log-group-name /example/app --log-stream-name web-1 --log-events timestamp=$((T-15*24*3600*1000)),message="INFO 15 days ago" timestamp=$T,message="INFO now"
{
    "nextSequenceToken": "00000000000000000000000000000000000000000000000000000008",
    "rejectedLogEventsInfo": {
        "tooOldLogEventEndIndex": 1
    }
}
$ T=$(date +%s%3N); aws logs put-log-events --log-group-name /example/app --log-stream-name web-1 --log-events timestamp=$T,message="INFO now 2" timestamp=$((T+3*3600*1000)),message="INFO 3 hours later"
{
    "nextSequenceToken": "00000000000000000000000000000000000000000000000000000010",
    "rejectedLogEventsInfo": {
        "tooNewLogEventStartIndex": 1
    }
}

数字は、送った配列の中の位置(0から数える)を表します。RejectedLogEventsInfo の説明によると、tooOldLogEventEndIndex はその番号の手前まで(番号自身は含まない)が古すぎるもの、tooNewLogEventStartIndex はその番号から後ろが新しすぎるものです。拒否されたのは、1回目では0番目の「INFO 15 days ago」、2回目では1番目の「INFO 3 hours later」で、web-1 に残ったのは今の時刻のログだけでした。

text
$ aws logs filter-log-events --log-group-name /example/app --log-stream-names web-1 --query "events[].message"
[
    "INFO server started",
    "ERROR db timeout after 3000 ms",
    "INFO now",
    "INFO now 2"
]

古いログをまとめて流し込むテストでは、終了コードだけで成功とみなさず、rejectedLogEventsInfo があるかを確かめる必要があります。

一方、1回で送るログの時刻が古い順に並んでいないときと、ログストリームがないときは、put-log-events 自体が失敗しました。終了コードは 254 です。

text
$ T=$(date +%s%3N); aws logs put-log-events --log-group-name /example/app --log-stream-name web-1 --log-events timestamp=$((T+10)),message="b" timestamp=$T,message="a"

aws: [ERROR]: An error occurred (InvalidParameterException) when calling the PutLogEvents operation: Log events in a single PutLogEvents request must be in chronological order.
$ T=$(date +%s%3N); aws logs put-log-events --log-group-name /example/app --log-stream-name web-9 --log-events timestamp=$T,message="x"

aws: [ERROR]: An error occurred (ResourceNotFoundException) when calling the PutLogEvents operation: The specified log stream does not exist.

時刻順に並べることは、API リファレンスにも条件として書かれています。

逆に、正しくない値を付けても通るものもあります。put-log-events の応答にある nextSequenceToken は、もう使う必要がありません。同じ API リファレンスによると、シーケンストークンは無視されるようになり、正しくないトークンを付けても受け付けられます。エミュレーターでも、でたらめな --sequence-token 123 を付けた書き込みが通りました。

text
$ T=$(date +%s%3N); aws logs put-log-events --log-group-name /example/app --log-stream-name web-1 --sequence-token 123 --log-events timestamp=$T,message="INFO wrong token"
{
    "nextSequenceToken": "00000000000000000000000000000000000000000000000000000012"
}

1つのログストリームを順に読む

特定のログストリームを古い順に読むときは、aws logs get-log-events に --start-from-head を付けます。ログに付けた時刻(timestamp)と、CloudWatch Logs が受け付けた時刻(ingestionTime)が並んで返りました。

text
$ aws logs get-log-events --log-group-name /example/app --log-stream-name web-1 --start-from-head
{
    "events": [
        {
            "timestamp": 1794899351149,
            "message": "INFO server started",
            "ingestionTime": 1794899351640
        },
        {
            "timestamp": 1794899351150,
            "message": "ERROR db timeout after 3000 ms",
            "ingestionTime": 1794899351640
        },
        {
            "timestamp": 1794899352476,
            "message": "INFO now",
            "ingestionTime": 1794899352975
        },
        {
            "timestamp": 1794899353104,
            "message": "INFO now 2",
            "ingestionTime": 1794899353685
        },
        {
            "timestamp": 1794899355923,
            "message": "INFO wrong token",
            "ingestionTime": 1794899356468
        }
    ],
    "nextForwardToken": "f/20000000000000000000000000001794899355923000000116942627/s",
    "nextBackwardToken": "b/20000000000000000000000000001794899351149000000006942627/s"
}

フィルターパターンで、グループ全体から探す

ロググループの中のすべてのログストリームから探すときは、aws logs filter-log-events を使います。--filter-pattern に書くのが、CloudWatch Logs のフィルターパターンです。

いちばん簡単なのは、語を1つ書く形です。ERROR で探すと、web-1 のテキストのログと、web-2 の JSON のログの両方が見つかりました。

text
$ aws logs filter-log-events --log-group-name /example/app --filter-pattern ERROR --query "events[].[logStreamName, message]" --output text
web-1	ERROR db timeout after 3000 ms
web-2	{"level":"ERROR","status":500,"path":"/api/orders","ms":1200}

フィルターパターンは、大文字と小文字を区別します(公式ドキュメントにもそう書かれています)。小文字の error では、1件も見つかりませんでした。

text
$ aws logs filter-log-events --log-group-name /example/app --filter-pattern error --query "events[].message"
[]

語の組み合わせで絞る

空白を含む言い回しをそのまま探すときは、二重引用符で囲みます。語の前に - を付けると、その語を含むログを除けます。

text
$ aws logs filter-log-events --log-group-name /example/app --filter-pattern "\"db timeout\"" --query "events[].message"
[
    "ERROR db timeout after 3000 ms"
]
$ aws logs filter-log-events --log-group-name /example/app --filter-pattern "ERROR -db" --query "events[].message"
[
    "{\"level\":\"ERROR\",\"status\":500,\"path\":\"/api/orders\",\"ms\":1200}"
]

「どれか1つを含む」は、語の前に ? を付けます。?ERROR ?WARN で、ERROR か WARN を含む3件が見つかりました。

text
$ aws logs filter-log-events --log-group-name /example/app --filter-pattern "?ERROR ?WARN" --query "events[].message"
[
    "ERROR db timeout after 3000 ms",
    "{\"level\":\"ERROR\",\"status\":500,\"path\":\"/api/orders\",\"ms\":1200}",
    "{\"level\":\"WARN\",\"status\":429,\"path\":\"/api/users\",\"ms\":5}"
]

ここは、エミュレーターの結果が公式ドキュメントの説明と合わなかったところです。公式ドキュメントには、? の語を ? の付かない語と同じパターンに混ぜると、? の語はすべて無視されると書かれています。つまり ?ERROR ?WARN orders は、orders だけを書いたパターンと同じ結果になる、という説明です。

エミュレーターを起動し直し、web-2 に同じ3件だけを書いた状態で比べると、orders だけでは2件(ERROR と INFO の行)が返りました。?ERROR ?WARN orders では、ERROR と orders の両方を含む1件だけでした。エミュレーターは ? の語を無視していません。

text
$ aws logs filter-log-events --log-group-name /example/app --filter-pattern "orders" --query "events[].message"
[
    "{\"level\":\"ERROR\",\"status\":500,\"path\":\"/api/orders\",\"ms\":1200}",
    "{\"level\":\"INFO\",\"status\":200,\"path\":\"/api/orders\",\"ms\":35}"
]
$ aws logs filter-log-events --log-group-name /example/app --filter-pattern "?ERROR ?WARN orders" --query "events[].message"
[
    "{\"level\":\"ERROR\",\"status\":500,\"path\":\"/api/orders\",\"ms\":1200}"
]

? の語とほかの語を混ぜたパターンは、エミュレーターと公式ドキュメントで答えが分かれるので、テストにも本番の検索にも使わないほうが無難です。

JSON のログを、項目の値で絞る

メッセージが JSON のログは、{ $.項目名 演算子 値 } の形で、項目の値を条件にできます。数値は >= などで比べられ、&& で条件を重ねられます。文字列の値は二重引用符で囲みます。

text
$ aws logs filter-log-events --log-group-name /example/app --filter-pattern "{ \$.status >= 500 }" --query "events[].message"
[
    "{\"level\":\"ERROR\",\"status\":500,\"path\":\"/api/orders\",\"ms\":1200}"
]
$ aws logs filter-log-events --log-group-name /example/app --filter-pattern "{ \$.path = \"/api/orders\" && \$.ms > 100 }" --query "events[].message"
[
    "{\"level\":\"ERROR\",\"status\":500,\"path\":\"/api/orders\",\"ms\":1200}"
]
$ aws logs filter-log-events --log-group-name /example/app --filter-pattern "{ \$.level = \"INFO\" }" --query "events[].message"
[
    "{\"level\":\"INFO\",\"status\":200,\"path\":\"/api/orders\",\"ms\":35}"
]

シェルの二重引用符の中に書いているので、$ の前に \ を付けています。付けないと、シェルが $.status を変数として読もうとします。

正規表現で探す

% で囲むと、正規表現で探せます。公式ドキュメントによると、使える記号は限られていて、空白は一覧になく、( と ) によるグループも使えません。空白には、一覧にある \s を使います。4桁の数字のあとに空白と ms が続くログを探すと、3000 ms を含むログが見つかりました(web-1 の2件だけを書いた状態で確かめています)。

text
$ aws logs filter-log-events --log-group-name /example/app --filter-pattern "%[0-9]{4}\sms%" --query "events[].message"
[
    "ERROR db timeout after 3000 ms"
]

ログストリームと時刻で範囲を狭める

--log-stream-name-prefix を付けると、名前がその文字で始まるログストリームだけを探します(決まった名前を並べるときは --log-stream-names)。

text
$ aws logs filter-log-events --log-group-name /example/app --log-stream-name-prefix web-2 --filter-pattern ERROR --query "events[].message"
[
    "{\"level\":\"ERROR\",\"status\":500,\"path\":\"/api/orders\",\"ms\":1200}"
]

--start-time には、ミリ秒の時刻を渡します。下では、今の時刻を変数 T に入れてから2秒待ってログを1件書き、T より後の ERROR を探しました。それより前に書いた ERROR のログは出てきません。テストで「この操作のあとに出たログ」だけを確かめるときに使えます。

text
$ T=$(date +%s%3N); sleep 2; aws logs put-log-events --log-group-name /example/app --log-stream-name web-1 --log-events timestamp=$(date +%s%3N),message="ERROR after mark" >/dev/null; aws logs filter-log-events --log-group-name /example/app --start-time $T --filter-pattern ERROR --query "events[].message"
[
    "ERROR after mark"
]

FilterLogEvents の API リファレンスによると、本物の CloudWatch Logs では、結果が複数のページに分かれ、途中のページが空のこともあります。続きがあるかは nextToken があるかで判断します。今回の件数では、エミュレーターの応答に nextToken は付きませんでした。

Logs Insights のクエリで集計する

件数や平均を出したいときは、CloudWatch Logs Insights のクエリを使います。AWS CLI では、aws logs start-query でクエリを始め、返ってきた queryId を aws logs get-query-results に渡して結果を受け取ります。StartQuery の API リファレンスにあるとおり、--start-time と --end-time は、ミリ秒ではなく秒で指定します。filter-log-events とは単位が違う点に気をつけてください。

2つのコマンドを毎回打つのは手間なので、次のスクリプト insights.sh にまとめました。直近1時間のログにクエリを投げ、状態が Complete になるまで1秒おきに待ってから、結果を出します。

bash
#!/bin/bash
# 使い方: bash insights.sh 'クエリ' ['JMESPath' [AWS CLI のほかのオプション]]
# 直近1時間の /example/app に CloudWatch Logs Insights のクエリを投げ、終わるのを待って結果を出す
Q=$(aws logs start-query --log-group-name /example/app \
  --start-time $(date -d '-1 hour' +%s) --end-time $(date +%s) \
  --query-string "$1" --query queryId --output text)
for i in $(seq 30); do
  S=$(aws logs get-query-results --query-id "$Q" --query status --output text)
  [ "$S" = Complete ] && break
  sleep 1
done
aws logs get-query-results --query-id "$Q" --query "${2:-results}" "${@:3}"

まず、ERROR を含むログを新しい順に出します。結果は1行ごとに field と value の組の配列で返るので、JMESPath でログストリーム名とメッセージだけを取り出しました。

text
$ bash insights.sh "fields @timestamp, @logStream, @message | filter @message like /ERROR/ | sort @timestamp desc | limit 5" "results[*].[ @[?field==\`@logStream\`].value | [0], @[?field==\`@message\`].value | [0] ]" --output text
web-1	ERROR after mark
web-2	{"level":"ERROR","status":500,"path":"/api/orders","ms":1200}
web-1	ERROR db timeout after 3000 ms

@message や @logStream は、Logs Insights がどのログにも用意する項目です。自動で見つける項目の説明によると、JSON のログでは、JSON の中の項目もクエリで使えます。エミュレーターでも、status、ms、path をそのまま使えました。下は、status を持つログ(JSON のログ)だけを残し、path ごとの件数と ms の平均を出すクエリです。結果は加工せずに出しています。

text
$ bash insights.sh "filter ispresent(status) | stats count(*) as n, avg(ms) as avg_ms by path"
[
    [
        {
            "field": "path",
            "value": "/api/orders"
        },
        {
            "field": "n",
            "value": "2"
        },
        {
            "field": "avg_ms",
            "value": "617.5"
        }
    ],
    [
        {
            "field": "path",
            "value": "/api/users"
        },
        {
            "field": "n",
            "value": "1"
        },
        {
            "field": "avg_ms",
            "value": "5"
        }
    ]
]

値は数値でも、"2" や "617.5" のように文字列で返りました。テストで数として比べるときは、変換してから比べます。

JSON の項目は、filter の条件にも使えます。status が 400 以上のログが2件返りました。

text
$ bash insights.sh "fields @message | filter status >= 400" "results[*][?field==\`@message\`].value[]"
[
    "{\"level\":\"WARN\",\"status\":429,\"path\":\"/api/users\",\"ms\":5}",
    "{\"level\":\"ERROR\",\"status\":500,\"path\":\"/api/orders\",\"ms\":1200}"
]

クエリの書き方の説明では、本物の CloudWatch Logs で大きなクエリを実行して料金がかさまないように、ロググループと時間の範囲をできるだけ狭くするよう勧めています。エミュレーターでは料金はかかりませんが、本番で同じクエリを使うつもりなら、範囲を絞った形で書いておくのが安全です。

aws logs tail で、ターミナルに流す

ログを目で追うだけなら、aws logs tail が手軽です。ロググループのすべてのログストリームから、時刻とストリーム名を付けて1行ずつ出します。tail のリファレンスによると、既定では直近10分のログを出して終わります。--since 1h で1時間前から出し、--filter-pattern にはフィルターパターンをそのまま書けました。

text
$ timeout 10 aws logs tail /example/app --since 1h --filter-pattern "{ \$.status >= 400 }"
2026-11-17T07:09:11.760000+00:00 web-2 {"level":"ERROR","status":500,"path":"/api/orders","ms":1200}
2026-11-17T07:09:11.762000+00:00 web-2 {"level":"WARN","status":429,"path":"/api/users","ms":5}

--format short にすると、ストリーム名を省き、時刻を秒までに縮めて出します。この記事で書いたログが、すべて時刻順に並びました(先頭の timeout 10 は、検証のスクリプトが止まらなくなるのを避けるために付けたものです。tail のリファレンスによると、--follow を付けなければ、出すログがなくなった時点で終わります)。

text
$ timeout 10 aws logs tail /example/app --since 1h --format short
2026-11-17T07:09:11 INFO server started
2026-11-17T07:09:11 ERROR db timeout after 3000 ms
2026-11-17T07:09:11 {"level":"ERROR","status":500,"path":"/api/orders","ms":1200}
2026-11-17T07:09:11 {"level":"INFO","status":200,"path":"/api/orders","ms":35}
2026-11-17T07:09:11 {"level":"WARN","status":429,"path":"/api/users","ms":5}
2026-11-17T07:09:12 INFO now
2026-11-17T07:09:13 INFO now 2
2026-11-17T07:09:15 INFO wrong token
2026-11-17T07:09:27 ERROR after mark

片付け

試し終わったら、aws logs delete-log-group でロググループを消します。一覧は空に戻りました。

text
$ aws logs delete-log-group --log-group-name /example/app
$ aws logs describe-log-groups --query "logGroups[].logGroupName"
[]

制限の説明によると、エミュレーターはすべてをメモリーに持っていて、止めると消します。テストのたびにエミュレーターを起動し直せば、ロググループを消す手順がなくても、まっさらな状態から始められます。

​Posted by 86