Skip to content

Commit b8d52d2

Browse files
authored
docs(logger): clarify Advanced Logging Controls interaction with sampling (#7429)
* docs(logger): clarify Advanced Logging Controls interaction with sampling * docs(logger): fix broken AWS Lambda ALC documentation link
1 parent abd340e commit b8d52d2

File tree

1 file changed

+8
-1
lines changed

1 file changed

+8
-1
lines changed

docs/core/logger.md

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -375,7 +375,7 @@ If you want to access the numeric value of the current log level, you can use th
375375
When you want to set a logging policy to drop informational or verbose logs for one or all AWS Lambda functions, regardless of runtime and logger used.
376376

377377
<!-- markdownlint-disable MD013 -->
378-
With [AWS Lambda Advanced Logging Controls (ALC)](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-cloudwatchlogs.html#monitoring-cloudwatchlogs-advanced){target="_blank"}, you can enforce a minimum log level that Lambda will accept from your application code.
378+
With [AWS Lambda Advanced Logging Controls (ALC)](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-cloudwatchlogs-log-level.html#monitoring-cloudwatchlogs-log-level-setting){target="_blank"}, you can enforce a minimum log level that Lambda will accept from your application code.
379379

380380
When enabled, you should keep `Logger` and ALC log level in sync to avoid data loss.
381381

@@ -409,6 +409,11 @@ We prioritise log level settings in this order:
409409
2. Explicit log level in `Logger` constructor, or by calling the `logger.setLevel()` method
410410
3. `POWERTOOLS_LOG_LEVEL` environment variable
411411

412+
!!! info "AWS CDK and Advanced Logging Controls"
413+
When using AWS CDK's `applicationLogLevelV2` parameter or setting log levels through the Lambda console, AWS Lambda automatically sets the `AWS_LAMBDA_LOG_LEVEL` environment variable. This means Lambda's log level takes precedence over Powertools for AWS configuration, potentially overriding both `POWERTOOLS_LOG_LEVEL` and sampling settings.
414+
415+
**Example**: If you set `applicationLogLevelV2=DEBUG` in CDK while having `POWERTOOLS_LOG_LEVEL=INFO`, the DEBUG level will be used because Lambda automatically sets the environment variable `AWS_LAMBDA_LOG_LEVEL` to the debug level.
416+
412417
If you set `Logger` level lower than ALC, we will emit a warning informing you that your messages will be discarded by Lambda.
413418

414419
> **NOTE**
@@ -825,6 +830,8 @@ Use sampling when you want to dynamically change your log level to **DEBUG** bas
825830

826831
You can use values ranging from `0.0` to `1` (100%) when setting `POWERTOOLS_LOGGER_SAMPLE_RATE` env var, or `sampling_rate` parameter in Logger.
827832

833+
**AWS Lambda Advanced Logging Controls (ALC)** settings can affect Sampling behavior. See [how it works](#aws-lambda-advanced-logging-controls-alc).
834+
828835
???+ tip "Tip: When is this useful?"
829836
Log sampling allows you to capture debug information for a fraction of your requests, helping you diagnose rare or intermittent issues without increasing the overall verbosity of your logs.
830837

0 commit comments

Comments
 (0)