RFC: Metrics: Create a default dimension using the "service" name

[to-mc]

Key information

• RFC PR:
• Related issue(s), if known:
• Area: Metrics
• Meet tenets: Yes

Summary

Add a default dimension named "service" with a value of the provided service name if it exists (via Metrics constructor or env var).

Motivation

This would simplify what I think is the most common use case where users don't need multiple dimensions. It would enable creation of simple custom metrics without needing to think about the underlying CloudWatch dimension construct.

Proposal

With PR #60 the metrics interface was changed to behave more similarly to the other core utils, by accepting a service parameter or reading the POWERTOOLS_SERVICE_NAME env var. In the metrics util, this service is translated to the namespace used for metrics. We could also use this value to set a dimension by default: {"name": "service", "value": service_name}. This could be handled in the MetricManager constructor, by adding to the dimension_set dict if the service parameter is set.
This would remove the need to make a call to add_dimension, so the simplest implementation could look like:

metrics = Metrics(service="ServerlessAirline")

@metrics.log_metrics
def lambda_handler():
    # without this change we have to make a call to add dimensions here
    metrics.add_metric(name="Something", unit="Count", value=1)

Drawbacks

1. We would potentially create additional billable custom metrics for users who want specify their own dimensions.
2. The migration path is a bit awkward for anyone who is currently using the POWERTOOLS_SERVICE_NAME env var. Right now they are forced to use add_dimension, so they will start to see another dimension for all their metrics when they upgrade.

Rationale and alternatives

• What other designs have been considered? Why not them?
• What is the impact of not doing this?

Users of the library need to understand how CloudWatch metrics dimensions work. In my opinion this is quite hard to grasp from documentation. If we don't abstract this away by implementing this change, users who are not already familiar with CloudWatch can be faced with a time consuming trial/error cycle to discover how to properly use dimensions in their custom metrics. This is compounded by the fact that custom metrics can't be deleted - if mistakes are made here they will pollute the dashboard for 2 weeks until they expire.

Unresolved questions

Optional, stash area for topics that need further development e.g. TBD

[heitorlessa]

One area that might cause confusion is that namespace is used for the Application while dimension would be a service - e.g ServerlessAirline (namespace) and Payment (service dimension) In hindsight, I think we can ease the bar for entry by: 1. Updating the docs to explain how dimensions are typically used (not very different than other monitoring systems) 2. PR to AWS CW docs so we can point customers to too

…

On Sat, 6 Jun 2020 at 20:50, Tom McCarthy ***@***.***> wrote: Key information - RFC PR: - Related issue(s), if known: - Area: Metrics - Meet tenets <https://awslabs.github.io/aws-lambda-powertools-python/#tenets>: Yes Summary Add a default dimension named "service" with a value of the provided service name if it exists (via Metrics constructor or env var). Motivation This would simplify what I think is the most common use case where users don't need multiple dimensions. It would enable creation of simple custom metrics without needing to think about the underlying CloudWatch dimension construct. Proposal With PR #60 <#60> the metrics interface was changed to behave more similarly to the other core utils, by accepting a service parameter or reading the POWERTOOLS_SERVICE_NAME env var. In the metrics util, this service is translated to the namespace used for metrics. We could also use this value to set a dimension by default: {"name": "service", "value": service_name}. This could be handled in the MetricManager constructor, by adding to the dimension_set dict if the service parameter is set. This would remove the need to make a call to add_dimension, so the simplest implementation could look like: metrics = Metrics(service="ServerlessAirline") @metrics.log_metricsdef lambda_handler(): # without this change we have to make a call to add dimensions here metrics.add_metric(name="Something", unit="Count", value=1) Drawbacks 1. We would potentially create additional billable custom metrics for users who want specify their own dimensions. 2. The migration path is a bit awkward for anyone who is currently using the POWERTOOLS_SERVICE_NAME env var. Right now they are forced to use add_dimension, so they will start to see another dimension for all their metrics when they upgrade. Rationale and alternatives - *What other designs have been considered? Why not them?* - *What is the impact of not doing this?* Users of the library need to understand how CloudWatch metrics dimensions work. In my opinion this is quite hard to grasp from documentation. If we don't abstract this away by implementing this change, users who are not already familiar with CloudWatch can be faced with a time consuming trial/error cycle to discover how to properly use dimensions in their custom metrics. This is compounded by the fact that custom metrics can't be deleted - if mistakes are made here they will pollute the dashboard for 2 weeks until they expire. Unresolved questions Optional, stash area for topics that need further development e.g. TBD — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#61>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAZPQBBKVKSF7QVVJJMNG2DRVKMZBANCNFSM4NWKALWQ> .