docs(logger): clarify Advanced Logging Controls interaction with sampling #7412

kattakaha · 2025-09-21T23:29:08Z

Issue number: closes #7220

Summary

Changes

This PR addresses documentation improvements for AWS Lambda Advanced Logging Controls (ALC) interaction with Powertools Logger sampling functionality. The changes clarify how Lambda's log level settings override Powertools configuration and provide clear guidance to avoid confusion.

Fix broken AWS Lambda ALC documentation link (line ~378)
Add warning callout in sampling section about ALC interaction
Clarify CDK applicationLogLevelV2 behavior with AWS_LAMBDA_LOG_LEVEL environment variable
Enhance priority section with concrete examples showing how Lambda's log level takes precedence

User experience

Before: Users were confused about the interaction between Lambda's Advanced Logging Controls and Powertools sampling settings, leading to unexpected behavior where sampling didn't work as expected when ALC was set to DEBUG level.

After: Users have clear documentation explaining:

How Lambda's log level settings override Powertools configuration
Why sampling may not work when ALC is set to DEBUG
How CDK's applicationLogLevelV2 automatically sets AWS_LAMBDA_LOG_LEVEL
The priority order of log level settings with concrete examples

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Disclaimer: We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.

…ling - Fix broken AWS Lambda ALC documentation link - Add warning about ALC interaction with log sampling - Clarify CDK applicationLogLevelV2 behavior with AWS_LAMBDA_LOG_LEVEL - Enhance priority section with concrete examples Fixes aws-powertools#7220

Copilot

Pull Request Overview

This PR improves documentation for AWS Lambda Advanced Logging Controls (ALC) interaction with Powertools Logger sampling functionality to reduce user confusion about unexpected logging behavior.

Fixed broken AWS Lambda ALC documentation link
Added warning about ALC interaction overriding sampling when log level is set to DEBUG
Enhanced priority section with concrete examples showing Lambda log level precedence over Powertools configuration

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

leandrodamascena · 2025-09-22T11:33:11Z

Hey @kattakaha thanks for sending this PR! At glance this PR looks ok, but I'll review this by the end of this week and work to get it merged! Thanks.

dreamorosi · 2025-09-25T16:30:18Z

@leandrodamascena friendly ping to remind you to review this tomorrow, if you can.

leandrodamascena

Hey @kattakaha! I just left some feedback before we merge it! Thanks so much for working on this.

leandrodamascena · 2025-09-26T08:39:47Z

docs/core/logger.md

+!!! info "AWS CDK and Advanced Logging Controls"
+    When using AWS CDK's `applicationLogLevelV2` parameter or setting log levels through the Lambda console, AWS automatically sets the `AWS_LAMBDA_LOG_LEVEL` environment variable. This means Lambda's log level takes precedence over Powertools configuration, potentially overriding both `POWERTOOLS_LOG_LEVEL` and sampling settings.
+
+    **Example**: If you set `applicationLogLevelV2=DEBUG` in CDK while having `POWERTOOLS_LOG_LEVEL=INFO`, the DEBUG level will be used because CDK automatically sets `AWS_LAMBDA_LOG_LEVEL=DEBUG` behind the scenes.


Suggested change

!!! info "AWS CDK and Advanced Logging Controls"

When using AWS CDK's `applicationLogLevelV2` parameter or setting log levels through the Lambda console, AWS automatically sets the `AWS_LAMBDA_LOG_LEVEL` environment variable. This means Lambda's log level takes precedence over Powertools configuration, potentially overriding both `POWERTOOLS_LOG_LEVEL` and sampling settings.

**Example**: If you set `applicationLogLevelV2=DEBUG` in CDK while having `POWERTOOLS_LOG_LEVEL=INFO`, the DEBUG level will be used because CDK automatically sets `AWS_LAMBDA_LOG_LEVEL=DEBUG` behind the scenes.

!!! info "AWS CDK and Advanced Logging Controls"

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.

**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.

leandrodamascena · 2025-09-26T08:40:20Z

docs/core/logger.md

+!!! warning "Interaction with AWS Lambda Advanced Logging Controls"
+    When using [AWS Lambda Advanced Logging Controls](#aws-lambda-advanced-logging-controls-alc) with log level set to `DEBUG` (e.g., via CDK's `applicationLogLevelV2` or Lambda console), sampling may not work as expected. Lambda's log level setting takes precedence and overrides Powertools configuration, potentially causing all DEBUG logs to appear regardless of your sampling rate. See the [priority order](#aws-lambda-advanced-logging-controls-alc) for more details.
+


Please remove this here as it creates another block of tips/warnings and may clutter the page.

leandrodamascena · 2025-09-26T08:41:28Z

docs/core/logger.md

 Use sampling when you want to dynamically change your log level to **DEBUG** based on a **percentage of the Lambda function invocations**.

 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.



Please add this new line here

AWS Lambda Advanced Logging Controls (ALC) settings can affect Sampling behavior. See how it works.

leandrodamascena

Please address the changes.

kattakaha · 2025-09-26T10:39:53Z

@leandrodamascena Thanks for the detailed feedback! I've addressed all the requested changes:

Updated the CDK example text to be more precise about Lambda setting the environment variable
Removed the warning block from the sampling section to avoid cluttering the page
Added a reference to ALC behavior in the sampling introduction

The documentation should now be clearer and less repetitive. Please let me know if anything else needs adjustment.

Copilot

Pull Request Overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 1 comment.

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

Copilot · 2025-09-26T10:40:33Z

docs/core/logger.md


    Example: Imagine an e-commerce checkout process where you want to understand rare payment gateway errors. With 10% sampling, you'll log detailed information for a small subset of transactions, making troubleshooting easier without generating excessive logs.

+


Remove the extra blank line at line 840. This creates unnecessary whitespace in the documentation.

Suggested change

- Update CDK example wording for precision - Remove warning block from sampling section - Add ALC reference to sampling introduction

sonarqubecloud · 2025-09-26T10:46:28Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

kattakaha · 2025-09-26T10:53:48Z

Sorry for the confusion with the commit history. I've recreated this PR with a cleaner commit structure. Please see the new PR: #7413

Copilot AI review requested due to automatic review settings September 21, 2025 23:29

kattakaha requested a review from a team as a code owner September 21, 2025 23:29

kattakaha requested a review from anafalcao September 21, 2025 23:29

pull-request-size bot added the size/S Denotes a PR that changes 10-29 lines, ignoring generated files. label Sep 21, 2025

boring-cyborg bot added the documentation Improvements or additions to documentation label Sep 21, 2025

Copilot AI reviewed Sep 21, 2025

View reviewed changes

leandrodamascena assigned kattakaha Sep 22, 2025

leandrodamascena added do-not-merge and removed do-not-merge labels Sep 22, 2025

dreamorosi requested a review from leandrodamascena September 25, 2025 16:30

leandrodamascena reviewed Sep 26, 2025

View reviewed changes

leandrodamascena requested changes Sep 26, 2025

View reviewed changes

kattakaha added 2 commits September 26, 2025 19:31

Merge branch 'develop' into fix/docs/logger#7220

ecfc3a9

docs(logger): improve Advanced Logging Controls documentation clarity

bb9e49b

kattakaha requested review from Copilot and leandrodamascena September 26, 2025 10:40

Copilot AI reviewed Sep 26, 2025

View reviewed changes

docs(logger): address PR review feedback

b49ada5

- Update CDK example wording for precision - Remove warning block from sampling section - Add ALC reference to sampling introduction

pull-request-size bot added size/L Denotes a PR that changes 100-499 lines, ignoring generated files. and removed size/S Denotes a PR that changes 10-29 lines, ignoring generated files. labels Sep 26, 2025

kattakaha closed this Sep 26, 2025

kattakaha deleted the fix/docs/logger#7220 branch September 26, 2025 10:53

kattakaha mentioned this pull request Sep 26, 2025

docs(logger): clarify Advanced Logging Controls interaction with sampling #7429

Merged

		!!! warning "Interaction with AWS Lambda Advanced Logging Controls"
		When using [AWS Lambda Advanced Logging Controls](#aws-lambda-advanced-logging-controls-alc) with log level set to `DEBUG` (e.g., via CDK's `applicationLogLevelV2` or Lambda console), sampling may not work as expected. Lambda's log level setting takes precedence and overrides Powertools configuration, potentially causing all DEBUG logs to appear regardless of your sampling rate. See the [priority order](#aws-lambda-advanced-logging-controls-alc) for more details.

		Use sampling when you want to dynamically change your log level to DEBUG based on a percentage of the Lambda function invocations.

		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.


		Example: Imagine an e-commerce checkout process where you want to understand rare payment gateway errors. With 10% sampling, you'll log detailed information for a small subset of transactions, making troubleshooting easier without generating excessive logs.

docs(logger): clarify Advanced Logging Controls interaction with sampling #7412

docs(logger): clarify Advanced Logging Controls interaction with sampling #7412

Uh oh!

Conversation

kattakaha commented Sep 21, 2025

Summary

Changes

User experience

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

leandrodamascena commented Sep 22, 2025

Uh oh!

dreamorosi commented Sep 25, 2025

Uh oh!

leandrodamascena left a comment

Choose a reason for hiding this comment

Uh oh!

leandrodamascena Sep 26, 2025

Choose a reason for hiding this comment

Uh oh!

kattakaha Sep 26, 2025

Choose a reason for hiding this comment

Uh oh!

leandrodamascena Sep 26, 2025

Choose a reason for hiding this comment

Uh oh!

kattakaha Sep 26, 2025

Choose a reason for hiding this comment

Uh oh!

leandrodamascena Sep 26, 2025

Choose a reason for hiding this comment

Uh oh!

kattakaha Sep 26, 2025

Choose a reason for hiding this comment

Uh oh!

leandrodamascena left a comment

Choose a reason for hiding this comment

Uh oh!

kattakaha commented Sep 26, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Copilot AI Sep 26, 2025

Choose a reason for hiding this comment

Uh oh!

sonarqubecloud bot commented Sep 26, 2025

Quality Gate passed

Uh oh!

kattakaha commented Sep 26, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants