docs(tracer): clarify escape hatch mechanism (#3056)

Co-authored-by: Leandro Damascena <leandro.damascena@gmail.com>

Author: dreamorosi

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 [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,6 +388,8 @@ This is useful when you need a feature available in X-Ray that is not available
     --8<-- "examples/snippets/tracer/escapeHatch.ts"
     ```
 
+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.

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

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"
-}
+}