From bbe840539245f5a70b008474b4dd8370830ddd6a Mon Sep 17 00:00:00 2001 From: Niko Achilles Kokkinos Date: Wed, 11 Jan 2023 18:13:27 +0000 Subject: [PATCH 1/2] docs(tracer): extract Tracer code snippets in separate files #1219 --- docs/core/tracer.md | 256 ++---------------- docs/snippets/tracer/accessRootTraceId.ts | 18 ++ docs/snippets/tracer/basicUsage.ts | 7 + docs/snippets/tracer/captureAWS.ts | 5 + docs/snippets/tracer/captureAWSAll.ts | 4 + docs/snippets/tracer/captureAWSv3.ts | 5 + docs/snippets/tracer/captureHTTP.ts | 8 + .../snippets/tracer/captureMethodDecorator.ts | 20 ++ docs/snippets/tracer/captureMethodManual.ts | 34 +++ docs/snippets/tracer/decorator.ts | 15 + .../tracer/disableCaptureResponseHandler.ts | 14 + .../tracer/disableCaptureResponseMethod.ts | 18 ++ .../tracer/disableCaptureResponseMiddy.ts | 14 + docs/snippets/tracer/escapeHatch.ts | 7 + docs/snippets/tracer/manual.ts | 32 +++ docs/snippets/tracer/middy.ts | 13 + docs/snippets/tracer/putAnnotation.ts | 7 + docs/snippets/tracer/putMetadata.ts | 8 + docs/snippets/tracer/sam.ts | 9 + 19 files changed, 256 insertions(+), 238 deletions(-) create mode 100644 docs/snippets/tracer/accessRootTraceId.ts create mode 100644 docs/snippets/tracer/basicUsage.ts create mode 100644 docs/snippets/tracer/captureAWS.ts create mode 100644 docs/snippets/tracer/captureAWSAll.ts create mode 100644 docs/snippets/tracer/captureAWSv3.ts create mode 100644 docs/snippets/tracer/captureHTTP.ts create mode 100644 docs/snippets/tracer/captureMethodDecorator.ts create mode 100644 docs/snippets/tracer/captureMethodManual.ts create mode 100644 docs/snippets/tracer/decorator.ts create mode 100644 docs/snippets/tracer/disableCaptureResponseHandler.ts create mode 100644 docs/snippets/tracer/disableCaptureResponseMethod.ts create mode 100644 docs/snippets/tracer/disableCaptureResponseMiddy.ts create mode 100644 docs/snippets/tracer/escapeHatch.ts create mode 100644 docs/snippets/tracer/manual.ts create mode 100644 docs/snippets/tracer/middy.ts create mode 100644 docs/snippets/tracer/putAnnotation.ts create mode 100644 docs/snippets/tracer/putMetadata.ts create mode 100644 docs/snippets/tracer/sam.ts diff --git a/docs/core/tracer.md b/docs/core/tracer.md index c51e76a21f..e03e07c128 100644 --- a/docs/core/tracer.md +++ b/docs/core/tracer.md @@ -37,13 +37,7 @@ The `Tracer` utility must always be instantiated outside of the Lambda handler. === "handler.ts" ```typescript hl_lines="1 3" - import { Tracer } from '@aws-lambda-powertools/tracer'; - - const tracer = new Tracer({ serviceName: 'serverlessAirline' }); - - export const handler = async (_event, _context): Promise => { - // ... - }; + --8<-- "docs/snippets/tracer/basicUsage.ts" ``` ### Utility settings @@ -68,15 +62,7 @@ The `Tracer` utility is instantiated outside of the Lambda handler. In doing thi === "handler.ts" ```typescript hl_lines="1 4" - import { Tracer } from '@aws-lambda-powertools/tracer'; - - // Tracer parameter fetched from the environment variables (see template.yaml tab) - const tracer = new Tracer(); - - // You can also pass the parameter in the constructor - // const tracer = new Tracer({ - // serviceName: 'serverlessAirline' - // }); + --8<-- "docs/snippets/tracer/sam.ts" ``` === "template.yml" @@ -104,19 +90,7 @@ You can quickly start by importing the `Tracer` class, initialize it outside the Learn more about [its usage and lifecycle in the official Middy documentation](https://middy.js.org/docs/intro/getting-started){target="_blank"}. ```typescript hl_lines="1-2 11 13" - import { Tracer, captureLambdaHandler } from '@aws-lambda-powertools/tracer'; - import middy from '@middy/core'; // (1) - - const tracer = new Tracer({ serviceName: 'serverlessAirline' }); - - const lambdaHandler = async (_event: any, _context: any): Promise => { - /* ... */ - }; - - // Wrap the handler with middy - export const handler = middy(lambdaHandler) - // Use the middleware by passing the Tracer instance as a parameter - .use(captureLambdaHandler(tracer)); + --8<-- "docs/snippets/tracer/middy.ts" ``` 1. Using Middy for the first time? You can install Middy by running `npm i @middy/core`. @@ -129,21 +103,7 @@ You can quickly start by importing the `Tracer` class, initialize it outside the See the [official TypeScript documentation](https://www.typescriptlang.org/docs/handbook/decorators.html) for more details. ```typescript hl_lines="8" - import { Tracer } from '@aws-lambda-powertools/tracer'; - import { LambdaInterface } from '@aws-lambda-powertools/commons'; - - const tracer = new Tracer({ serviceName: 'serverlessAirline' }); - - class Lambda implements LambdaInterface { - // Decorate your handler class method - @tracer.captureLambdaHandler() - public async handler(_event: any, _context: any): Promise { - /* ... */ - } - } - - const handlerClass = new Lambda(); - export const handler = handlerClass.handler.bind(handlerClass); // (1) + --8<-- "docs/snippets/tracer/decorator.ts" ``` 1. Binding your handler method allows your handler to access `this`. @@ -151,38 +111,7 @@ You can quickly start by importing the `Tracer` class, initialize it outside the === "Manual" ```typescript hl_lines="6 8-9 12-13 19 22 26 28" - import { Tracer } from '@aws-lambda-powertools/tracer'; - - const tracer = new Tracer({ serviceName: 'serverlessAirline' }); - - export const handler = async (_event: any, context: any): Promise => { - const segment = tracer.getSegment(); // This is the facade segment (the one that is created by AWS Lambda) - // Create subsegment for the function & set it as active - const subsegment = segment.addNewSubsegment(`## ${process.env._HANDLER}`); - tracer.setSegment(subsegment); - - // Annotate the subsegment with the cold start & serviceName - tracer.annotateColdStart(); - tracer.addServiceNameAnnotation(); - - let res; - try { - /* ... */ - // Add the response as metadata - tracer.addResponseAsMetadata(res, process.env._HANDLER); - } catch (err) { - // Add the error as metadata - tracer.addErrorAsMetadata(err as Error); - throw err; - } finally { - // Close subsegment (the AWS Lambda one is closed automatically) - subsegment.close(); - // Set back the facade segment as active again - tracer.setSegment(segment); - } - - return res; - }; + --8<-- "docs/snippets/tracer/manual.ts" ``` @@ -203,26 +132,13 @@ When using the `captureLambdaHandler` decorator or middleware, Tracer performs t You can add annotations using `putAnnotation` method. ```typescript hl_lines="6" - import { Tracer } from '@aws-lambda-powertools/tracer'; - - const tracer = new Tracer({ serviceName: 'serverlessAirline' }); - - export const handler = async (_event: any, _context: any): Promise => { - tracer.putAnnotation('successfulBooking', true); - }; + --8<-- "docs/snippets/tracer/putAnnotation.ts" ``` === "Metadata" You can add metadata using `putMetadata` method. ```typescript hl_lines="7" - import { Tracer } from '@aws-lambda-powertools/tracer'; - - const tracer = new Tracer({ serviceName: 'serverlessAirline' }); - - export const handler = async (_event: any, _context: any): Promise => { - const res; /* ... */ - tracer.putMetadata('paymentResponse', res); - }; + --8<-- "docs/snippets/tracer/putMetadata.ts" ```
@@ -237,26 +153,7 @@ You can trace other Class methods using the `captureMethod` decorator or any arb === "Decorator" ```typescript hl_lines="8" - import { Tracer } from '@aws-lambda-powertools/tracer'; - import { LambdaInterface } from '@aws-lambda-powertools/commons'; - - const tracer = new Tracer({ serviceName: 'serverlessAirline' }); - - class Lambda implements LambdaInterface { - // Decorate your class method - @tracer.captureMethod() // (1) - public getChargeId(): string { - /* ... */ - return 'foo bar'; - } - - public async handler(_event: any, _context: any): Promise { - /* ... */ - } - } - - const handlerClass = new Lambda(); - export const handler = handlerClass.handler.bind(handlerClass); // (2) + --8<-- "docs/snippets/tracer/captureMethodDecorator.ts" ``` 1. You can set a custom name for the subsegment by passing `subSegmentName` to the decorator, like: `@tracer.captureMethod({ subSegmentName: '### myCustomMethod' })`. @@ -265,40 +162,7 @@ You can trace other Class methods using the `captureMethod` decorator or any arb === "Manual" ```typescript hl_lines="6 8-9 15 18 23 25" - import { Tracer } from '@aws-lambda-powertools/tracer'; - - const tracer = new Tracer({ serviceName: 'serverlessAirline' }); - - const getChargeId = async (): Promise => { - const parentSubsegment = tracer.getSegment(); // This is the subsegment currently active - // Create subsegment for the function & set it as active - const subsegment = parentSubsegment.addNewSubsegment(`### chargeId`); - tracer.setSegment(subsegment); - - let res; - try { - /* ... */ - // Add the response as metadata - tracer.addResponseAsMetadata(res, 'chargeId'); - } catch (err) { - // Add the error as metadata - tracer.addErrorAsMetadata(err as Error); - throw err; - } - - // Close subsegment (the AWS Lambda one is closed automatically) - subsegment.close(); - // Set the facade segment as active again - tracer.setSegment(parentSubsegment); - - return res; - }; - - export const handler = async (_event: any, _context: any): Promise => { - const chargeId = getChargeId(); - const payment = collectPayment(chargeId); - /* ... */ - }; + --8<-- "docs/snippets/tracer/captureMethodManual.ts" ``` @@ -314,11 +178,7 @@ You can patch any AWS SDK clients by calling the `captureAWSv3Client` method: === "index.ts" ```typescript hl_lines="5" - import { S3Client } from '@aws-sdk/client-s3'; - import { Tracer } from '@aws-lambda-powertools/tracer'; - - const tracer = new Tracer({ serviceName: 'serverlessAirline' }); - const client = tracer.captureAWSv3Client(new S3Client({})); + --8<-- "docs/snippets/tracer/captureAWSv3.ts" ``` !!! info @@ -329,10 +189,7 @@ You can patch all AWS SDK v2 clients by calling the `captureAWS` method: === "index.ts" ```typescript hl_lines="4" - import { Tracer } from '@aws-lambda-powertools/tracer'; - - const tracer = new Tracer({ serviceName: 'serverlessAirline' }); - const AWS = tracer.captureAWS(require('aws-sdk')); + --8<-- "docs/snippets/tracer/captureAWSAll.ts" ``` If you're looking to shave a few microseconds, or milliseconds depending on your function memory configuration, you can patch only specific AWS SDK v2 clients using `captureAWSClient`: @@ -340,11 +197,7 @@ If you're looking to shave a few microseconds, or milliseconds depending on your === "index.ts" ```typescript hl_lines="5" - import { S3 } from 'aws-sdk'; - import { Tracer } from '@aws-lambda-powertools/tracer'; - - const tracer = new Tracer({ serviceName: 'serverlessAirline' }); - const s3 = tracer.captureAWSClient(new S3()); + --8<-- "docs/snippets/tracer/captureAWS.ts" ``` ### Tracing HTTP requests @@ -360,14 +213,7 @@ You can opt-out from this feature by setting the **`POWERTOOLS_TRACER_CAPTURE_HT === "index.ts" ```typescript hl_lines="2 7" - import { Tracer } from '@aws-lambda-powertools/tracer'; - import axios from 'axios'; // (1) - - const tracer = new Tracer({ serviceName: 'serverlessAirline' }); - - export const handler = async (event: unknown, context: Context): Promise => { - await axios.get('https://httpbin.org/status/200'); - }; + --8<-- "docs/snippets/tracer/captureHTTP.ts" ``` 1. You can install the [axios](https://www.npmjs.com/package/axios) package using `npm i axios` @@ -418,62 +264,19 @@ Alternatively, use the `captureResponse: false` option in both `tracer.captureLa === "method.ts" ```typescript hl_lines="6" - import { Tracer } from '@aws-lambda-powertools/tracer'; - - const tracer = new Tracer({ serviceName: 'serverlessAirline' }); - - class Lambda implements LambdaInterface { - @tracer.captureMethod({ captureResult: false }) - public getChargeId(): string { - /* ... */ - return 'foo bar'; - } - - public async handler(_event: any, _context: any): Promise { - /* ... */ - } - } - - const handlerClass = new Lambda(); - export const handler = handlerClass.handler.bind(handlerClass); + --8<-- "docs/snippets/tracer/disableCaptureResponseMethod.ts" ``` === "handler.ts" ```typescript hl_lines="7" - import { Tracer } from '@aws-lambda-powertools/tracer'; - import { LambdaInterface } from '@aws-lambda-powertools/commons'; - - const tracer = new Tracer({ serviceName: 'serverlessAirline' }); - - class Lambda implements LambdaInterface { - @tracer.captureLambdaHandler({ captureResponse: false }) - async handler(_event: any, _context: any): Promise { - /* ... */ - } - } - - const handlerClass = new Lambda(); - export const handler = handlerClass.handler.bind(handlerClass); + --8<-- "docs/snippets/tracer/disableCaptureResponseHandler.ts" ``` === "middy.ts" ```typescript hl_lines="14" - import { Tracer, captureLambdaHandler } from '@aws-lambda-powertools/tracer'; - import middy from '@middy/core'; - - const tracer = new Tracer({ serviceName: 'serverlessAirline' }); - - const lambdaHandler = async (_event: any, _context: any): Promise => { - /* ... */ - }; - - // Wrap the handler with middy - export const handler = middy(lambdaHandler) - // Use the middleware by passing the Tracer instance as a parameter, - // but specify the captureResponse option as false. - .use(captureLambdaHandler(tracer, { captureResponse: false })); + --8<-- "docs/snippets/tracer/disableCaptureResponseMiddy.ts" ``` ### Disabling errors auto-capture @@ -496,24 +299,7 @@ Tracer exposes a `getRootXrayTraceId()` method that allows you to retrieve the [ === "index.ts" ```typescript hl_lines="9" - import { Tracer } from '@aws-lambda-powertools/tracer'; - - const tracer = new Tracer({ serviceName: 'serverlessAirline' }); - - export const handler = async (event: unknown, context: Context): Promise => { - try { - ... - } catch (err) { - const rootTraceId = tracer.getRootXrayTraceId(); - - // Example of returning an error response - return { - statusCode: 500, - body: `Internal Error - Please contact support and quote the following id: ${rootTraceId}`, - headers: { '_X_AMZN_TRACE_ID': rootTraceId }, - }; - } - }; + --8<-- "docs/snippets/tracer/accessRootTraceId.ts" ``` ### Escape hatch mechanism @@ -525,13 +311,7 @@ This is useful when you need a feature available in X-Ray that is not available === "index.ts" ```typescript hl_lines="7" - import { Logger } from '@aws-lambda-powertools/logger'; - import { Tracer } from '@aws-lambda-powertools/tracer'; - - const serviceName = 'serverlessAirline'; - const logger = new Logger({ serviceName: serviceName }); - const tracer = new Tracer({ serviceName: serviceName }); - tracer.provider.setLogger(logger); + --8<-- "docs/snippets/tracer/escapeHatch.ts" ``` ## Testing your code diff --git a/docs/snippets/tracer/accessRootTraceId.ts b/docs/snippets/tracer/accessRootTraceId.ts new file mode 100644 index 0000000000..c385e39b7c --- /dev/null +++ b/docs/snippets/tracer/accessRootTraceId.ts @@ -0,0 +1,18 @@ +import { Tracer } from '@aws-lambda-powertools/tracer'; + +const tracer = new Tracer({ serviceName: 'serverlessAirline' }); + +export const handler = async (event: unknown, context: Context): Promise => { + try { + + } catch (err) { + const rootTraceId = tracer.getRootXrayTraceId(); + + // Example of returning an error response + return { + statusCode: 500, + body: `Internal Error - Please contact support and quote the following id: ${rootTraceId}`, + headers: { '_X_AMZN_TRACE_ID': rootTraceId }, + }; + } +}; \ No newline at end of file diff --git a/docs/snippets/tracer/basicUsage.ts b/docs/snippets/tracer/basicUsage.ts new file mode 100644 index 0000000000..a8c830e78b --- /dev/null +++ b/docs/snippets/tracer/basicUsage.ts @@ -0,0 +1,7 @@ +import { Tracer } from '@aws-lambda-powertools/tracer'; + +const tracer = new Tracer({ serviceName: 'serverlessAirline' }); + +export const handler = async (_event, _context): Promise => { + // ... +}; \ No newline at end of file diff --git a/docs/snippets/tracer/captureAWS.ts b/docs/snippets/tracer/captureAWS.ts new file mode 100644 index 0000000000..b94151c014 --- /dev/null +++ b/docs/snippets/tracer/captureAWS.ts @@ -0,0 +1,5 @@ +import { S3 } from 'aws-sdk'; +import { Tracer } from '@aws-lambda-powertools/tracer'; + +const tracer = new Tracer({ serviceName: 'serverlessAirline' }); +const s3 = tracer.captureAWSClient(new S3()); \ No newline at end of file diff --git a/docs/snippets/tracer/captureAWSAll.ts b/docs/snippets/tracer/captureAWSAll.ts new file mode 100644 index 0000000000..d758e1dd7c --- /dev/null +++ b/docs/snippets/tracer/captureAWSAll.ts @@ -0,0 +1,4 @@ +import { Tracer } from '@aws-lambda-powertools/tracer'; + +const tracer = new Tracer({ serviceName: 'serverlessAirline' }); +const AWS = tracer.captureAWS(require('aws-sdk')); \ No newline at end of file diff --git a/docs/snippets/tracer/captureAWSv3.ts b/docs/snippets/tracer/captureAWSv3.ts new file mode 100644 index 0000000000..8270d10c0a --- /dev/null +++ b/docs/snippets/tracer/captureAWSv3.ts @@ -0,0 +1,5 @@ +import { S3Client } from '@aws-sdk/client-s3'; +import { Tracer } from '@aws-lambda-powertools/tracer'; + +const tracer = new Tracer({ serviceName: 'serverlessAirline' }); +const client = tracer.captureAWSv3Client(new S3Client({})); \ No newline at end of file diff --git a/docs/snippets/tracer/captureHTTP.ts b/docs/snippets/tracer/captureHTTP.ts new file mode 100644 index 0000000000..cf4cae3cdb --- /dev/null +++ b/docs/snippets/tracer/captureHTTP.ts @@ -0,0 +1,8 @@ +import { Tracer } from '@aws-lambda-powertools/tracer'; +import axios from 'axios'; // (1) + +const tracer = new Tracer({ serviceName: 'serverlessAirline' }); + +export const handler = async (event: unknown, context: Context): Promise => { + await axios.get('https://httpbin.org/status/200'); +}; \ No newline at end of file diff --git a/docs/snippets/tracer/captureMethodDecorator.ts b/docs/snippets/tracer/captureMethodDecorator.ts new file mode 100644 index 0000000000..e929c31a61 --- /dev/null +++ b/docs/snippets/tracer/captureMethodDecorator.ts @@ -0,0 +1,20 @@ +import { Tracer } from '@aws-lambda-powertools/tracer'; +import { LambdaInterface } from '@aws-lambda-powertools/commons'; + +const tracer = new Tracer({ serviceName: 'serverlessAirline' }); + +class Lambda implements LambdaInterface { + // Decorate your class method + @tracer.captureMethod() // (1) + public getChargeId(): string { + /* ... */ + return 'foo bar'; + } + + public async handler(_event: any, _context: any): Promise { + /* ... */ + } +} + +const handlerClass = new Lambda(); +export const handler = handlerClass.handler.bind(handlerClass); // (2) \ No newline at end of file diff --git a/docs/snippets/tracer/captureMethodManual.ts b/docs/snippets/tracer/captureMethodManual.ts new file mode 100644 index 0000000000..af8c0a1dc8 --- /dev/null +++ b/docs/snippets/tracer/captureMethodManual.ts @@ -0,0 +1,34 @@ +import { Tracer } from '@aws-lambda-powertools/tracer'; + +const tracer = new Tracer({ serviceName: 'serverlessAirline' }); + +const getChargeId = async (): Promise => { + const parentSubsegment = tracer.getSegment(); // This is the subsegment currently active + // Create subsegment for the function & set it as active + const subsegment = parentSubsegment.addNewSubsegment(`### chargeId`); + tracer.setSegment(subsegment); + + let res; + try { + /* ... */ + // Add the response as metadata + tracer.addResponseAsMetadata(res, 'chargeId'); + } catch (err) { + // Add the error as metadata + tracer.addErrorAsMetadata(err as Error); + throw err; + } + + // Close subsegment (the AWS Lambda one is closed automatically) + subsegment.close(); + // Set the facade segment as active again + tracer.setSegment(parentSubsegment); + + return res; +}; + +export const handler = async (_event: any, _context: any): Promise => { + const chargeId = getChargeId(); + const payment = collectPayment(chargeId); + /* ... */ +}; \ No newline at end of file diff --git a/docs/snippets/tracer/decorator.ts b/docs/snippets/tracer/decorator.ts new file mode 100644 index 0000000000..1e17ea6af0 --- /dev/null +++ b/docs/snippets/tracer/decorator.ts @@ -0,0 +1,15 @@ +import { Tracer } from '@aws-lambda-powertools/tracer'; +import { LambdaInterface } from '@aws-lambda-powertools/commons'; + +const tracer = new Tracer({ serviceName: 'serverlessAirline' }); + +class Lambda implements LambdaInterface { + // Decorate your handler class method + @tracer.captureLambdaHandler() + public async handler(_event: any, _context: any): Promise { + /* ... */ + } +} + +const handlerClass = new Lambda(); +export const handler = handlerClass.handler.bind(handlerClass); // (1) \ No newline at end of file diff --git a/docs/snippets/tracer/disableCaptureResponseHandler.ts b/docs/snippets/tracer/disableCaptureResponseHandler.ts new file mode 100644 index 0000000000..de9549c22c --- /dev/null +++ b/docs/snippets/tracer/disableCaptureResponseHandler.ts @@ -0,0 +1,14 @@ +import { Tracer } from '@aws-lambda-powertools/tracer'; +import { LambdaInterface } from '@aws-lambda-powertools/commons'; + +const tracer = new Tracer({ serviceName: 'serverlessAirline' }); + +class Lambda implements LambdaInterface { + @tracer.captureLambdaHandler({ captureResponse: false }) + async handler(_event: any, _context: any): Promise { + /* ... */ + } +} + +const handlerClass = new Lambda(); +export const handler = handlerClass.handler.bind(handlerClass); \ No newline at end of file diff --git a/docs/snippets/tracer/disableCaptureResponseMethod.ts b/docs/snippets/tracer/disableCaptureResponseMethod.ts new file mode 100644 index 0000000000..cb3d6df57d --- /dev/null +++ b/docs/snippets/tracer/disableCaptureResponseMethod.ts @@ -0,0 +1,18 @@ +import { Tracer } from '@aws-lambda-powertools/tracer'; + +const tracer = new Tracer({ serviceName: 'serverlessAirline' }); + +class Lambda implements LambdaInterface { + @tracer.captureMethod({ captureResult: false }) + public getChargeId(): string { + /* ... */ + return 'foo bar'; + } + + public async handler(_event: any, _context: any): Promise { + /* ... */ + } +} + +const handlerClass = new Lambda(); +export const handler = handlerClass.handler.bind(handlerClass); \ No newline at end of file diff --git a/docs/snippets/tracer/disableCaptureResponseMiddy.ts b/docs/snippets/tracer/disableCaptureResponseMiddy.ts new file mode 100644 index 0000000000..b0916d00fc --- /dev/null +++ b/docs/snippets/tracer/disableCaptureResponseMiddy.ts @@ -0,0 +1,14 @@ +import { Tracer, captureLambdaHandler } from '@aws-lambda-powertools/tracer'; +import middy from '@middy/core'; + +const tracer = new Tracer({ serviceName: 'serverlessAirline' }); + +const lambdaHandler = async (_event: any, _context: any): Promise => { + /* ... */ +}; + +// Wrap the handler with middy +export const handler = middy(lambdaHandler) + // Use the middleware by passing the Tracer instance as a parameter, + // but specify the captureResponse option as false. + .use(captureLambdaHandler(tracer, { captureResponse: false })); \ No newline at end of file diff --git a/docs/snippets/tracer/escapeHatch.ts b/docs/snippets/tracer/escapeHatch.ts new file mode 100644 index 0000000000..a1515582c2 --- /dev/null +++ b/docs/snippets/tracer/escapeHatch.ts @@ -0,0 +1,7 @@ +import { Logger } from '@aws-lambda-powertools/logger'; +import { Tracer } from '@aws-lambda-powertools/tracer'; + +const serviceName = 'serverlessAirline'; +const logger = new Logger({ serviceName: serviceName }); +const tracer = new Tracer({ serviceName: serviceName }); +tracer.provider.setLogger(logger); \ No newline at end of file diff --git a/docs/snippets/tracer/manual.ts b/docs/snippets/tracer/manual.ts new file mode 100644 index 0000000000..de0fe064e9 --- /dev/null +++ b/docs/snippets/tracer/manual.ts @@ -0,0 +1,32 @@ +import { Tracer } from '@aws-lambda-powertools/tracer'; + +const tracer = new Tracer({ serviceName: 'serverlessAirline' }); + +export const handler = async (_event: any, context: any): Promise => { + const segment = tracer.getSegment(); // This is the facade segment (the one that is created by AWS Lambda) + // Create subsegment for the function & set it as active + const subsegment = segment.addNewSubsegment(`## ${process.env._HANDLER}`); + tracer.setSegment(subsegment); + + // Annotate the subsegment with the cold start & serviceName + tracer.annotateColdStart(); + tracer.addServiceNameAnnotation(); + + let res; + try { + /* ... */ + // Add the response as metadata + tracer.addResponseAsMetadata(res, process.env._HANDLER); + } catch (err) { + // Add the error as metadata + tracer.addErrorAsMetadata(err as Error); + throw err; + } finally { + // Close subsegment (the AWS Lambda one is closed automatically) + subsegment.close(); + // Set back the facade segment as active again + tracer.setSegment(segment); + } + + return res; +}; \ No newline at end of file diff --git a/docs/snippets/tracer/middy.ts b/docs/snippets/tracer/middy.ts new file mode 100644 index 0000000000..0318b099f6 --- /dev/null +++ b/docs/snippets/tracer/middy.ts @@ -0,0 +1,13 @@ +import { Tracer, captureLambdaHandler } from '@aws-lambda-powertools/tracer'; +import middy from '@middy/core'; // (1) + +const tracer = new Tracer({ serviceName: 'serverlessAirline' }); + +const lambdaHandler = async (_event: any, _context: any): Promise => { + /* ... */ +}; + +// Wrap the handler with middy +export const handler = middy(lambdaHandler) + // Use the middleware by passing the Tracer instance as a parameter + .use(captureLambdaHandler(tracer)); \ No newline at end of file diff --git a/docs/snippets/tracer/putAnnotation.ts b/docs/snippets/tracer/putAnnotation.ts new file mode 100644 index 0000000000..5b48d831af --- /dev/null +++ b/docs/snippets/tracer/putAnnotation.ts @@ -0,0 +1,7 @@ +import { Tracer } from '@aws-lambda-powertools/tracer'; + +const tracer = new Tracer({ serviceName: 'serverlessAirline' }); + +export const handler = async (_event: any, _context: any): Promise => { + tracer.putAnnotation('successfulBooking', true); +}; \ No newline at end of file diff --git a/docs/snippets/tracer/putMetadata.ts b/docs/snippets/tracer/putMetadata.ts new file mode 100644 index 0000000000..c69a307373 --- /dev/null +++ b/docs/snippets/tracer/putMetadata.ts @@ -0,0 +1,8 @@ +import { Tracer } from '@aws-lambda-powertools/tracer'; + +const tracer = new Tracer({ serviceName: 'serverlessAirline' }); + +export const handler = async (_event: any, _context: any): Promise => { + const res; /* ... */ + tracer.putMetadata('paymentResponse', res); +}; \ No newline at end of file diff --git a/docs/snippets/tracer/sam.ts b/docs/snippets/tracer/sam.ts new file mode 100644 index 0000000000..881471c80b --- /dev/null +++ b/docs/snippets/tracer/sam.ts @@ -0,0 +1,9 @@ +import { Tracer } from '@aws-lambda-powertools/tracer'; + +// Tracer parameter fetched from the environment variables (see template.yaml tab) +const tracer = new Tracer(); + +// You can also pass the parameter in the constructor +// const tracer = new Tracer({ +// serviceName: 'serverlessAirline' +// }); \ No newline at end of file From 4ce659b2a6867a3c275703f02ae5b5e488cefa22 Mon Sep 17 00:00:00 2001 From: Niko Achilles Kokkinos Date: Wed, 11 Jan 2023 23:29:14 +0000 Subject: [PATCH 2/2] fix(docs): code snippet captureMethodDecorator.ts and code snippet disableCaptureResponseMethod.ts --- docs/snippets/tracer/captureMethodDecorator.ts | 2 +- docs/snippets/tracer/disableCaptureResponseMethod.ts | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/snippets/tracer/captureMethodDecorator.ts b/docs/snippets/tracer/captureMethodDecorator.ts index e929c31a61..6c580f3e5d 100644 --- a/docs/snippets/tracer/captureMethodDecorator.ts +++ b/docs/snippets/tracer/captureMethodDecorator.ts @@ -6,7 +6,7 @@ const tracer = new Tracer({ serviceName: 'serverlessAirline' }); class Lambda implements LambdaInterface { // Decorate your class method @tracer.captureMethod() // (1) - public getChargeId(): string { + public async getChargeId(): Promise { /* ... */ return 'foo bar'; } diff --git a/docs/snippets/tracer/disableCaptureResponseMethod.ts b/docs/snippets/tracer/disableCaptureResponseMethod.ts index cb3d6df57d..7386d75338 100644 --- a/docs/snippets/tracer/disableCaptureResponseMethod.ts +++ b/docs/snippets/tracer/disableCaptureResponseMethod.ts @@ -3,8 +3,8 @@ import { Tracer } from '@aws-lambda-powertools/tracer'; const tracer = new Tracer({ serviceName: 'serverlessAirline' }); class Lambda implements LambdaInterface { - @tracer.captureMethod({ captureResult: false }) - public getChargeId(): string { + @tracer.captureMethod({ captureResponse: false }) + public async getChargeId(): Promise { /* ... */ return 'foo bar'; }