docs: update template & functions

Author: dreamorosi

examples/cdk/functions/commons/constants.ts

@@ -2,6 +2,5 @@ import { getStringFromEnv } from '#helpers/utils';
 
 // Get the DynamoDB table name from environment variables
 const itemsTableName = getStringFromEnv('TABLE_NAME');
-const ssmParameterName = getStringFromEnv('SSM_PARAMETER_NAME');
 
-export { itemsTableName, ssmParameterName };
+export { itemsTableName };

examples/cdk/functions/process-items-stream.ts

@@ -1,9 +1,13 @@
+import { assertIsError } from '#helpers/utils';
 import { logger } from '#powertools/logger';
+import { tracer } from '#powertools/tracer';
 import {
   BatchProcessor,
   EventType,
   processPartialResponse,
 } from '@aws-lambda-powertools/batch';
+import type { AttributeValue } from '@aws-sdk/client-dynamodb';
+import { unmarshall } from '@aws-sdk/util-dynamodb';
 import type {
   Context,
   DynamoDBBatchResponse,
@@ -23,37 +27,46 @@ const processor = new BatchProcessor(EventType.DynamoDBStreams);
  * @param record The DynamoDB record to process
  */
 const recordHandler = async (record: DynamoDBRecord): Promise<void> => {
+  logger.debug('processing record', { record });
+  const subsegment = tracer
+    .getSegment()
+    ?.addNewSubsegment('#### recordHandler');
   try {
     if (record.dynamodb && record.dynamodb.NewImage) {
-      const message = record.dynamodb.NewImage.Message?.S;
-      if (message) {
-        const payload = JSON.parse(message) as { id: string; name: string };
-        // Add itemId to the logger so that it's included in every log message
-        logger.appendKeys({ itemId: payload.id });
+      const payload = unmarshall(
+        record.dynamodb.NewImage as { [key: string]: AttributeValue }
+      );
 
-        const query = new URLSearchParams();
-        query.set('name', payload.name);
+      // Add itemId to the logger so that it's included in every log message
+      logger.appendKeys({ itemId: payload.id });
+      // Also add it to the subsegment, so you can search for traces by itemId
+      subsegment?.addAnnotation('itemId', payload.id);
 
-        const remoteUrl = `https://httpbin.org/anything?${query.toString()}`;
-        logger.debug('sending request', { remoteUrl });
+      const query = new URLSearchParams();
+      query.set('name', payload.name);
 
-        // This request doesn't show up in the trace yet, see #1619 for updates
-        const response = await fetch(remoteUrl);
-        // If the request was successful, the response.ok property will be true
-        equal(response.ok, true);
+      const remoteUrl = `https://httpbin.org/anything?${query.toString()}`;
+      logger.debug('sending request', { remoteUrl });
 
-        logger.debug('request completed', {
-          response: await response.json(),
-          status: response.status,
-        });
-      }
+      // This request doesn't show up in the trace yet, see #1619 for updates
+      const response = await fetch(remoteUrl);
+      // If the request was successful, the response.ok property will be true
+      equal(response.ok, true);
+
+      logger.debug('request completed', {
+        response: await response.json(),
+        status: response.status,
+      });
     }
   } catch (error) {
-    logger.error('error processing record', { error });
+    assertIsError(error);
+    logger.error('error processing record', error);
+    subsegment?.addError(error, true);
 
     throw error;
   } finally {
     logger.removeKeys(['itemId']);
+    subsegment?.close();
   }
 };
 
@@ -62,10 +75,24 @@ const recordHandler = async (record: DynamoDBRecord): Promise<void> => {
  *
  * The functions uses the `processPartialResponse` function from the `@aws-lambda-powertools/batch` package
  * to process the records in parallel using the `recordHandler` function.
+ *
+ * The `processPartialResponse` is wrapped in a `tracer.provider.captureAsyncFunc` to ensure that the whole
+ * process is captured in a single trace.
  */
 export const handler = async (
   event: DynamoDBStreamEvent,
   context: Context
 ): Promise<DynamoDBBatchResponse> => {
-  return processPartialResponse(event, recordHandler, processor, { context });
+  return tracer.provider.captureAsyncFunc('### handler', async (segment) => {
+    const result = await processPartialResponse(
+      event,
+      recordHandler,
+      processor,
+      { context }
+    );
+
+    segment?.close();
+
+    return result;
+  }) as DynamoDBBatchResponse;
 };

examples/cdk/functions/put-item.ts

@@ -1,7 +1,7 @@
-import { ssmParameterName } from '#constants';
+import { ddbClient } from '#clients/dynamodb';
 import { getSSMStringParameter } from '#helpers/get-string-param';
 import { putItemInDynamoDB } from '#helpers/put-item';
-import { assertIsError } from '#helpers/utils';
+import { assertIsError, getStringFromEnv } from '#helpers/utils';
 import { logger, metrics, tracer } from '#powertools';
 import {
   IdempotencyConfig,
@@ -17,12 +17,15 @@ import type {
 import type { Subsegment } from 'aws-xray-sdk-core';
 
 // Initialize the persistence store for idempotency
+const ssmParameterName = getStringFromEnv('SSM_PARAMETER_NAME');
 const persistenceStore = new DynamoDBPersistenceLayer({
   tableName: await getSSMStringParameter(ssmParameterName),
+  // Pass DynamoDB client, so we can trace the calls
+  awsSdkV3Client: ddbClient,
 });
 // Define the idempotency configuration
 const idempotencyConfig = new IdempotencyConfig({
-  useLocalCache: true,
+  useLocalCache: false,
   maxLocalCacheSize: 500,
   expiresAfterSeconds: 60 * 60 * 24,
 });

examples/cdk/src/example-stack.ts

@@ -31,8 +31,7 @@ export class CdkAppStack extends Stack {
       'powertools-layer',
       `arn:aws:lambda:${
         Stack.of(this).region
-        //}:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:2` // doesn't work with ESM see
-      }:536254204126:layer:Layers-E2E-20-x86-1f6e3-layerStack:1`
+      }:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:3`
     );
 
     // Items table
@@ -88,6 +87,7 @@ export class CdkAppStack extends Stack {
         keepNames: true,
         format: OutputFormat.ESM,
         sourcesContent: true,
+        mainFields: ['module', 'main'],
         externalModules: [], // we bundle all the dependencies
         esbuildArgs: {
           '--tree-shaking': 'true',
@@ -131,6 +131,7 @@ export class CdkAppStack extends Stack {
         sourceMap: true,
         keepNames: true,
         format: OutputFormat.ESM,
+        mainFields: ['module', 'main'],
         sourcesContent: true,
         externalModules: ['@aws-sdk/*', '@aws-lambda-powertools/*'], // the dependencies are included in the layer
         esbuildArgs: {
@@ -155,6 +156,7 @@ export class CdkAppStack extends Stack {
         sourceMap: true,
         keepNames: true,
         format: OutputFormat.CJS,
+        mainFields: ['main'],
         sourcesContent: true,
         externalModules: [], // we bundle all the dependencies
       },
@@ -177,6 +179,7 @@ export class CdkAppStack extends Stack {
           sourceMap: true,
           keepNames: true,
           format: OutputFormat.CJS,
+          mainFields: ['main'],
           sourcesContent: true,
           externalModules: ['@aws-sdk/*', '@aws-lambda-powertools/*'], // the dependencies are included in the layer
         },
@@ -196,6 +199,7 @@ export class CdkAppStack extends Stack {
         batchSize: 100,
         retryAttempts: 3,
         filters: [
+          // Filter by the INSERT event type and the presence of the id and name attributes
           FilterCriteria.filter({
             eventName: FilterRule.isEqual('INSERT'),
             dynamodb: {