docs: clarify append_context_keys behavior with overlapping keys

[oyiz-michael]

Issue number: closes #7690

Summary

This PR clarifies the behavior of append_context_keys() when keys overlap with existing keys, addressing user confusion reported in #7690. This is a documentation-only fix that explains the current implementation without changing functionality.

Changes

• Updated docstrings in formatter.py and logger.py:

  • Added Warning section explaining that all keys added within the context are removed on exit
  • Clarified that overlapping keys lose their original values after context exit
  • Recommended using append_keys() for persistent keys

• Enhanced documentation in docs/core/logger.md:

  • Added prominent "danger" callout box explaining key collision behavior
  • Included concrete code example showing what happens when keys overlap
  • Demonstrates the issue: persistent key order_id="ORD-123" is lost after using append_context_keys(order_id="ORD-CHILD")

User experience

Before:

• Users expected Python context manager conventions (restore state on exit)
• Documentation said "temporarily add logging keys" without clarifying removal behavior
• When keys overlapped, original values were silently lost, breaking logging flows
• No guidance on avoiding key name collisions

After:

• Clear warnings in both code docstrings and user-facing documentation
• Concrete example showing the key collision problem
• Explicit recommendation: use append_keys() for persistent context, avoid overlapping key names with append_context_keys()
• Users understand this is current expected behavior, not a bug

---

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.

[leandrodamascena]

Thanks fir the PR @oyiz-michael!

APPROVED!

[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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.54%. Comparing base (ef3da99) to head (692022d).
⚠️ Report is 1 commits behind head on develop.

Additional details and impacted files

@@           Coverage Diff            @@
##           develop    #7846   +/-   ##
========================================
  Coverage    96.54%   96.54%           
========================================
  Files          275      275           
  Lines        13194    13194           
  Branches       999      999           
========================================
  Hits         12738    12738           
  Misses         353      353           
  Partials       103      103           

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

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.