From 48fb8455f8acd0ffca0c73a4ecfaab8d732df369 Mon Sep 17 00:00:00 2001 From: Leandro Damascena Date: Wed, 28 Oct 2026 11:06:19 +0000 Subject: [PATCH] docs: explain how Logger, Metrics and Tracer telemetry shows up in CloudWatch Omni --- docs/core/logger.md | 18 ++++++++++++++++++ docs/core/metrics/index.md | 9 +++++++++ docs/core/tracer.md | 6 ++++++ 3 files changed, 33 insertions(+) diff --git a/docs/core/logger.md b/docs/core/logger.md index 8acc962ea96..1f60b9ff124 100644 --- a/docs/core/logger.md +++ b/docs/core/logger.md @@ -917,6 +917,24 @@ You can use import and use them as any other Logger formatter via `logger_format --8<-- "examples/logger/src/observability_provider_builtin_formatters.py" ``` +### CloudWatch Omni + +[CloudWatch Omni](https://aws.amazon.com/cloudwatch/omni/){target="_blank"} is the unified observability experience built on top of Amazon CloudWatch. It works on the telemetry you already send to CloudWatch, so there is nothing to configure in Logger: every log line goes to CloudWatch Logs as structured JSON and is available in your Omni space from there. + +What makes those lines useful in Omni is the shape Logger gives them. Each record is a single JSON object, and the [standard structured keys](#standard-structured-keys) are the fields you filter and correlate on: + +| Key | Set by | Use it to | +| --- | --- | --- | +| `service` | `Logger(service=...)` or `POWERTOOLS_SERVICE_NAME` | group logs of one service and tie them to the metrics emitted with the same `service` dimension | +| `correlation_id` | `inject_lambda_context(correlation_id_path=...)` or `set_correlation_id()` | follow one request across functions | +| `xray_trace_id` | automatically when tracing is active | jump from a log line to its X-Ray trace | +| `function_name`, `function_request_id`, `cold_start` | `inject_lambda_context` | slice by function, invocation and cold starts | + +Keys you add with `append_keys()` or as `extra` become fields too, so prefer stable, flat names such as `order_id` over nested or free-form values when you plan to query them. + +???+ tip "Keep `service` consistent across Logger, Metrics and Tracer" + Omni correlates logs, metrics and traces by service. Use the same value in `Logger(service=...)`, `Metrics(service=...)` and `Tracer(service=...)`, or set `POWERTOOLS_SERVICE_NAME` once for all three. + ### Migrating from other Loggers If you're migrating from other Loggers, there are few key points to be aware of: [Service parameter](#the-service-parameter), [Child Loggers](#child-loggers), [Overriding Log records](#overriding-log-records), and [Logging exceptions](#logging-exceptions). diff --git a/docs/core/metrics/index.md b/docs/core/metrics/index.md index e7d1e804df3..4bfbea99b6a 100644 --- a/docs/core/metrics/index.md +++ b/docs/core/metrics/index.md @@ -418,6 +418,15 @@ Current providers: | ---------------------------------------- | -------------------------------------------------------- | | [Datadog](./datadog.md){target="_blank"} | Uses Datadog SDK and Datadog Lambda Extension by default | +### CloudWatch Omni + +[CloudWatch Omni](https://aws.amazon.com/cloudwatch/omni/){target="_blank"} reads the same metrics you already publish to CloudWatch, so metrics emitted with this utility are available in your Omni space without changes. The EMF blob Metrics writes to the log is turned into CloudWatch metrics by the Lambda service, and those are what Omni dashboards and alerts use. + +Two things help on the Omni side: + +* Keep the `service` dimension set, through `Metrics(service=...)` or `POWERTOOLS_SERVICE_NAME`, and use the same value in Logger and Tracer. Omni correlates telemetry by service. +* Use the `namespace` and dimension names you would want to see in a query. Omni queries metrics by namespace and dimensions, the same way CloudWatch does. + ## Testing your code ### Setting environment variables diff --git a/docs/core/tracer.md b/docs/core/tracer.md index 2971e7db0dc..5eaac07c594 100644 --- a/docs/core/tracer.md +++ b/docs/core/tracer.md @@ -225,6 +225,12 @@ Tracer keeps a copy of its configuration after the first initialization. This is --8<-- "examples/tracer/src/tracer_reuse_module.py" ``` +### CloudWatch Omni + +Traces captured by Tracer go to AWS X-Ray, and X-Ray data is available in [CloudWatch Omni](https://aws.amazon.com/cloudwatch/omni/){target="_blank"} through Transaction Search. Omni's own instrumentation path is OpenTelemetry, which Tracer does not emit today; if you need OTLP traces from your function, follow [this feature request](https://github.com/aws-powertools/powertools-lambda-python/issues/7003){target="_blank"}. + +The `service` name you pass to Tracer is what ties your segments to the logs and metrics of the same service, so keep it aligned with Logger and Metrics. + ## Testing your code Tracer is disabled by default when not running in the AWS Lambda environment, including AWS SAM CLI and Chalice environments. This means no code changes or environment variables to be set.