From f482e692159942d919b47b9b1e098b01d654fba9 Mon Sep 17 00:00:00 2001 From: Andrea Amorosi Date: Thu, 12 Sep 2024 18:57:51 +0200 Subject: [PATCH 1/3] docs(tracer): clarify escape hatch mechanism --- docs/core/tracer.md | 6 +++++- packages/tracer/src/provider/ProviderService.ts | 11 +++++++++++ packages/tracer/typedoc.json | 9 ++++++--- 3 files changed, 22 insertions(+), 4 deletions(-) diff --git a/docs/core/tracer.md b/docs/core/tracer.md index c680ccf38d..3c38ee3383 100644 --- a/docs/core/tracer.md +++ b/docs/core/tracer.md @@ -378,7 +378,7 @@ Tracer exposes a `getRootXrayTraceId()` method that allows you to retrieve the [ ### Escape hatch mechanism -You can use `tracer.provider` attribute to access all methods provided by the [AWS X-Ray SDK](https://docs.aws.amazon.com/xray-sdk-for-nodejs/latest/reference/AWSXRay.html). +You can use `tracer.provider` attribute to access some of the methods provided by the [AWS X-Ray SDK](https://docs.aws.amazon.com/xray-sdk-for-nodejs/latest/reference/AWSXRay.html). This is useful when you need a feature available in X-Ray that is not available in the Tracer utility, for example [SQL queries tracing](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-nodejs-sqlclients.html), or [a custom logger](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-nodejs-configuration.html#xray-sdk-nodejs-configuration-logging). @@ -388,6 +388,10 @@ This is useful when you need a feature available in X-Ray that is not available --8<-- "examples/snippets/tracer/escapeHatch.ts" ``` +We only expose [a subset of the methods available](https://docs.powertools.aws.dev/lambda/typescript/latest/api/classes/_aws_lambda_powertools_tracer.provider_ProviderService.ProviderService.html) in the AWS X-Ray SDK for Node.js based on the most common use cases relevant for AWS Lambda and their compatibility with the Tracer utility. + +If you need to access a method that is not available you can import it directly from the AWS X-Ray SDK for Node.js. Compatibility with the Tracer utility is not guaranteed. + ## Testing your code Tracer is disabled by default when not running in the AWS Lambda environment - This means no code changes or environment variables to be set. diff --git a/packages/tracer/src/provider/ProviderService.ts b/packages/tracer/src/provider/ProviderService.ts index facfca45ef..fe83e8087d 100644 --- a/packages/tracer/src/provider/ProviderService.ts +++ b/packages/tracer/src/provider/ProviderService.ts @@ -32,6 +32,17 @@ import { isHttpSubsegment, } from './utilities.js'; +/** + * The ProviderService class is a wrapper around the AWS X-Ray SDK for Node.js. + * + * The service provides exposes a selection of methods to interact with the SDK directly, + * these methods were chosen to be the most useful in the context of a Lambda function and + * have been tested to work with Powertools for AWS Lambda. + * + * If you want to use one of the other methods that are not exposed by this class, + * you can import the methods directly from the `aws-xray-sdk-core` package, and for most cases, + * they should work as expected. However, support for these methods is not guaranteed. + */ class ProviderService implements ProviderServiceInterface { /** * @deprecated diff --git a/packages/tracer/typedoc.json b/packages/tracer/typedoc.json index 7df20e3456..bf98d8924a 100644 --- a/packages/tracer/typedoc.json +++ b/packages/tracer/typedoc.json @@ -1,9 +1,12 @@ { - "extends": ["../../typedoc.base.json"], + "extends": [ + "../../typedoc.base.json" + ], "entryPoints": [ "./src/index.ts", "./src/types/index.ts", - "./src/middleware/middy.ts" + "./src/middleware/middy.ts", + "./src/provider/ProviderService.ts", ], "readme": "README.md" -} +} \ No newline at end of file From d23dd99cefb4cb8c52bddd0c2bdf1607bb1748e4 Mon Sep 17 00:00:00 2001 From: Andrea Amorosi Date: Thu, 12 Sep 2024 19:52:16 +0200 Subject: [PATCH 2/3] Update docs/core/tracer.md Co-authored-by: Leandro Damascena --- docs/core/tracer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/tracer.md b/docs/core/tracer.md index 3c38ee3383..021a42271c 100644 --- a/docs/core/tracer.md +++ b/docs/core/tracer.md @@ -390,7 +390,7 @@ This is useful when you need a feature available in X-Ray that is not available We only expose [a subset of the methods available](https://docs.powertools.aws.dev/lambda/typescript/latest/api/classes/_aws_lambda_powertools_tracer.provider_ProviderService.ProviderService.html) in the AWS X-Ray SDK for Node.js based on the most common use cases relevant for AWS Lambda and their compatibility with the Tracer utility. -If you need to access a method that is not available you can import it directly from the AWS X-Ray SDK for Node.js. Compatibility with the Tracer utility is not guaranteed. +If you need to access a method that is not available, you can import it directly from the AWS X-Ray SDK for Node.js. However, please note that compatibility with the Tracer utility is not guaranteed. ## Testing your code From a2e6a6207e0f932a91c13013ff9d8a0ef8ace318 Mon Sep 17 00:00:00 2001 From: Andrea Amorosi Date: Thu, 12 Sep 2024 19:52:40 +0200 Subject: [PATCH 3/3] chore: address feedback --- docs/core/tracer.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/core/tracer.md b/docs/core/tracer.md index 3c38ee3383..a1d5d619fe 100644 --- a/docs/core/tracer.md +++ b/docs/core/tracer.md @@ -378,7 +378,7 @@ Tracer exposes a `getRootXrayTraceId()` method that allows you to retrieve the [ ### Escape hatch mechanism -You can use `tracer.provider` attribute to access some of the methods provided by the [AWS X-Ray SDK](https://docs.aws.amazon.com/xray-sdk-for-nodejs/latest/reference/AWSXRay.html). +You can use `tracer.provider` attribute to access [a subset of the methods provided](https://docs.powertools.aws.dev/lambda/typescript/latest/api/classes/_aws_lambda_powertools_tracer.provider_ProviderService.ProviderService.html) by the [AWS X-Ray SDK](https://docs.aws.amazon.com/xray-sdk-for-nodejs/latest/reference/AWSXRay.html). This is useful when you need a feature available in X-Ray that is not available in the Tracer utility, for example [SQL queries tracing](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-nodejs-sqlclients.html), or [a custom logger](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-nodejs-configuration.html#xray-sdk-nodejs-configuration-logging). @@ -388,8 +388,6 @@ This is useful when you need a feature available in X-Ray that is not available --8<-- "examples/snippets/tracer/escapeHatch.ts" ``` -We only expose [a subset of the methods available](https://docs.powertools.aws.dev/lambda/typescript/latest/api/classes/_aws_lambda_powertools_tracer.provider_ProviderService.ProviderService.html) in the AWS X-Ray SDK for Node.js based on the most common use cases relevant for AWS Lambda and their compatibility with the Tracer utility. - If you need to access a method that is not available you can import it directly from the AWS X-Ray SDK for Node.js. Compatibility with the Tracer utility is not guaranteed. ## Testing your code