Observability

Belt provides structured logging and CloudWatch metrics out of the box. These are initialized automatically by Belt::LambdaHandler — no setup required.

Logging

Access the logger from anywhere:

Belt::Observability::Logger.info("Order placed", order_id: "o-123", total: 49.99)
Belt::Observability::Logger.warn("Retry attempt", attempt: 3, service: "payments")
Belt::Observability::Logger.error("Payment failed", error: e.message, order_id: "o-123")

Logs are structured JSON, compatible with CloudWatch Logs Insights:

{
  "level": "INFO",
  "message": "Order placed",
  "order_id": "o-123",
  "total": 49.99,
  "timestamp": "2024-01-15T10:30:00Z",
  "service": "api"
}

Metrics

Track custom events via CloudWatch Embedded Metric Format (EMF):

Belt::Observability::Metrics.track_event("OrderCreated", model: "Order")
Belt::Observability::Metrics.track_event("PaymentProcessed", amount: 49.99)

Built-in Metrics

The Lambda handler automatically emits:

RequestCount — per invocation
ErrorCount — on unhandled exceptions
Latency — request duration in milliseconds

Namespace

Metrics are published under the namespace set by BELT_METRICS_NAMESPACE (defaults to Belt). View them in CloudWatch → Metrics → Custom namespaces.

Error Alerting

Set ERROR_NOTIFICATION_TOPIC_ARN to an SNS topic ARN. Unhandled errors will publish a notification with error details (message, backtrace, request context).

# config/lambda/api.yml
environment:
  ERROR_NOTIFICATION_TOPIC_ARN: ${var.sns_topic_arn}

CloudWatch Logs Insights

Query structured logs:

fields @timestamp, message, order_id
| filter level = "ERROR"
| sort @timestamp desc
| limit 20

Viewing Logs Locally

belt logs api              # tail logs for the "api" Lambda
belt logs api -f           # follow (live tail)
belt logs api -s 30m       # last 30 minutes
belt logs worker -e prod   # specific environment

Environment Variables

Variable	Purpose
`BELT_METRICS_NAMESPACE`	CloudWatch metrics namespace (default: `Belt`)
`ACTION`	Service name in log entries (falls back to function name)
`ERROR_NOTIFICATION_TOPIC_ARN`	SNS topic for error alerts
`ENVIRONMENT`	Controls verbose errors (`dev*`/`local`/`test` = verbose)