DEV: add non-metric properties to metrics API.

README.md

@@ -539,7 +539,7 @@ Return a map containing the current sample definition.
 Convenience method that takes the channel as the first argument.
 
 
-#### metrics(channel: string, message: string, namespace: string, values: [], dimensions = [[]])
+#### metrics(channel: string, message: string, namespace: string, values: {}, dimensions = [], units = null, properties = {})
 
 Emit metrics in [CloudWatch EMF](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format_Specification.html) format.
 
@@ -551,7 +551,9 @@ The log format for metric messages will always be unformatted which is required
 
 The namespace is your unique custom namespace and usually consists of your name with service name. For example: 'MyCorp/App'.
 
-The values is an array of metric values to submit. Dimensions are the optional CloudWatch Metrics two-dimensional array of extra dimensions.
+The `values` is a map of metric values to submit. Dimensions are the optional CloudWatch Metrics array of dimensions. Units are the optional map of metric unit types. The `units` map may contain a `default` property that contains the default unit type to use.
+
+The `properties` are additional properties that are emitted, but not as metrics. They can be searched using SenseDeep or insights. These are useful for high-cardinality items that if emitted as metrics would incur significant CloudWatch metric costs.
 
 #### setFilter(filter: string | array)
 

src/index.d.ts

@@ -50,5 +50,5 @@ export default class SenseLogs {
     emit(chan: string, message: string, context?: {}): void;
 
     assert(truthy: any, message?: string | Error, context?: {}): void;
-    metrics(chan: string, message: string, namespace: string, values: {}, dimensions?: any[][], units?: {}): void;
+    metrics(chan: string, message: string, namespace: string, values: {}, dimensions?: string[], units?: null, properties?: {}): void;
 }

src/index.js

@@ -430,9 +430,11 @@ export default class SenseLogs {
     /*
         Emit a CloudWatch metic using the CloudWatch EMF format.
 
-        metrics(chan, message, 'MyCompany/MyApp', {UserSessions: 1}, dimensions, {UserSessions: 'Count'})
+        metrics(chan, message, 'MyCompany/MyApp', {UserSessions: 1}, dimensions, {UserSessions: 'Count'}, properties)
+        Dimensions are an array of dimension names. The values must be in `values`
+        Properties are additional properties that are not metrics, but are emitted. Useful for SenseDeep & insights.
     */
-    metrics(chan, message, namespace, values, dimensions = [[]], units = null) {
+    metrics(chan, message, namespace, values, dimensions = [], units = null, properties = {}) {
         let top = this.#top
         if (!top.#filter.metrics) {
             return
@@ -444,13 +446,14 @@ export default class SenseLogs {
         if (!this.enabled(chan, 1)) {
             return
         }
-        let keys = Object.keys(values).filter(v => dimensions[0].indexOf(v) < 0)
+        //  Get list of value keys that are not in dimensions. These are the metrics.
+        let keys = Object.keys(values).filter(v => dimensions.indexOf(v) < 0)
         let metrics = keys.map(name => {
             let def = {Name: name}
             if (units) {
                 let unit = units[name] || units.default
                 if (unit) {
-                    def.unit = unit
+                    def.Unit = unit
                 }
             }
             return def
@@ -463,12 +466,12 @@ export default class SenseLogs {
                 _aws: {
                     Timestamp: Date.now(),
                     CloudWatchMetrics: [{
-                        Dimensions: dimensions,
+                        Dimensions: [dimensions],
                         Namespace: namespace,
                         Metrics: metrics,
                     }]
                 },
-            }, values))
+            }, properties, values))
         }
         //  Write directly bypassing process and format()
         for (let {dest} of this.#top.#destinations) {