use async local storage for metrics

Author: svozza

.github/scripts/release_patch_package_json.js

@@ -88,6 +88,6 @@ const betaPackages = [];
 
   // Temporarily update the original package.json file.
   // This version will be picked up during the `npm publish` step, so that
-  // the version number and metadata in the registry are correct and match the tarball.
+  // the version number and #metadata in the registry are correct and match the tarball.
   writeFileSync('package.json', JSON.stringify(newPkgJson, null, 2));
 })();

.github/workflows/layers_partitions.yml

@@ -84,7 +84,7 @@ jobs:
           echo regions='["us-gov-east-1", "us-gov-west-1"]'>> "$GITHUB_OUTPUT"
           echo partition='aws-us-gov'>> "$GITHUB_OUTPUT"
           echo aud='sts.amazonaws.com'>> "$GITHUB_OUTPUT"
-  # This job downloads the specified layer version from the main AWS partition (us-east-1) and stores both the layer zip file and metadata as GitHub Actions artifacts for use in deployment.
+  # This job downloads the specified layer version from the main AWS partition (us-east-1) and stores both the layer zip file and #metadata as GitHub Actions artifacts for use in deployment.
   download:
     runs-on: ubuntu-latest
     permissions:
@@ -178,7 +178,7 @@ jobs:
             --action lambda:GetLayerVersion \
             --principal '*' \
             --version-number "$LAYER_VERSION"
-      # This step retrieves the newly deployed layer metadata and compares it against the original source layer:
+      # This step retrieves the newly deployed layer #metadata and compares it against the original source layer:
       # 1. SHA256 hash verification - ensures the layer content is identical to the source
       # 2. Description validation - confirms the version number in the description matches the source
       # 3. Layer Version number verification - validates that the layer version numbers match between source and target

examples/snippets/tracer/captureMethodManual.ts

@@ -12,12 +12,12 @@ const getChargeId = async (): Promise<unknown> => {
   try {
     const res = { chargeId: '1234' };
 
-    // Add the response as metadata
+    // Add the response as #metadata
     tracer.addResponseAsMetadata(res, 'chargeId');
 
     return res;
   } catch (err) {
-    // Add the error as metadata
+    // Add the error as #metadata
     tracer.addErrorAsMetadata(err as Error);
     throw err;
   } finally {

examples/snippets/tracer/manual.ts

@@ -20,10 +20,10 @@ export const handler = async (
   tracer.addServiceNameAnnotation();
 
   try {
-    // Add the response as metadata
+    // Add the response as #metadata
     tracer.addResponseAsMetadata({}, process.env._HANDLER);
   } catch (err) {
-    // Add the error as metadata
+    // Add the error as #metadata
     tracer.addErrorAsMetadata(err as Error);
     throw err;
   } finally {

package-lock.json

@@ -80,7 +80,7 @@ type ConsumerRecord<K, V> = {
 };
 
 /**
- * Represents a collection of Kafka consumer records, along with MSK event metadata.
+ * Represents a collection of Kafka consumer records, along with MSK event #metadata.
  */
 type ConsumerRecords<K = unknown, V = unknown> = {
   /**

packages/kafka/src/types/types.ts

@@ -88,7 +88,8 @@
     "url": "https://github.com/aws-powertools/powertools-lambda-typescript/issues"
   },
   "dependencies": {
-    "@aws-lambda-powertools/commons": "2.27.0"
+    "@aws-lambda-powertools/commons": "2.27.0",
+    "@aws/lambda-invoke-store": "0.1.0"
   },
   "keywords": [
     "aws",

packages/metrics/package.json

@@ -0,0 +1,68 @@
+import { InvokeStore } from '@aws/lambda-invoke-store';
+import type { Dimensions } from './types/Metrics.js';
+
+/**
+ * Manages storage of metrics dimensions with automatic context detection.
+ *
+ * This class abstracts the storage mechanism for metrics, automatically
+ * choosing between AsyncLocalStorage (when in async context) and a fallback
+ * object (when outside async context). The decision is made at runtime on
+ * every method call to support Lambda's transition to async contexts.
+ */
+class DimensionsStore {
+  #fallbackDimensions: Dimensions = {};
+  #fallbackDimensionSets: Dimensions[] = [];
+
+  #getDimensions(): Dimensions {
+    if (InvokeStore.getContext() === undefined) {
+      return this.#fallbackDimensions;
+    }
+
+    let stored = InvokeStore.get('dimensions') as Dimensions | undefined;
+    if (stored == null) {
+      stored = {};
+      InvokeStore.set('dimensions', stored);
+    }
+    return stored;
+  }
+
+  #getDimensionSets(): Dimensions[] {
+    if (InvokeStore.getContext() !== undefined) {
+      let stored = InvokeStore.get('dimensionSets') as Dimensions[] | undefined;
+      if (stored == null) {
+        stored = [];
+        InvokeStore.set('dimensionSets', stored);
+      }
+      return stored;
+    }
+    return this.#fallbackDimensionSets;
+  }
+
+  addDimension(name: string, value: string): void {
+    this.#getDimensions()[name] = value;
+  }
+
+  addDimensionSet(dimensionSet: Dimensions): void {
+    this.#getDimensionSets().push({ ...dimensionSet });
+  }
+
+  getDimensions(): Dimensions {
+    return { ...this.#getDimensions() };
+  }
+
+  getDimensionSets(): Dimensions[] {
+    return this.#getDimensionSets().map((set) => ({ ...set }));
+  }
+
+  clear(): void {
+    if (InvokeStore.getContext() !== undefined) {
+      InvokeStore.set('dimensions', {});
+      InvokeStore.set('dimensionSets', []);
+    } else {
+      this.#fallbackDimensions = {};
+      this.#fallbackDimensionSets = [];
+    }
+  }
+}
+
+export { DimensionsStore };

packages/metrics/src/DimensionsStore.ts

@@ -0,0 +1,46 @@
+import { InvokeStore } from '@aws/lambda-invoke-store';
+
+/**
+ * Manages storage of metrics #metadata with automatic context detection.
+ *
+ * This class abstracts the storage mechanism for metrics, automatically
+ * choosing between AsyncLocalStorage (when in async context) and a fallback
+ * object (when outside async context). The decision is made at runtime on
+ * every method call to support Lambda's transition to async contexts.
+ */
+class MetadataStore {
+  #fallbackStorage: Record<string, string> = {};
+
+  #getStorage(): Record<string, string> {
+    if (InvokeStore.getContext() === undefined) {
+      return this.#fallbackStorage;
+    }
+
+    let stored = InvokeStore.get('#metadata') as
+      | Record<string, string>
+      | undefined;
+    if (stored == null) {
+      stored = {};
+      InvokeStore.set('#metadata', stored);
+    }
+    return stored;
+  }
+
+  public set(key: string, value: string): void {
+    this.#getStorage()[key] = value;
+  }
+
+  public getAll(): Record<string, string> {
+    return { ...this.#getStorage() };
+  }
+
+  public clear(): void {
+    if (InvokeStore.getContext() !== undefined) {
+      InvokeStore.set('#metadata', {});
+    } else {
+      this.#fallbackStorage = {};
+    }
+  }
+}
+
+export { MetadataStore };