chore(all): merge

Author: saragerion

CHANGELOG.md

@@ -3,6 +3,30 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [0.2.0-beta.6](https://github.com/awslabs/aws-lambda-powertools-typescript/compare/v0.2.0-beta.5...v0.2.0-beta.6) (2021-12-23)
+
+**Note:** Version bump only for package aws-lambda-powertools-typescript
+
+
+
+
+
+# [0.2.0-beta.5](https://github.com/awslabs/aws-lambda-powertools-typescript/compare/v0.2.0-beta.4...v0.2.0-beta.5) (2021-12-21)
+
+**Note:** Version bump only for package aws-lambda-powertools-typescript
+
+
+
+
+
+# [0.2.0-beta.4](https://github.com/awslabs/aws-lambda-powertools-typescript/compare/v0.2.0-beta.3...v0.2.0-beta.4) (2021-12-21)
+
+**Note:** Version bump only for package aws-lambda-powertools-typescript
+
+
+
+
+
 # [0.2.0-beta.3](https://github.com/awslabs/aws-lambda-powertools-typescript/compare/v0.2.0-beta.2...v0.2.0-beta.3) (2021-12-17)
 
 **Note:** Version bump only for package aws-lambda-powertools-typescript

docs/core/tracer.md

@@ -9,7 +9,7 @@ Tracer is an opinionated thin wrapper for [AWS X-Ray SDK for Node.js](https://gi
 
 ## Key features
 
-* Auto capture cold start as annotation, and responses or full exceptions as metadata
+* Auto capture cold start and service name as annotations, and responses or full exceptions as metadata
 * Auto-disable when not running in AWS Lambda environment
 * Support tracing functions via decorators, middleware, and manual instrumentation
 * Support tracing AWS SDK v2 and v3 via AWS X-Ray SDK for Node.js
@@ -75,32 +75,31 @@ You can quickly start by importing the `Tracer` class, initialize it outside the
 
 === "Manual"
 
-    ```typescript hl_lines="1-2 4 9-10 12 18 21 25"
+    ```typescript hl_lines="1 3 7 9 11 17 20 24"
     import { Tracer } from '@aws-lambda-powertools/tracer';
-    import { Segment } from 'aws-xray-sdk-core';
 
     const tracer = Tracer(); // Sets service via env var
     // OR tracer = Tracer({ service: 'example' });
 
     export const handler = async (_event: any, context: any) => {
-        // Create subsegment & set it as active
-        const subsegment = new Subsegment(`## ${context.functionName}`);
-        tracer.setSegment(subsegment);
-        // Add the ColdStart annotation
-        this.putAnnotation('ColdStart', tracer.coldStart);
+        const segment = tracer.getSegment(); // This is the facade segment (the one that is created by AWS Lambda)
+        // Create subsegment for the function
+        const handlerSegment = segment.addNewSubsegment(`## ${context.functionName}`);
+        tracer.annotateColdStart();
+        tracer.addServiceNameAnnotation();
 
         let res;
         try {
-            res = await someLogic(); // Do something
-            // Add the response as metadata
-            tracer.putMetadata(`${context.functionName} response`, data);
+            res = ...
+            // Add the response as metadata 
+            tracer.addResponseAsMetadata(res, context.functionName);
         } catch (err) {
             // Add the error as metadata
-            subsegment.addError(err, false);
+            tracer.addErrorAsMetadata(err as Error);
         }
-
-        // Close subsegment
-        subsegment.close();
+    
+        // Close subsegment (the AWS Lambda one is closed automatically)
+        handlerSegment.close();
 
         return res;
     }

examples/cdk/.gitignore

@@ -0,0 +1,8 @@
+*.js
+!jest.config.js
+*.d.ts
+node_modules
+
+# CDK asset staging directory
+.cdk.staging
+cdk.out

examples/cdk/.npmignore

@@ -0,0 +1,6 @@
+*.ts
+!*.d.ts
+
+# CDK asset staging directory
+.cdk.staging
+cdk.out

examples/cdk/README.md

@@ -0,0 +1,14 @@
+# Welcome to your CDK TypeScript project!
+
+This is a blank project for TypeScript development with CDK.
+
+The `cdk.json` file tells the CDK Toolkit how to execute your app.
+
+## Useful commands
+
+ * `npm run build`   compile typescript to js
+ * `npm run watch`   watch for changes and compile
+ * `npm run test`    perform the jest unit tests
+ * `cdk deploy`      deploy this stack to your default AWS account/region
+ * `cdk diff`        compare deployed stack with current state
+ * `cdk synth`       emits the synthesized CloudFormation template

examples/cdk/bin/cdk-app.ts

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import 'source-map-support/register';
+import * as cdk from 'aws-cdk-lib';
+import { CdkAppStack } from '../lib/example-stack';
+
+const app = new cdk.App();
+new CdkAppStack(app, 'CdkAppStack', {
+  /* If you don't specify 'env', this stack will be environment-agnostic.
+   * Account/Region-dependent features and context lookups will not work,
+   * but a single synthesized template can be deployed anywhere. */
+
+  /* Uncomment the next line to specialize this stack for the AWS Account
+   * and Region that are implied by the current CLI configuration. */
+  // env: { account: process.env.CDK_DEFAULT_ACCOUNT, region: process.env.CDK_DEFAULT_REGION },
+
+  /* Uncomment the next line if you know exactly what Account and Region you
+   * want to deploy the stack to. */
+  // env: { account: '123456789012', region: 'us-east-1' },
+
+  /* For more information, see https://docs.aws.amazon.com/cdk/latest/guide/environments.html */
+});

examples/cdk/cdk.json

@@ -0,0 +1,26 @@
+{
+  "app": "npx ts-node --prefer-ts-exts bin/cdk-app.ts",
+  "watch": {
+    "include": [
+      "**"
+    ],
+    "exclude": [
+      "README.md",
+      "cdk*.json",
+      "**/*.d.ts",
+      "**/*.js",
+      "tsconfig.json",
+      "package*.json",
+      "yarn.lock",
+      "node_modules",
+      "test"
+    ]
+  },
+  "context": {
+    "@aws-cdk/aws-apigateway:usagePlanKeyOrderInsensitiveId": true,
+    "@aws-cdk/core:stackRelativeExports": true,
+    "@aws-cdk/aws-rds:lowercaseDbIdentifier": true,
+    "@aws-cdk/aws-lambda:recognizeVersionProps": true,
+    "@aws-cdk/aws-cloudfront:defaultSecurityPolicyTLSv1.2_2021": true
+  }
+}

examples/cdk/jest.config.js

@@ -0,0 +1,8 @@
+module.exports = {
+  testEnvironment: 'node',
+  roots: ['<rootDir>/test'],
+  testMatch: ['**/*.test.ts'],
+  transform: {
+    '^.+\\.tsx?$': 'ts-jest'
+  }
+};

examples/cdk/lib/example-stack.MyFunction.ts

@@ -0,0 +1,61 @@
+import { Context } from 'aws-lambda';
+import { Metrics, MetricUnits } from '@aws-lambda-powertools/metrics';
+import { Logger } from '@aws-lambda-powertools/logger';
+import { Tracer } from '@aws-lambda-powertools/tracer';
+
+const namespace = 'CDKExample';
+const serviceName = 'MyFunctionWithStandardHandler';
+
+const metrics = new Metrics({ namespace: namespace, service: serviceName });
+const logger = new Logger({ logLevel: 'INFO', serviceName: serviceName });
+const tracer = new Tracer({ serviceName: serviceName });
+
+export const handler = async (_event: unknown, context: Context): Promise<unknown> => {
+  // Since we are in manual mode we need to create the handler segment (the 4 lines below would be done for you by decorator/middleware)
+  // we do it at the beginning because we want to trace the whole duration of the handler
+  const segment = tracer.getSegment(); // This is the facade segment (the one that is created by Lambda & that can't be manipulated)
+  const handlerSegment = segment.addNewSubsegment(`## ${context.functionName}`);
+  // TODO: expose tracer.annotateColdStart()
+  tracer.putAnnotation('ColdStart', Tracer.coldStart);
+
+  // ### Experiment logger
+  logger.addPersistentLogAttributes({
+    testKey: 'testValue',
+  });
+  logger.debug('This is an DEBUG log'); // Won't show by default
+  logger.info('This is an INFO log');
+  logger.warn('This is an WARN log');
+  logger.error('This is an ERROR log');
+
+  // ### Experiment metrics
+  metrics.captureColdStartMetric();
+  metrics.raiseOnEmptyMetrics();
+  metrics.setDefaultDimensions({ environment: 'example', type: 'standardFunction' });
+  metrics.addMetric('test-metric', MetricUnits.Count, 10);
+
+  const metricWithItsOwnDimensions = metrics.singleMetric();
+  metricWithItsOwnDimensions.addDimension('InnerDimension', 'true');
+  metricWithItsOwnDimensions.addMetric('single-metric', MetricUnits.Percent, 50);
+
+  metrics.purgeStoredMetrics();
+  metrics.raiseOnEmptyMetrics();
+
+  // ### Experiment tracer
+
+  tracer.putAnnotation('Myannotation', 'My annotation\'s value');
+
+  // Create subsegment & set it as active
+  const subsegment = handlerSegment.addNewSubsegment('MySubSegment');
+
+  try {
+    throw new Error('test');
+    // Add the response as metadata
+  } catch (err) {
+    // Add the error as metadata
+    subsegment.addError(err as Error, false);
+  }
+
+  // Close subsegment
+  subsegment.close();
+  handlerSegment.close();
+};

examples/cdk/lib/example-stack.MyFunctionWithDecorator.ts

@@ -0,0 +1,63 @@
+import { Tracer } from '@aws-lambda-powertools/tracer';
+import { Callback, Context } from 'aws-lambda';
+import { Metrics, MetricUnits } from '@aws-lambda-powertools/metrics';
+import { Logger } from '@aws-lambda-powertools/logger';
+
+const namespace = 'CDKExample';
+const serviceName = 'MyFunctionWithDecorator';
+
+const metrics = new Metrics({ namespace: namespace, service: serviceName });
+const logger = new Logger({ logLevel: 'INFO', serviceName: serviceName });
+const tracer = new Tracer({ serviceName: serviceName });
+
+export class MyFunctionWithDecorator {
+  @tracer.captureLambdaHanlder()
+  @logger.injectLambdaContext()
+  @metrics.logMetrics({
+    captureColdStartMetric: true,
+    raiseOnEmptyMetrics: true,
+    defaultDimensions: { environment: 'example', type: 'withDecorator' },
+  })
+  public handler(_event: unknown, _context: Context, _callback: Callback<unknown>): void | Promise<unknown> {
+    // ### Experiment logger
+    logger.addPersistentLogAttributes({
+      testKey: 'testValue',
+    });
+    logger.debug('This is an DEBUG log'); // Won't show by default
+    logger.info('This is an INFO log');
+    logger.warn('This is an WARN log');
+    logger.error('This is an ERROR log');
+
+    // ### Experiment metrics
+    metrics.addMetric('test-metric', MetricUnits.Count, 10);
+
+    const metricWithItsOwnDimensions = metrics.singleMetric();
+    metricWithItsOwnDimensions.addDimension('InnerDimension', 'true');
+    metricWithItsOwnDimensions.addMetric('single-metric', MetricUnits.Percent, 50);
+
+    // ### Experiment tracer
+    tracer.putAnnotation('Myannotation', 'My annotation\'s value');
+
+    // Create subsegment & set it as active
+    const segment = tracer.getSegment(); // This is the facade segment (the one that is created by Lambda & that can't be manipulated)
+    const subsegment = segment.addNewSubsegment('MySubSegment');
+
+    tracer.setSegment(subsegment);
+    // TODO: Add the ColdStart annotation !!! NOT POSSIBLE
+    // tracer.putAnnotation('ColdStart', tracer);
+
+    try {
+      throw new Error('test');
+      // Add the response as metadata
+    } catch (err) {
+      // Add the error as metadata
+      subsegment.addError(err as Error, false);
+    }
+
+    // Close subsegment
+    subsegment.close();
+  }
+}
+
+export const handlerClass = new MyFunctionWithDecorator();
+export const handler = handlerClass.handler;