View a markdown version of this page

Observability - AWS CDK Blocks

Observability

This section covers AWS CDK Blocks for monitoring, logging, and tracing.

Choosing an observability Block

Block Best for Avoid when

Metrics

Custom application metrics with dimensions for filtering and aggregation

You only need request-level tracing (use Tracer)

Logger

Structured JSON logging with log levels and request context

You need numeric aggregation or alerting (use Metrics)

Tracer

Request tracing in your backend code, latency analysis

You only need simple log output (use Logger)

Dashboard

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.