Docs: Powertools Metrics behavior in Lambda environment

[just-boris]

What were you searching in the docs?

Currently, there is no documentation explaining how @aws-lambda-powertools/metrics (and other Powertools utilities) behave differently when running in actual Lambda environment as opposed to running the same code locally

This is important for two reasons:

1. Discoverability: Without documentation, users may not understand why metrics are correctly isolated in Lambda runtime or how the mechanism works. The current behavior feels like undocumented magic.

2. Unit testing guidance: Because Metrics behaves differently users need guidance on how to set up their test environments. Under the hood the powertools print metrics to the console logs. Is intercepting the console calls the way to test?

Is this related to an existing documentation section?

https://docs.aws.amazon.com/powertools/typescript/latest/features/metrics/

How can we improve?

• Explain that Powertools use @aws/lambda-invoke-store under the hood for better metrics instrumentation
• Describe that the invoke store is used automatically to provide per-invocation isolation — no code changes required.
• Provide some tips how to assert metrics emit in unit tests.

Got a suggestion in mind?

No response

Acknowledgment

• I understand the final update might be different from my proposed suggestion, or refused.