feat(metrics): New metrics module implementation with support for Metrics providers and usage without annotations

[phipag]

Issue #, if available: #1848

Description of changes:

This PR re-implements the metrics module providing an interface fully owned by Powertools. It lays the foundation to support multiple Metrics providers in the future (see related TypeScript issue aws-powertools/powertools-lambda-typescript#1812).

This PR:

• Rewrites the metrics module decoupling the interface completely from the EMF library
  • In the future, we can remove the EMF dependency (will be separate work)
• Provides a fully working functional interface that allows using the utility without @Metrics annotation
  • Similar to .NET it supports the Builder pattern now using MetricsLoggerBuilder
• Updates documentation with new module and some additional hints and descriptions
• Adds more extensive unit tests covering 100% statements (only some partial if-branches are missed)
• Updates GraalVM metadata files with new interface and new unit tests using an updated tracing agent
  • I tested that this works in my AWS account

Documentation preview deployed here: https://dealn7fl31ram.cloudfront.net/core/metrics/

Checklist

• Meet tenets criteria
• Update tests
• Update docs
• PR title follows conventional commit semantics

Breaking change checklist

• Note: I will update the upgrade guide in the documentation in a separate PR. I would like to get a final version of this with feedback first.

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

[dreamorosi]

Thanks for the PR!

As discussed in the review session, let's address a few minor details around:

• supporting custom timestamps + validation
• removing service name dimension when not set
• aligning behavior on overwriting dimensions & metadata (wherever possible)
• considering changing name of single metric method to use the verb flush
• adding a section about testing your code (nice to have)

[phipag]

Hey @dreamorosi, thanks again for the in-depth review. I implemented your changes plus some additional things I found.

• If no Service is defined, we don't create the Service default dimension anymore
• Fail if not namespace is set instead of using EMF library default one
• Add custom Validators for Timestamp, namespace, and dimensions
• Update documentation with various changes and additional examples
• Add support for POWERTOOLS_METRICS_DISABLED environment variable
• Add example for adding high cardinality dimensions in documentation
• Update Maximum Dimensions to 30 according to EMF spec
• Accept a DimensionSet for addDimension and setDefaultDimensions methods instead of a generic Java Map
• Add support for FUNCTION_NAME environment variable
• Log a warning if metrics are empty and raiseOnEmptyMetrics is false
• Add support for specifying Timestamps using setTimestamp
• Rename @Metrics to @FlushMetrics and rename MetricsLogger to Metrics along with Factory and Builder
• Rename pushSingleMetric to flushSingleMetric
• Add Testing section into documentation
• Fix e2e tests

[phipag]

E2E tests pass without any changes in assertions: https://github.com/aws-powertools/powertools-lambda-java/actions/runs/15469183318

[dreamorosi]

I see we accepted a SonarQube finding around complexity, is there any way at all that we can break the logic down in smaller chunks? If not, then I'm ok to keep it.

[phipag]

I see we accepted a SonarQube finding around complexity, is there any way at all that we can break the logic down in smaller chunks? If not, then I'm ok to keep it.

3d02853

Sonar passes now.

[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

[phipag]

I also applied some changes to the GraalVM metadata files after renaming the MetricsLogger. 53d054d

[phipag]

Hey @dreamorosi, thanks again for your feedback. This PR is ready for review again.