Merge pull request #226 from hjgraca/feat_support_high_resolution_metrics

feat: Support for High resolution metrics

Author: amirkaws

docs/core/metrics.md

@@ -10,16 +10,26 @@ These metrics can be visualized through [Amazon CloudWatch Console](https://aws.
 ## Key features
 
 * Aggregate up to 100 metrics using a single CloudWatch EMF object (large JSON blob)
-* Validate against common metric definitions mistakes (metric unit, values, max dimensions, max metrics, etc)
-* Metrics are created asynchronously by CloudWatch service, no custom stacks needed
+* Validating your metrics against common metric definitions mistakes (for example, metric unit, values, max dimensions, max metrics)
+* Metrics are created asynchronously by the CloudWatch service. You do not need any custom stacks, and there is no impact to Lambda function latency
 * Context manager to create a one off metric with a different dimension
 
+<br />
+
+<figure>
+  <img src="../../media/metrics_utility_showcase.png" loading="lazy" alt="Screenshot of the Amazon CloudWatch Console showing an example of business metrics in the Metrics Explorer" />
+  <figcaption>Metrics showcase - Metrics Explorer</figcaption>
+</figure>
+
 ## Terminologies
 
 If you're new to Amazon CloudWatch, there are two terminologies you must be aware of before using this utility:
 
-* **Namespace**. It's the highest level container that will group multiple metrics from multiple services for a given application, for example `MyCompanyEcommerce`.
+* **Namespace**. It's the highest level container that will group multiple metrics from multiple services for a given application, for example `ServerlessEcommerce`.
 * **Dimensions**. Metrics metadata in key-value format. They help you slice and dice metrics visualization, for example `ColdStart` metric by Payment `service`.
+* **Metric**. It's the name of the metric, for example: SuccessfulBooking or UpdatedBooking.
+* **Unit**. It's a value representing the unit of measure for the corresponding metric, for example: Count or Seconds.
+* **Resolution**. It's a value representing the storage resolution for the corresponding metric. Metrics can be either Standard or High resolution. Read more [here](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch_concepts.html#Resolution_definition).
 
 Visit the AWS documentation for a complete explanation for [Amazon CloudWatch concepts](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch_concepts.html).
 
@@ -130,6 +140,38 @@ You can create metrics using **`AddMetric`**, and you can create dimensions for
 !!! warning "Do not create metrics or dimensions outside the handler"
     Metrics or dimensions added in the global scope will only be added during cold start. Disregard if that's the intended behavior.
 
+### Adding high-resolution metrics
+
+You can create [high-resolution metrics](https://aws.amazon.com/about-aws/whats-new/2023/02/amazon-cloudwatch-high-resolution-metric-extraction-structured-logs/) passing `MetricResolution` as parameter to `AddMetric`.
+
+!!! tip "When is it useful?"
+    High-resolution metrics are data with a granularity of one second and are very useful in several situations such as telemetry, time series, real-time incident management, and others.
+
+=== "Metrics with high resolution"
+
+    ```csharp hl_lines="9 12 15"
+    using AWS.Lambda.Powertools.Metrics;
+
+    public class Function {
+           
+      [Metrics(Namespace = "ExampleApplication", Service = "Booking")]
+      public async Task<APIGatewayProxyResponse> FunctionHandler(APIGatewayProxyRequest apigProxyEvent, ILambdaContext context)
+      {
+        // Publish a metric with standard resolution i.e. StorageResolution = 60
+        Metrics.AddMetric("SuccessfulBooking", 1, MetricUnit.Count, MetricResolution.Standard);
+    
+        // Publish a metric with high resolution i.e. StorageResolution = 1
+        Metrics.AddMetric("FailedBooking", 1, MetricUnit.Count, MetricResolution.High);
+    
+        // The last parameter (storage resolution) is optional
+        Metrics.AddMetric("SuccessfulUpgrade", 1, MetricUnit.Count);
+      }
+    }
+    ```
+
+!!! tip "Autocomplete Metric Resolutions"
+    Use the `MetricResolution` enum to easily find a supported metric resolution by CloudWatch.
+
 ### Adding default dimensions
 
 You can use **`SetDefaultDimensions`** method to persist dimensions across Lambda invocations.

docs/media/metrics_utility_showcase.png

@@ -31,7 +31,8 @@ public interface IMetrics : IDisposable
     /// <param name="key">Metric key</param>
     /// <param name="value">Metric value</param>
     /// <param name="unit">Metric unit</param>
-    void AddMetric(string key, double value, MetricUnit unit);
+    /// <param name="metricResolution"></param>
+    void AddMetric(string key, double value, MetricUnit unit, MetricResolution metricResolution);
 
     /// <summary>
     ///     Adds a dimension
@@ -62,8 +63,9 @@ public interface IMetrics : IDisposable
     /// <param name="nameSpace">Metric namespace</param>
     /// <param name="service">Metric service</param>
     /// <param name="defaultDimensions">Metric default dimensions</param>
+    /// <param name="metricResolution">Metrics resolution</param>
     void PushSingleMetric(string metricName, double value, MetricUnit unit, string nameSpace = null,
-        string service = null, Dictionary<string, string> defaultDimensions = null);
+        string service = null, Dictionary<string, string> defaultDimensions = null, MetricResolution metricResolution = MetricResolution.Default);
 
     /// <summary>
     ///     Sets the namespace

libraries/src/AWS.Lambda.Powertools.Metrics/IMetrics.cs

@@ -81,11 +81,12 @@ internal Metrics(IPowertoolsConfigurations powertoolsConfigurations, string name
     /// <param name="key">Metric Key</param>
     /// <param name="value">Metric Value</param>
     /// <param name="unit">Metric Unit</param>
+    /// <param name="metricResolution">Metric resolution</param>
     /// <exception cref="System.ArgumentNullException">
     ///     'AddMetric' method requires a valid metrics key. 'Null' or empty values
     ///     are not allowed.
     /// </exception>
-    void IMetrics.AddMetric(string key, double value, MetricUnit unit)
+    void IMetrics.AddMetric(string key, double value, MetricUnit unit, MetricResolution metricResolution)
     {
         if (string.IsNullOrWhiteSpace(key))
             throw new ArgumentNullException(
@@ -98,7 +99,7 @@ void IMetrics.AddMetric(string key, double value, MetricUnit unit)
 
         if (_context.GetMetrics().Count == 100) _instance.Flush(true);
 
-        _context.AddMetric(key, value, unit);
+        _context.AddMetric(key, value, unit, metricResolution);
     }
 
     /// <summary>
@@ -231,19 +232,20 @@ public string Serialize()
     /// <param name="nameSpace">Metric Namespace</param>
     /// <param name="service">Service Name</param>
     /// <param name="defaultDimensions">Default dimensions list</param>
+    /// <param name="metricResolution">Metrics resolution</param>
     /// <exception cref="System.ArgumentNullException">
     ///     'PushSingleMetric' method requires a valid metrics key. 'Null' or empty
     ///     values are not allowed.
     /// </exception>
     void IMetrics.PushSingleMetric(string metricName, double value, MetricUnit unit, string nameSpace, string service,
-        Dictionary<string, string> defaultDimensions)
+        Dictionary<string, string> defaultDimensions, MetricResolution metricResolution)
     {
         if (string.IsNullOrWhiteSpace(metricName))
             throw new ArgumentNullException(
                 $"'PushSingleMetric' method requires a valid metrics key. 'Null' or empty values are not allowed.");
 
         using var context = InitializeContext(nameSpace, service, defaultDimensions);
-        context.AddMetric(metricName, value, unit);
+        context.AddMetric(metricName, value, unit, metricResolution);
 
         Flush(context);
     }
@@ -262,9 +264,11 @@ public void Dispose()
     /// <param name="key">Metric Key. Must not be null, empty or whitespace</param>
     /// <param name="value">Metric Value</param>
     /// <param name="unit">Metric Unit</param>
-    public static void AddMetric(string key, double value, MetricUnit unit = MetricUnit.None)
+    /// <param name="metricResolution"></param>
+    public static void AddMetric(string key, double value, MetricUnit unit = MetricUnit.None,
+        MetricResolution metricResolution = MetricResolution.Default)
     {
-        _instance.AddMetric(key, value, unit);
+        _instance.AddMetric(key, value, unit, metricResolution);
     }
 
     /// <summary>
@@ -336,10 +340,11 @@ private void Flush(MetricsContext context)
     /// <param name="nameSpace">Metric Namespace</param>
     /// <param name="service">Service Name</param>
     /// <param name="defaultDimensions">Default dimensions list</param>
+    /// <param name="metricResolution">Metrics resolution</param>
     public static void PushSingleMetric(string metricName, double value, MetricUnit unit, string nameSpace = null,
-        string service = null, Dictionary<string, string> defaultDimensions = null)
+        string service = null, Dictionary<string, string> defaultDimensions = null, MetricResolution metricResolution = MetricResolution.Default)
     {
-        _instance.PushSingleMetric(metricName, value, unit, nameSpace, service, defaultDimensions);
+        _instance.PushSingleMetric(metricName, value, unit, nameSpace, service, defaultDimensions, metricResolution);
     }
 
     /// <summary>

libraries/src/AWS.Lambda.Powertools.Metrics/Metrics.cs

@@ -82,9 +82,10 @@ internal void ClearNonDefaultDimensions()
     /// <param name="key">Metric key. Cannot be null, empty or whitespace</param>
     /// <param name="value">Metric value</param>
     /// <param name="unit">Metric Unit</param>
-    internal void AddMetric(string key, double value, MetricUnit unit)
+    /// <param name="metricResolution">Metric Resolution, Standard (default), High</param>
+    internal void AddMetric(string key, double value, MetricUnit unit, MetricResolution metricResolution)
     {
-        _metricDirective.AddMetric(key, value, unit);
+        _metricDirective.AddMetric(key, value, unit, metricResolution);
     }
 
     /// <summary>

libraries/src/AWS.Lambda.Powertools.Metrics/Model/Metadata.cs

@@ -28,7 +28,7 @@ public class MetricDefinition
     /// </summary>
     /// <param name="name">Metric name</param>
     /// <param name="value">Metric value</param>
-    public MetricDefinition(string name, double value) : this(name, MetricUnit.None, new List<double> {value})
+    public MetricDefinition(string name, double value) : this(name, MetricUnit.None, new List<double> {value}, MetricResolution.Default)
     {
     }
 
@@ -38,7 +38,8 @@ public class MetricDefinition
     /// <param name="name">Metric name</param>
     /// <param name="unit">Metric unit</param>
     /// <param name="value">Metric value</param>
-    public MetricDefinition(string name, MetricUnit unit, double value) : this(name, unit, new List<double> {value})
+    /// <param name="metricResolution">Metric resolution</param>
+    public MetricDefinition(string name, MetricUnit unit, double value, MetricResolution metricResolution) : this(name, unit, new List<double> {value}, metricResolution)
     {
     }
 
@@ -48,11 +49,13 @@ public class MetricDefinition
     /// <param name="name">Metric name</param>
     /// <param name="unit">Metric unit</param>
     /// <param name="values">List of metric values</param>
-    public MetricDefinition(string name, MetricUnit unit, List<double> values)
+    /// <param name="metricResolution">Metric resolution</param>
+    public MetricDefinition(string name, MetricUnit unit, List<double> values, MetricResolution metricResolution)
     {
         Name = name;
         Unit = unit;
         Values = values;
+        StorageResolution = metricResolution;
     }
 
     /// <summary>
@@ -75,6 +78,14 @@ public MetricDefinition(string name, MetricUnit unit, List<double> values)
     /// <value>The unit.</value>
     [JsonPropertyName(nameof(Unit))]
     public MetricUnit Unit { get; set; }
+    
+    /// <summary>
+    ///     Gets or sets the StorageResolution.
+    /// </summary>
+    /// <value>The unit.</value>
+    [JsonPropertyName(nameof(StorageResolution))]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)]
+    public MetricResolution StorageResolution { get; set; }
 
     /// <summary>
     ///     Adds value to existing metric with same key

libraries/src/AWS.Lambda.Powertools.Metrics/Model/MetricDefinition.cs

@@ -133,16 +133,17 @@ public List<List<string>> AllDimensionKeys
     /// <param name="name">Metric name. Cannot be null, empty or whitespace</param>
     /// <param name="value">Metric value</param>
     /// <param name="unit">Metric unit</param>
+    /// <param name="metricResolution">Metric Resolution, Standard (default), High</param>
     /// <exception cref="System.ArgumentOutOfRangeException">Metrics - Cannot add more than 100 metrics at the same time.</exception>
-    public void AddMetric(string name, double value, MetricUnit unit)
+    public void AddMetric(string name, double value, MetricUnit unit, MetricResolution metricResolution)
     {
         if (Metrics.Count < PowertoolsConfigurations.MaxMetrics)
         {
             var metric = Metrics.FirstOrDefault(m => m.Name == name);
             if (metric != null)
                 metric.AddValue(value);
             else
-                Metrics.Add(new MetricDefinition(name, unit, value));
+                Metrics.Add(new MetricDefinition(name, unit, value, metricResolution));
         }
         else
         {

libraries/src/AWS.Lambda.Powertools.Metrics/Model/MetricDirective.cs

@@ -0,0 +1,26 @@
+using System.Runtime.Serialization;
+using System.Text.Json.Serialization;
+
+namespace AWS.Lambda.Powertools.Metrics;
+
+/// <summary>
+/// Enum MetricResolution
+/// </summary>
+// [JsonConverter(typeof(StringEnumConverter))]
+public enum MetricResolution
+{
+    /// <summary>
+    ///     Standard resolution, with data having a one-minute granularity
+    /// </summary>
+    Standard = 60,
+
+    /// <summary>
+    ///     High resolution, with data at a granularity of one second
+    /// </summary>
+    High = 1,
+    
+    /// <summary>
+    /// When not set default to not sending metric resolution
+    /// </summary>
+    Default = 0
+}

libraries/src/AWS.Lambda.Powertools.Metrics/Model/MetricResolution.cs

@@ -83,9 +83,10 @@ internal void ClearNonDefaultDimensions()
     /// <param name="key">Metric key. Cannot be null, empty or whitespace</param>
     /// <param name="value">Metric value</param>
     /// <param name="unit">Metric unit</param>
-    public void AddMetric(string key, double value, MetricUnit unit)
+    /// <param name="metricResolution">Metric Resolution, Standard (default), High</param>
+    public void AddMetric(string key, double value, MetricUnit unit, MetricResolution metricResolution)
     {
-        _rootNode.AWS.AddMetric(key, value, unit);
+        _rootNode.AWS.AddMetric(key, value, unit, metricResolution);
     }
 
     /// <summary>

libraries/src/AWS.Lambda.Powertools.Metrics/Model/MetricsContext.cs

@@ -539,6 +539,90 @@ public void WhenMetricsWithSameNameAdded_ValidateMetricArray()
             // Reset
             handler.ResetForTest();
         }
+        
+        [Trait("Category", "MetricsImplementation")]
+        [Fact]
+        public void WhenMetricsWithStandardResolutionAdded_ValidateMetricArray()
+        {
+            // Arrange
+            var methodName = Guid.NewGuid().ToString();
+            var consoleOut = new StringWriter();
+            Console.SetOut(consoleOut);
+
+            var configurations = new Mock<IPowertoolsConfigurations>();
+
+            var logger = new Metrics(
+                configurations.Object,
+                nameSpace: "dotnet-powertools-test",
+                service: "testService"
+            );
+
+            var handler = new MetricsAspectHandler(
+                logger,
+                false
+            );
+
+            var eventArgs = new AspectEventArgs { Name = methodName };
+
+            // Act 
+            handler.OnEntry(eventArgs);
+            Metrics.AddDimension("functionVersion", "$LATEST");
+            Metrics.AddMetric("Time", 100.5, MetricUnit.Milliseconds, MetricResolution.Standard);
+            handler.OnExit(eventArgs);
+
+            var result = consoleOut.ToString();
+
+            // Assert
+            Assert.Contains("\"Metrics\":[{\"Name\":\"Time\",\"Unit\":\"Milliseconds\",\"StorageResolution\":60}]"
+                , result);
+            Assert.Contains("\"Time\":100.5"
+                , result);
+
+            // Reset
+            handler.ResetForTest();
+        }
+        
+        [Trait("Category", "MetricsImplementation")]
+        [Fact]
+        public void WhenMetricsWithHighResolutionAdded_ValidateMetricArray()
+        {
+            // Arrange
+            var methodName = Guid.NewGuid().ToString();
+            var consoleOut = new StringWriter();
+            Console.SetOut(consoleOut);
+
+            var configurations = new Mock<IPowertoolsConfigurations>();
+
+            var logger = new Metrics(
+                configurations.Object,
+                nameSpace: "dotnet-powertools-test",
+                service: "testService"
+            );
+
+            var handler = new MetricsAspectHandler(
+                logger,
+                false
+            );
+
+            var eventArgs = new AspectEventArgs { Name = methodName };
+
+            // Act 
+            handler.OnEntry(eventArgs);
+            Metrics.AddDimension("functionVersion", "$LATEST");
+            Metrics.AddMetric("Time", 100.5, MetricUnit.Milliseconds, MetricResolution.High);
+            handler.OnExit(eventArgs);
+
+            var result = consoleOut.ToString();
+
+            // Assert
+            Assert.Contains("\"Metrics\":[{\"Name\":\"Time\",\"Unit\":\"Milliseconds\",\"StorageResolution\":1}]"
+                , result);
+            Assert.Contains("\"Time\":100.5"
+                , result);
+
+            // Reset
+            handler.ResetForTest();
+        }
 
         #region Helpers