localstack-logs

LocalStack ログ分析

LocalStack のログを分析して、問題のデバッグ、エラーの特定、AWS API のやり取りの把握に役立てます。

機能

• LocalStack のログの表示とフィルタリング
• エラーパターンと失敗の特定
• AWS API のリクエスト／レスポンスのサイクルの分析
• サービス固有の操作の追跡
• Lambda 関数の実行のデバッグ

前提条件

• 実行中のエミュレーターを備えた lstk CLI — localstack スキルを参照してください

ログの表示

基本的なログコマンド

# Print available logs
lstk logs

# Follow logs in real time
lstk logs -f

# Last N lines
lstk logs -n 100

# Unfiltered output (lstk filters noise by default)
lstk logs -v

想定しているログ行が見つからない場合は、lstk logs -v を使ってください。デフォルトの表示では、重要度の低い出力が省かれます。

ログのフィルタリング

# Filter by service
lstk logs | grep -i s3
lstk logs | grep -i lambda
lstk logs | grep -i dynamodb

# Filter errors only
lstk logs | grep -i error
lstk logs | grep -i exception

# Filter by request ID (use -v so nothing is filtered out first)
lstk logs -v | grep "request-id-here"

診断ログ

CLI 自体に問題がある場合（エミュレーターではなく）、lstk は設定ディレクトリ内の lstk.log に診断ログを書き込みます。

lstk config path      # the lstk.log sits alongside this file

デバッグモード

lstk は、ホスト環境変数のうち LOCALSTACK_ がプレフィックスとして付いているものをエミュレーターに渡します。そのため、LocalStack の設定変数にはこのプレフィックスが必要です。

# Start with debug mode
LOCALSTACK_DEBUG=1 lstk start

# Trace-level logging
LOCALSTACK_LS_LOG=trace lstk start

プロジェクトでデバッグログをデフォルトにするには、config.toml の環境プロファイルを使用します。

[[containers]]
type = "aws"
env  = ["debug"]

[env.debug]
DEBUG = "1"

[env.*] プロファイル内のキーには、LOCALSTACK_ プレフィックスは不要です。

API リクエストの分析

リクエスト／レスポンスの追跡

LocalStack のログには AWS API リクエストが含まれます。次のようなパターンを探してください。

AWS <service>.<operation> => <status>

ログエントリの例：

AWS s3.CreateBucket => 200
AWS dynamodb.PutItem => 200
AWS lambda.Invoke => 200

デプロイ済みリソース

lstk status は現在エミュレーターにデプロイされているリソースを一覧表示します。「このリソースは存在するか」という疑問に答えるには、ログを grep するよりも迅速なことがよくあります。

lstk status
lstk --non-interactive status

よくあるエラーパターン

エラー	考えられる原因	解決策
ResourceNotFoundException	リソースが存在しません	まずリソースを作成し、lstk status で確認します
AccessDeniedException	IAM ポリシーの問題	IAM の適用モードを確認します
ValidationException	パラメーターが無効です	リクエストパラメーターを確認します
ServiceException	内部エラー	詳細について LocalStack のログを確認します

Lambda のデバッグ

Lambda ログの表示

# Lambda function logs appear in the emulator logs
lstk logs -v | grep -A 10 "Lambda"

# Or use CloudWatch Logs locally
lstk aws logs describe-log-groups
lstk aws logs get-log-events \
  --log-group-name /aws/lambda/my-function \
  --log-stream-name <stream-name>

Lambda デバッグモードの有効化

LOCALSTACK_LAMBDA_DEBUG=1 lstk start

ヘルスチェック

# Check overall health
curl http://localhost:4566/_localstack/health | jq

# Check specific service
curl http://localhost:4566/_localstack/health | jq '.services.s3'

トラブルシューティングのヒント

• ログが表示されない：エミュレーターが実行中であることを確認します（lstk status）
• 想定した行が見つからない：lstk logs -v を指定して再実行します。デフォルトの表示はフィルタリングされています
• デバッグ情報が不足している：詳細なログを有効にするには、LOCALSTACK_DEBUG=1 を指定して起動します
• Lambda の問題：エミュレーターのログと CloudWatch Logs の両方を確認します
• 断続的なエラー：リソース制限やタイミングの問題がないか確認します
• CLI レベルの問題：lstk config path が示すディレクトリ内の lstk.log を確認します