feat(metrics): allow custom timestamps for metrics

[leandrodamascena]

Issue number: #3429

Summary

Changes

This pull request adds a functionality to allow custom dates instead of the current timestamp for Metrics EMF, while still retaining epoch time as expected value. Previously, only the current timestamp was used by default.

Questions

1 - Timestamp type

According to the AWS Documentation timestamp is a number representing the time stamp used for metrics extracted from the event. Values MUST be expressed as the number of milliseconds after Jan 1, 1970 00:00:00 UTC.

That said, should we only allow int inputs with epoch value, or should customers be able to pass datetime objects and have them converted internally? In our Datadog Metrtics provider we just allow int values.

2 - Invalid values
If a customer passes an invalid number, we will emit a warning and fallback to the current timestamp instead of raising an exception.

Update 26/03/2024

1 - Timestamp is either a Datetime object or an integer representing an epoch time.
2 - Any Datetime object will be converted into epoch time.
3 - The timestamp should not exceed 14 days in the past or be more than 2 hours in the future. Reference: Amazon CloudWatch Documentation
4 - If any metric fails to meet the requirements, a warning will be raised, and the metric will be flushed accordingly.
5 - We will not revert the timestamp to the current timestamp under any circumstances to prevent potential side effects.

User experience

import datetime
from aws_lambda_powertools import Metrics
from aws_lambda_powertools.metrics import MetricUnit
from aws_lambda_powertools.utilities.typing import LambdaContext

metrics = Metrics(namespace="Powertools")


@metrics.log_metrics 
def lambda_handler(event: dict, context: LambdaContext):
    metrics.add_metric(name="SuccessfulBooking", unit=MetricUnit.Count, value=1)

    # Calculate the metric timestamp as 2 days before the current time
    metric_timestamp = int((datetime.datetime.now() - datetime.timedelta(days=2)).timestamp() * 1000)
    metrics.set_timestamp(metric_timestamp)

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-commenter]

Codecov Report

Attention: Patch coverage is 87.87879% with 4 lines in your changes are missing coverage. Please review.

Project coverage is 96.25%. Comparing base (e14e768) to head (a36df37).
Report is 230 commits behind head on develop.

Files	Patch %	Lines
aws_lambda_powertools/metrics/base.py	66.66%	1 Missing and 1 partial ⚠️
aws_lambda_powertools/metrics/functions.py	88.88%	1 Missing and 1 partial ⚠️

❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #4006      +/-   ##
===========================================
- Coverage    96.38%   96.25%   -0.13%     
===========================================
  Files          214      215       +1     
  Lines        10030    10374     +344     
  Branches      1846     1925      +79     
===========================================
+ Hits          9667     9986     +319     
- Misses         259      275      +16     
- Partials       104      113       +9     

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

[leandrodamascena]

Hello everyone! This PR is ready for review. Here are some notes to facilitate the review process:

1 - Timestamp is either a Datetime object or an integer representing an epoch time.
2 - Any Datetime object will be converted into epoch time.
3 - The timestamp should not exceed 14 days in the past or be more than 2 hours in the future. Reference: Amazon CloudWatch Documentation
4 - If any metric fails to meet the requirements, a warning will be raised, and the metric will be flushed accordingly.
5 - We will not revert the timestamp to the current timestamp under any circumstances to prevent potential side effects.

@rubenfonseca I need your review here.

@dreamorosi considering your additional experience with metrics and EMF, I'd appreciate it if you could take a look at this PR and provide any thoughts or feedback you have.

[dreamorosi]

Left a comment about time zones, just want to make sure we are covering this aspect since we support it in other utilities.

Other than that, it looks great!

[rubenfonseca]

Reviewing now

[rubenfonseca]

I thing you're treating "ints" as seconds and converting "datetimes" to milliseconds. I believe everything needs to be milliseconds. Can you please check?

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
No data about Coverage
No data about Duplication

See analysis details on SonarCloud

[leandrodamascena]

I thing you're treating "ints" as seconds and converting "datetimes" to milliseconds. I believe everything needs to be milliseconds. Can you please check?

Thanks for the feedback @rubenfonseca! I've updated the documentation, docstring, and comments to make it clear that we expect epoch time in milliseconds.

Ready to review again.

[rubenfonseca]

Two small notes, feel free to ping me offline