Observability
This section covers AWS CDK Blocks for monitoring, logging, and tracing.
Choosing an observability Block
| Block | Best for | Avoid when |
|---|---|---|
|
|
Custom application metrics with dimensions for filtering and aggregation |
You only need request-level tracing (use Tracer) |
|
|
Structured JSON logging with log levels and request context |
You need numeric aggregation or alerting (use Metrics) |
|
|
Request tracing in your backend code, latency analysis |
You only need simple log output (use Logger) |
|
|
A prebuilt view of compute health, logs, traces, and the metrics you choose |
You need custom charts or interactive data exploration (use the CloudWatch console) |
Metrics
Custom application metrics. Emit named metric data points with dimensions for filtering and aggregation. Supports child emitters with merged dimensions for scoped metric contexts. Uses CloudWatch Embedded Metric Format to emit metrics.
Locally, Metrics writes to the console. On AWS, metrics flow to Amazon CloudWatch. Best for tracking business KPIs, API latencies, error rates, and custom application counters.
For more information, see bb-metrics on GitHub
Logger
Structured JSON logging with levels and contextual metadata. Supports debug, info, warn, and error levels. Attach arbitrary metadata to log entries for filtering and analysis.
Locally, Logger writes to the console. On AWS, structured JSON flows to CloudWatch Logs. Each entry includes the X-Ray trace ID (traceId) when Lambda provides one. To tag entries with a request ID or other context, create a child logger with log.child({ requestId }). Best for application logging with searchable structured data.
For more information, see bb-logger on GitHub
Tracer
Distributed request tracing. Wrap operations in traced segments to visualize request flow across your application. Add searchable annotations for debugging and add metadata for detailed inspection.
Locally, Tracer records traces to files in the .bb-data/ directory for inspection. On AWS, it records segments in AWS X-Ray. Adding a Tracer turns on X-Ray active tracing for every compute Lambda function in the app, unless you set enabled: false. X-Ray bills per trace. Helper functions, such as database migrations, are not traced. Only Lambda functions are traced. API Gateway stage tracing is not turned on. Best for debugging latency issues and understanding request paths in production.
For more information, see bb-tracer on GitHub
Dashboard
Auto-generated CloudWatch dashboard. It works without any other observability CDK Block: each compute in your app gets a health section and a logs section. A traces section appears when the app has an enabled Tracer. To chart your own metrics, pass a Metrics Block and list the metric names in metricConfigs. Dashboard does not create alarms.
Locally, Dashboard is not available; its route responds with a message directing you to deploy. On AWS, it provisions a CloudWatch Dashboard with those sections, and its route (/aws-blocks/dashboard by default) redirects to the dashboard in the CloudWatch console. Best for teams that want out-of-the-box monitoring without manual dashboard setup.
For more information, see bb-dashboard on GitHub