fix(logger): correctly pick powertools or custom handler in custom environments

[leandrodamascena]

Original PR: #4295

Issue number: #4277

Summary

This PR fixes a bug when a compute environment or customer preconfigures a standard logging logger with the same Powertools logger name.

Previously, we'd always pick the first handler - child or parent. However, it led to pick the incorrect one if a logger we're creating for the first time (Logger) was already pre-setup through other means (logging.getLogger).

import logging
import os

from aws_lambda_powertools import Logger

service_name = os.getenv("POWERTOOLS_SERVICE_NAME")

# A environment, third-party library, or customer intentionally creates a logger with the same name as Powertools
# and add a Handler

logging.getLogger(service_name).addHandler(logging.StreamHandler())

logger = Logger(service=service_name)  # Powertools will ask standard logging to give the previously setup logger, then configure another handler etc as expected 

Changes

Please provide a summary of what's being changed

• Encapsulate handler selection in _get_handler
• Reverse depend registered_handler on _get_handler
• Logger with two handlers and log items use both of them
• The above with a child logger
• Add explicit test for orphaned child without handler that will fail with AttributeError
• Create a backwards compatible exception to provide actionable error on orphaned child formatter (e.g., child init before parent and append_keys)
• Update docs to clarify child logger and their caveats

User experience

Please share what the user experience looks like before and after this change

Checklist

If your change doesn't seem to apply, please leave them unchecked.

• Meet tenets criteria
• I have performed a self-review of this change
• Changes have been tested
• Changes are documented
• PR title follows conventional commit semantics

Is this a breaking change?

RFC issue number:

Checklist:

• Migration process documented
• Implement warnings (if it can live side by side)

Acknowledgment

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.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 96.26%. Comparing base (4ad37b5) to head (cdaef75).
Report is 2 commits behind head on develop.

Additional details and impacted files

@@           Coverage Diff            @@
##           develop    #6083   +/-   ##
========================================
  Coverage    96.25%   96.26%           
========================================
  Files          234      234           
  Lines        11147    11160   +13     
  Branches       824      828    +4     
========================================
+ Hits         10730    10743   +13     
  Misses         327      327           
  Partials        90       90           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[sonarqubecloud]

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