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"

诊断日志

lstk 会将自身的诊断日志写入配置目录中的 lstk.log — 如果出问题的是 CLI 本身而非模拟器，这份日志会很有用：

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 会列出模拟器中当前已部署的资源；要回答“此资源是否存在？”，这通常比搜索日志更快：

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