add support to clear custom dimensions

Mark Kuhn · Mark Kuhn · commit df44f055aa67 · 2022-09-13T17:11:56.000-07:00
diff --git a/README.md b/README.md
@@ -150,3 +150,121 @@ public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
   "Time": 189
 }
 ```
+
+## API
+
+### MetricsLogger
+
+The `MetricsLogger` is the interface you will use to publish embedded metrics.
+
+- MetricsLogger **PutMetric**(string key, double value, Unit unit)
+- MetricsLogger **PutMetric**(string key, double value)
+
+Adds a new metric to the current logger context. Multiple metrics using the same key will be appended to an array of values. The Embedded Metric Format supports a maxumum of 100 metrics per key.
+
+Units must meet CloudWatch Metrics unit requirements, if not it will default to None. See [MetricDatum](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_MetricDatum.html) for valid values.
+
+Example:
+
+```c#
+metrics.PutMetric("ProcessingLatency", 101, Unit.MILLISECONDS);
+```
+
+- MetricsLogger **PutProperty**(string key, object value)
+
+Adds or updates the value for a given property on this context. This value is not submitted to CloudWatch Metrics but is searchable by CloudWatch Logs Insights. This is useful for contextual and potentially high-cardinality data that is not appropriate for CloudWatch Metrics dimensions.
+
+Example:
+```c#
+metrics.PutProperty("AccountId", "123456789");
+metrics.PutProperty("RequestId", "422b1569-16f6-4a03-b8f0-fe3fd9b100f8");
+
+Dictionary<string, object> payLoad = new Dictionary<string, object>
+{
+  { "sampleTime", 123456789 },
+  { "temperature", 273.0 },
+  { "pressure", 101.3 }
+};
+metrics.PutProperty("Payload", payLoad);
+```
+
+- MetricsLogger **PutDimensions**(DimensionSet dimensions)
+
+Adds a new set of dimensions that will be associated with all metric values.
+
+**WARNING**: Each dimension set will result in a new CloudWatch metric (even dimension sets with the same values).
+If the cardinality of a particular value is expected to be high, you should consider
+using `setProperty` instead.
+
+Dimensions must meet CloudWatch Dimensions requirements. See [Dimensions](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_Dimension.html) for valid values.
+
+Example:
+
+```c#
+DimensionSet dimensionSet = new DimensionSet();
+dimensionSet.AddDimension("Service", "Aggregator");
+dimensionSet.AddDimension("Region", "us-west-2");
+metrics.PutDimensions(dimensionSet);
+```
+
+- MetricsLogger **SetDimensions**(params DimensionSet[] dimensionSets)
+- MetricsLogger **SetDimensions**(bool useDefault, params DimensionSet[] dimensionSets)
+
+Explicitly override all dimensions. This will remove the default dimensions unless `useDefault` is set to true.
+
+**WARNING**:Each dimension set will result in a new CloudWatch metric (even dimension sets with the same values).
+If the cardinality of a particular value is expected to be high, you should consider
+using `setProperty` instead.
+
+Dimensions must meet CloudWatch Dimensions requirements. See [Dimensions](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_Dimension.html) for valid values.
+
+Examples:
+  
+```c#
+DimensionSet dimensionSet = new DimensionSet();
+dimensionSet.AddDimension("Service", "Aggregator");
+dimensionSet.AddDimension("Region", "us-west-2");
+metrics.SetDimensions(true, dimensionSet); // Will preserve default dimensions
+```
+
+```c#
+DimensionSet dimensionSet = new DimensionSet();
+dimensionSet.AddDimension("Service", "Aggregator");
+dimensionSet.AddDimension("Region", "us-west-2");
+metrics.SetDimensions(dimensionSet); // Will remove default dimensions
+```
+
+- MetricsLogger **ResetDimensions**(bool useDefault)
+
+Explicitly clear all custom dimensions. Set `useDefault` to `true` to keep using the default dimensions.
+
+- MetricsLogger **SetNamespace**(string logNamespace)
+
+Sets the CloudWatch [namespace](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch_concepts.html#Namespace) that extracted metrics should be published to. If not set, a default value of aws-embedded-metrics will be used.
+
+Example:
+
+```c#
+SetNamespace("MyApplication")
+```
+
+- **Flush**()
+
+Flushes the current MetricsContext to the configured sink and resets all properties and metric values. The namespace and default dimensions will be preserved across flushes. Custom dimensions are preserved by default, but this behavior can be changed by setting `flushPreserveDimensions = false` on the metrics logger.
+
+Examples:
+
+```c#
+flush();  // default dimensions and custom dimensions will be preserved after each flush()
+```
+
+```c#
+logger.setFlushPreserveDimensions = false;
+flush();  // only default dimensions will be preserved after each flush()
+```
+
+```c#
+setFlushPreserveDimensions(false);
+resetDimensions(false);  // default dimensions are disabled; no dimensions will be preserved after each flush()
+flush();
+```
diff --git a/src/Amazon.CloudWatch.EMF/Logger/MetricsLogger.cs b/src/Amazon.CloudWatch.EMF/Logger/MetricsLogger.cs
@@ -11,6 +11,7 @@ namespace Amazon.CloudWatch.EMF.Logger
 {
     public class MetricsLogger : IMetricsLogger, IDisposable
     {
+        public bool FlushPreserveDimensions = true;
         private readonly ILogger _logger;
         private readonly IEnvironment _environment;
         private readonly IEnvironmentProvider _environmentProvider;
@@ -86,7 +87,7 @@ public void Flush()
             _logger.LogDebug("Sending data to sink. {}", _environment.Sink.GetType().Name);
 
             _environment.Sink.Accept(_context);
-            _context = _context.CreateCopyWithContext();
+            _context = _context.CreateCopyWithContext(this.FlushPreserveDimensions);
         }
 
         /// <summary>
@@ -133,6 +134,30 @@ public MetricsLogger SetDimensions(params DimensionSet[] dimensionSets)
             return this;
         }
 
+        /// <summary>
+        /// Overwrites all dimensions on this MetricsLogger instance; also overriding default dimensions unless useDefault is set to true
+        /// </summary>
+        /// <param name="useDefault">whether to use the default dimensions</param>
+        /// <param name="dimensionSets">the dimensionSets to set</param>
+        /// <returns>the current logger</returns>
+        /// <seealso cref="https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch_concepts.html#Dimension"/>
+        public MetricsLogger SetDimensions(bool useDefault, params DimensionSet[] dimensionSets)
+        {
+            _context.SetDimensions(useDefault, dimensionSets);
+            return this;
+        }
+
+        /// <summary>
+        /// Resets all dimensions on this MetricsLogger instance; also resetting default dimensions unless useDefault is set to true
+        /// </summary>
+        /// <param name="useDefault">whether to use the default dimensions</param>
+        /// <returns>the current logger</returns>
+        public MetricsLogger ResetDimensions(bool useDefault)
+        {
+            _context.ResetDimensions(useDefault);
+            return this;
+        }
+
         /// <summary>
         /// Puts a metric value.
         /// This value will be emitted to CloudWatch Metrics asynchronously and does
diff --git a/src/Amazon.CloudWatch.EMF/Model/MetricDirective.cs b/src/Amazon.CloudWatch.EMF/Model/MetricDirective.cs
@@ -109,17 +109,40 @@ internal void SetDimensions(List<DimensionSet> dimensionSets)
             CustomDimensionSets = dimensionSets;
         }
 
+        /// <summary>
+        /// Overrides all existing dimensions, optionally suppressing any default dimensions.
+        /// </summary>
+        /// <param name="useDefault">whether to use the default dimensions</param>
+        /// <param name="dimensionSets">the dimension sets to use in lieu of all existing custom and default dimensions</param>
+        internal void SetDimensions(bool useDefault, List<DimensionSet> dimensionSets)
+        {
+            _shouldUseDefaultDimensionSet = useDefault;
+            CustomDimensionSets = dimensionSets;
+        }
+
+        /// <summary>
+        /// Resets all dimensions to the default dimensions.
+        /// </summary>
+        /// <param name="useDefault">whether to keep the default dimensions</param>
+        internal void ResetDimensions(bool useDefault)
+        {
+            _shouldUseDefaultDimensionSet = useDefault;
+            CustomDimensionSets = new List<DimensionSet>();
+        }
+
         internal List<DimensionSet> GetAllDimensionSets()
         {
             if (!_shouldUseDefaultDimensionSet)
             {
                 return CustomDimensionSets;
             }
 
-            CustomDimensionSets.ForEach(ds => DefaultDimensionSet.AddRange(ds));
+            var dimensions = new DimensionSet();
+
+            dimensions.AddRange(this.DefaultDimensionSet);
+            CustomDimensionSets.ForEach(ds => dimensions.AddRange(ds));
 
-            var dimensions = new List<DimensionSet>() { DefaultDimensionSet };
-            return dimensions;
+            return new List<DimensionSet>() { dimensions };
         }
 
         internal MetricDirective DeepCloneWithNewMetrics(List<MetricDefinition> metrics)
diff --git a/src/Amazon.CloudWatch.EMF/Model/MetricsContext.cs b/src/Amazon.CloudWatch.EMF/Model/MetricsContext.cs
@@ -52,14 +52,15 @@ public MetricsContext(
         /// <summary>
         /// Creates a new MetricsContext with the same namespace, properties,
         /// and dimensions as this one but empty metrics-directive collection.
+        /// Custom dimensions are preserved by default unless preservedDimension is set to false
         /// </summary>
         /// <returns></returns>
-        public MetricsContext CreateCopyWithContext()
+        public MetricsContext CreateCopyWithContext(bool preserveDimensions = true)
         {
             return new MetricsContext(
                     _metricDirective.Namespace,
                     _rootNode.GetProperties(),
-                    _metricDirective.CustomDimensionSets,
+                    preserveDimensions ? _metricDirective.CustomDimensionSets : new List<DimensionSet>(),
                     _metricDirective.DefaultDimensionSet);
         }
 
@@ -189,6 +190,25 @@ public void SetDimensions(params DimensionSet[] dimensionSets)
             _metricDirective.SetDimensions(dimensionSets.ToList());
         }
 
+        /// <summary>
+        /// Update the dimensions to the specified list; optionally overriding default dimensions
+        /// </summary>
+        /// <param name="useDefault">whether to use default dimensions or not.</param>
+        /// <param name="dimensionSets">the dimensionSets to use instead of all existing dimensions and default dimensions.</param>
+        public void SetDimensions(bool useDefault, params DimensionSet[] dimensionSets)
+        {
+            _metricDirective.SetDimensions(useDefault, dimensionSets.ToList());
+        }
+
+        /// <summary>
+        /// Reset all dimensions
+        /// </summary>
+        /// <param name="useDefault">whether to keep default dimensions or not.</param>
+        public void ResetDimensions(bool useDefault)
+        {
+            _metricDirective.ResetDimensions(useDefault);
+        }
+
         /// <summary>
         /// Adds the specified key-value pair to the metadata.
         /// </summary>
diff --git a/tests/Amazon.CloudWatch.EMF.Tests/Logger/MetricsLoggerTests.cs b/tests/Amazon.CloudWatch.EMF.Tests/Logger/MetricsLoggerTests.cs
@@ -96,6 +96,50 @@ public void TestOverridePreviousDimensions()
             Assert.Equal(dimensionValue, _sink.MetricsContext.GetAllDimensionSets()[0].GetDimensionValue(dimensionName));
         }
 
+        [Fact]
+        public void SetDimensions_WithUseDefault_PreservesDefaultDimensions()
+        {
+            string dimensionName = "dim";
+            string dimensionValue = "dimValue";
+            string defaultDimName = "defaultDim";
+            string defaultDimValue = "defaultDimValue";
+
+            MetricsContext metricsContext = new MetricsContext();
+            metricsContext.DefaultDimensions.AddDimension(defaultDimName, defaultDimValue);
+            _metricsLogger = new MetricsLogger(_environment, metricsContext, _logger);
+
+            _metricsLogger.PutDimensions(new DimensionSet("foo", "bar"));
+            _metricsLogger.SetDimensions(true, new DimensionSet(dimensionName, dimensionValue));
+            _metricsLogger.Flush();
+
+            Assert.Single(_sink.MetricsContext.GetAllDimensionSets());
+            Assert.Equal(2, _sink.MetricsContext.GetAllDimensionSets()[0].DimensionKeys.Count);
+            ExpectDimension(dimensionName, dimensionValue);
+            ExpectDimension(defaultDimName, defaultDimValue);
+        }
+
+        [Fact]
+        public void SetDimensions_WithoutUseDefault_DoesNotPreserveDefaultDimensions()
+        {
+            string dimensionName = "dim";
+            string dimensionValue = "dimValue";
+            string defaultDimName = "defaultDim";
+            string defaultDimValue = "defaultDimValue";
+
+            MetricsContext metricsContext = new MetricsContext();
+            metricsContext.DefaultDimensions.AddDimension(defaultDimName, defaultDimValue);
+            _metricsLogger = new MetricsLogger(_environment, metricsContext, _logger);
+
+            _metricsLogger.PutDimensions(new DimensionSet("foo", "bar"));
+            _metricsLogger.SetDimensions(false, new DimensionSet(dimensionName, dimensionValue));
+            _metricsLogger.Flush();
+
+            Assert.Single(_sink.MetricsContext.GetAllDimensionSets());
+            Assert.Single(_sink.MetricsContext.GetAllDimensionSets()[0].DimensionKeys);
+            ExpectDimension(dimensionName, dimensionValue);
+            ExpectDimension(defaultDimName, null);
+        }
+
         [Fact]
         public void TestPutDuplicateDimensions()
         {
@@ -140,6 +184,32 @@ public void TestSetPutDuplicateDimensions()
             Assert.Equal(dimensionValue4, _sink.MetricsContext.GetAllDimensionSets()[1].GetDimensionValue(dimensionName3));
         }
 
+        [Theory]
+        [InlineData(true, 2)]
+        [InlineData(false, 1)]
+        public void ResetDimensions_ClearsDimensions(bool useDefault, int expectedDimensionSets)
+        {
+            string dimensionName1 = "dim";
+            string dimensionValue1 = "dimValue";
+            string dimensionName2 = "dim2";
+            string dimensionValue2 = "dimValue2";
+
+            MetricsContext metricsContext = new MetricsContext();
+            metricsContext.DefaultDimensions.AddDimension("foo", "bar");
+            _metricsLogger = new MetricsLogger(_environment, metricsContext, _logger);
+
+            _metricsLogger.PutDimensions(new DimensionSet(dimensionName1, dimensionValue1));
+            _metricsLogger.ResetDimensions(useDefault);
+            _metricsLogger.PutDimensions(new DimensionSet(dimensionName2, dimensionValue2));
+            _metricsLogger.Flush();
+
+            Assert.Single(_sink.MetricsContext.GetAllDimensionSets());
+            Assert.Equal(expectedDimensionSets, _sink.MetricsContext.GetAllDimensionSets()[0].DimensionKeys.Count);
+            Assert.Null(_sink.MetricsContext.GetAllDimensionSets()[0].GetDimensionValue(dimensionName1));
+            ExpectDimension(dimensionName2, dimensionValue2);
+            ExpectDimension(dimensionName1, null);
+        }
+
         [Fact]
         public void TestSetNameSpace()
         {
@@ -202,6 +272,33 @@ public void TestFlushWithDefaultDimensionDefined()
             ExpectDimension("LogGroup", null);
         }
 
+        [Fact]
+        public void SetFlushPreserveDimensions_ToFalse_DoesNotPreserveDimensions()
+        {
+            string dimensionName = "dim";
+            string dimensionValue = "val";
+            string defaultDim = "defaultDim";
+            string defaultDimValue = "defaultDimValue";
+
+            MetricsContext metricsContext = new MetricsContext();
+            metricsContext.DefaultDimensions.AddDimension(defaultDim, defaultDimValue);
+            MetricsLogger _metricsLogger1 = new MetricsLogger(_environment, metricsContext, _logger);
+
+            _metricsLogger1.PutDimensions(new DimensionSet(dimensionName, dimensionValue));
+            _metricsLogger1.FlushPreserveDimensions = false;
+            _metricsLogger1.Flush();
+
+            Assert.Equal(2, _sink.MetricsContext.GetAllDimensionSets()[0].DimensionKeys.Count);
+            ExpectDimension(dimensionName, dimensionValue);
+            ExpectDimension(defaultDim, defaultDimValue);
+
+            _metricsLogger1.Flush();
+
+            Assert.Single(_sink.MetricsContext.GetAllDimensionSets()[0].DimensionKeys);
+            ExpectDimension(dimensionName, null);
+            ExpectDimension(defaultDim, defaultDimValue);
+        }
+
         [Fact]
         public void TestPutMetricWithNoUnit()
         {
