feat(metrics): support high resolution metrics

[niko-achilles]

Description of your changes

introduction of type MetricResolution for Metrics .
to the type MetricResolution are assignable only the values 1 and 60, which mean High and Standard , respecting the EMF Documentation.
addMetrics signature guides the developer to use the resolution of Metric as an optional parameter.
default metric resolution value is 60 , which means 1 minute.
developer is guided at compile time and only the values 1 and 60 can be applied to the metric resolution type.
serialized metrics include the StorageResolution as key , respecting the EMF Documentation.
stored metrics include the resolution of metric as part of the metric definition name, unit, resolution, respecting the EMF Documentation.

How to verify this change

a new test is written in Metrics.test.ts that exercises the type of Metric Resolution
a concept test is also written to compare the DX, type of metric resolution as const vs as enum .
failing tests extended to include the StorageResolution as key , respecting the EMF Documentation.

Related issues, RFCs

Issue number: #1277

Checklist

• My changes meet the tenets criteria
• I have performed a self-review of my own code
• I have commented my code where necessary, particularly in areas that should be flagged with a TODO, or hard-to-understand areas
• I have made corresponding changes to the documentation
• I have made corresponding changes to the examples
• My changes generate no new warnings
• The code coverage hasn't decreased
• I have added tests that prove my change is effective and works
• New and existing unit tests pass locally and in Github Actions
• Any dependent changes have been merged and published
• The PR title follows the conventional commit semantics

Breaking change checklist

Is it a breaking change?: NO

• I have documented the migration process
• I have added, implemented necessary warnings (if it can live side by side)

---

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.

[niko-achilles]

@dreamorosi this is a first PR Iteration, please play with the type MetricResolution , let me know what is preferable readonly const as type or enum. Concept test to play with is also inluded.

@dreamorosi , @heitorlessa , @leandrodamascena
this PR is a first iteration introducing Metric Resolution , first new test + existing tests are extended to know about the resolution, green bar TDD approach .
Feature is not completed yet . i need to write more test cases and by having tests as guide , i can apply behavior to Metrics correspondently.

[niko-achilles]

added equivalent partitions to the test for addMetric with metric resolution.
equivalent partitions : [standard], [60], [High], [1]

other partitions can not be created and used in tests , because MetricResolution Type by design does not allow other values than : [standard], [60], [High], [1]

[niko-achilles]

introduced tests and use case to support EMF Schema , which specifies StorageResolution as not required property:

• If a value is not provided for Metric Resolution, then StorageResolution property is not included as EMF output.

extended function serializeMetrics to support this use case

@dreamorosi , @heitorlessa and @leandrodamascena with this added use case and test i assume the metrics behavior to be complete . Expecting further guidance if needed for exercising further the Metrics behavior.

@dreamorosi if behavior looks good , please provide hints for documentation and examples that should demonstrate and guide a developer as powertools user how to use Metric Resolution .

[dreamorosi]

Great work so far, I have left a few comments here & there and all about style.

After addressing the comments please feel free to move onto proposing a change to documentation.

I think we should update this section (see corresponding section in Python) and add a new section + code snippet like this one from Python.

[niko-achilles]

@dreamorosi ok, with the link sections provided in your comment above, i am able to continue the work on the documentation for the Documentation Website and snippets of code .

In context of docs as comments in typescript code with IDE support, that can be considered as part of documentation unit of work , is the following i found a good reference ? Any tsdoc recommendations for the optional type metric resolution in add metric method , given is the only method exposed public with metric resolution in signature ?

• Reference python comments in code: in python code base, resolution of metric as example comments for public methods, e.g addMetric , exposed for usage by devs in IDE .

The motivation of question is to introduce together for consistency reasons

• docs for website, comments in code of typescript with snippet examples,
• comments of code in metrics package with IDE support

[dreamorosi]

I see what you mean.

The addMetric method doesn't have a great doc string and it could be improved. You can propose a new one in this PR if you'd like. If not we'll probably have to review all of the ones in the Metrics class at some point soon.

[niko-achilles]

Andreas this commit was an opportunity in context of unifying the docs for website, code snippet and code comments in package of metrics to refactor the code of Metrics in spaces where MetricResolution plays a behavioral role.

In summary :

• Website docs are similar to python website docs for adding a Metric with high resolution .
• Code snippet for add a high resolution metric is introduced
• addMetric Method introduces documentation in IDE with @example @param and @see comments
• serializeMetrics improvement with comments and IDE support
• code refactoring in serializeMetrics , introduction of MetricDefinition as explicit type for constructing an object for metric to be serialized as emf.
• type guard technique from typescript introduced, method private isHigh to verify if a stored metric in internal buffer impl. is of resolution High
• re-usage of Stored Metric Type in Metrics class.
• avoid unnecessary ingestion of data into cloudwatch, only if the metric is defined as isHigh the StorageResolution is serialized in EmfOutput . Because cloudwatch will assume resolution of standard if property of Storage Resolution is not present , hence optional defined from aws in schema spec.
• test in green state , refactoring is rolled out with jest running without stopping and applying refactoring ins steps

// avoid unnecessary ingestion of data into cloudwatch is implemented after reading the python implementation so mentioning @heitorlessa and @leandrodamascena

    // For high-resolution metrics, add StorageResolution property
    // Example: [ { "Name": "metric_name", "Unit": "Count", "StorageResolution": 1 } ]

    // For standard resolution metrics, don't add StorageResolution property to avoid unnecessary ingestion of data into cloudwatch
    // Example: [ { "Name": "metric_name", "Unit": "Count"} ]

[dreamorosi]

Thank you for working on this feature Niko, appreciate the help!

Let's merge it!