feat: added captureHTTPsRequest feature

Author: dreamorosi

Diff for: docs/core/tracer.md

@@ -16,6 +16,7 @@ Tracer is an opinionated thin wrapper for [AWS X-Ray SDK for Node.js](https://gi
 
 * 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
+* Automatically trace HTTP(s) clients and generate segments for each request
 * Support tracing functions via decorators, middleware, and manual instrumentation
 * Support tracing AWS SDK v2 and v3 via AWS X-Ray SDK for Node.js  
 
@@ -49,13 +50,13 @@ The `Tracer` utility must always be instantiated outside of the Lambda handler.
 
 ### Utility settings
 
-The library has one optional setting. You can set it as environment variable, or pass it in the constructor.
-
-This setting will be used across all traces emitted:
+The library has three optional settings. You can set them as environment variables, or pass them in the constructor:
 
 Setting | Description                                                                                    | Environment variable | Constructor parameter
 ------------------------------------------------- |------------------------------------------------------------------------------------------------| ------------------------------------------------- | -------------------------------------------------
+**Tracing enabled** | Enables or disables tracing. By default tracing is enabled when running in AWS Lambda. | `POWERTOOLS_TRACE_ENABLED`          | `enabled`
 **Service name** | Sets an annotation with the **name of the service** across all traces e.g. `serverlessAirline` | `POWERTOOLS_SERVICE_NAME` | `serviceName`
+**Capture HTTPs Requests** | Defines whether HTTPs requests will be traced or not, enabled by default when tracing is also enabled. | `POWERTOOLS_TRACER_CAPTURE_HTTPS_REQUESTS` | `captureHTTPsRequests`
 
 For a **complete list** of supported environment variables, refer to [this section](./../index.md#environment-variables).
 
@@ -137,13 +138,9 @@ You can quickly start by importing the `Tracer` class, initialize it outside the
 
 === "Middy Middleware"
 
-    !!! tip "Using Middy for the first time?"
-        You can install Middy by running `npm i @middy/core`.
-        Learn more about [its usage and lifecycle in the official Middy documentation](https://github.com/middyjs/middy#usage){target="_blank"}.
-
     ```typescript hl_lines="1-2 11 13"
     import { Tracer, captureLambdaHandler } from '@aws-lambda-powertools/tracer';
-    import middy from '@middy/core';
+    import middy from '@middy/core'; // (1)
 
     const tracer = new Tracer({ serviceName: 'serverlessAirline' });
 
@@ -157,6 +154,9 @@ You can quickly start by importing the `Tracer` class, initialize it outside the
         .use(captureLambdaHandler(tracer));
     ```
 
+    1. Using Middy for the first time? You can install Middy by running `npm i @middy/core`.
+       Learn more about [its usage and lifecycle in the official Middy documentation](https://github.com/middyjs/middy#usage){target="_blank"}.
+
 === "Decorator"
 
     !!! info
@@ -326,13 +326,66 @@ 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 { S3 } from 'aws-sdk';
     import { Tracer } from '@aws-lambda-powertools/tracer';
 
     const tracer = new Tracer({ serviceName: 'serverlessAirline' });
     const s3 = tracer.captureAWSClient(new S3());
     ```
 
+### Tracing HTTP requests
+
+When your function makes calls to microservices or public HTTP APIs, Tracer automatically traces those calls and add the API to the service graph as a downstream service.
+
+You can opt-out from this feature by setting the **`POWERTOOLS_TRACER_CAPTURE_HTTPS_REQUESTS=false`** environment variable or by passing the `captureHTTPSRequests: false` option to the `Tracer` constructor.
+
+!!! info
+    The following snippet shows how to trace [axios](https://www.npmjs.com/package/axios) requests, but you can use any HTTP client library built on top of [http](https://nodejs.org/api/http.html) or [https](https://nodejs.org/api/https.html)
+
+=== "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: any, context: Context): Promise<void> => {
+        await axios.get('https://httpbin.org/status/200');
+    };
+    ```
+
+    1.  You can install the [axios](https://www.npmjs.com/package/axios) package using `npm i axios`
+=== "Example Raw X-Ray Trace excerpt"
+
+    ```json hl_lines="6 9 12-21"
+    {
+        "id": "22883fbc730e3a0b",
+        "name": "## index.handler",
+        "start_time": 1647956168.22749,
+        "end_time": 1647956169.0679862,
+        "subsegments": [
+            {
+                "id": "ab82ab2b7d525d8f",
+                "name": "httpbin.org",
+                "start_time": 1647956168.407,
+                "end_time": 1647956168.945,
+                "http": {
+                    "request": {
+                        "url": "https://httpbin.org/status/200",
+                        "method": "GET"
+                    },
+                    "response": {
+                        "status": 200,
+                        "content_length": 0
+                    }
+                },
+                "namespace": "remote"
+            }
+        ]
+    }
+    ```
+
 ## Advanced
 
 ### Disabling response auto-capture
@@ -361,7 +414,7 @@ This is useful when you need a feature available in X-Ray that is not available
 
 === "index.ts"
 
-    ```typescript hl_lines="6"
+    ```typescript hl_lines="7"
     import { Logger } from '@aws-lambda-powertools/logger';
     import { Tracer } from '@aws-lambda-powertools/tracer';
 
@@ -379,4 +432,4 @@ Tracer is disabled by default when not running in the AWS Lambda environment - T
 
 * Use annotations on key operations to slice and dice traces, create unique views, and create metrics from it via Trace Groups
 * Use a namespace when adding metadata to group data more easily
-* Annotations and metadata are added to the current subsegment opened. If you want them in a specific subsegment, [create one](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-nodejs-subsegments.html#xray-sdk-nodejs-subsegments-lambda) via the escape hatch mechanism
+* Annotations and metadata are added to the currently open subsegment. If you want them in a specific subsegment, [create one](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-nodejs-subsegments.html#xray-sdk-nodejs-subsegments-lambda) via the escape hatch mechanism

Diff for: docs/index.md

@@ -54,6 +54,7 @@ Each TypeScript utility is installed as standalone NPM package.
 | **POWERTOOLS_TRACE_ENABLED**              | Explicitly disables tracing | [Tracer](./core/tracer)   | `true`                |
 | **POWERTOOLS_TRACER_CAPTURE_RESPONSE**    | Captures Lambda or method return as metadata. | [Tracer](./core/tracer)   | `true`                |
 | **POWERTOOLS_TRACER_CAPTURE_ERROR**       | Captures Lambda or method exception as metadata. | [Tracer](./core/tracer)   | `true`                |
+| **POWERTOOLS_TRACER_CAPTURE_HTTPS_REQUESTS** | Captures HTTP(s) requests as segments. | [Tracer](./core/tracer)   | `true`                |
 | **POWERTOOLS_LOGGER_LOG_EVENT**           | Logs incoming event | [Logger](./core/logger)   | `false`               |
 | **POWERTOOLS_LOGGER_SAMPLE_RATE**         | Debug log sampling | [Logger](./core/logger)  | `0`                   |
 | **POWERTOOLS_LOG_DEDUPLICATION_DISABLED** | Disables log deduplication filter protection to use Pytest Live Log feature | [Logger](./core/logger)  | `false`               |

Diff for: package-lock.json

@@ -32,6 +32,7 @@
   "devDependencies": {
     "@aws-sdk/client-dynamodb": "^3.52.0",
     "@types/promise-retry": "^1.1.3",
+    "axios": "^0.26.1",
     "promise-retry": "^2.0.1"
   },
   "files": [
@@ -46,6 +47,6 @@
   },
   "dependencies": {
     "@aws-lambda-powertools/commons": "^0.7.1",
-    "aws-xray-sdk-core": "^3.3.3"
+    "aws-xray-sdk-core": "^3.3.4"
   }
 }

Diff for: packages/tracing/package.json

@@ -15,6 +15,7 @@ import { Segment, Subsegment } from 'aws-xray-sdk-core';
  * ## Key features
  *   * Auto capture cold start as annotation, and responses or full exceptions as metadata
  *   * Auto-disable when not running in AWS Lambda environment
+ *   * Automatically trace HTTP(s) clients and generate segments for each request
  *   * Support tracing functions via decorators, middleware, and manual instrumentation
  *   * Support tracing AWS SDK v2 and v3 via AWS X-Ray SDK for Node.js
  * 
@@ -115,6 +116,8 @@ class Tracer extends Utility implements TracerInterface {
   public provider: ProviderServiceInterface;
 
   private captureError: boolean = true;
+
+  private captureHTTPsRequests: boolean = true;
 
   private captureResponse: boolean = true;
 
@@ -131,6 +134,9 @@ class Tracer extends Utility implements TracerInterface {
 
     this.setOptions(options);
     this.provider = new ProviderService();
+    if (this.isTracingEnabled() && this.captureHTTPsRequests) {
+      this.provider.captureHTTPsGlobal();
+    }
     if (!this.isTracingEnabled()) {
       // Tell x-ray-sdk to not throw an error if context is missing but tracing is disabled
       this.provider.setContextMissingStrategy(() => ({}));
@@ -631,6 +637,39 @@ class Tracer extends Utility implements TracerInterface {
     }
   }
 
+  /**
+   * Patch an all HTTP(s) clients and create traces when your application makes calls outgoing calls.
+   *
+   * Calls using third-party HTTP request libraries, such as Axios, are supported as long as they use the native http
+   * module under the hood. Support for third-party HTTP request libraries is provided on a best effort basis.
+   * 
+   * @see https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-nodejs-httpclients.html
+   * 
+   * @param enabled - Whether or not to patch all HTTP clients
+   * @returns void
+   */
+  private setCaptureHTTPsRequests(enabled?: boolean): void {
+    if (enabled !== undefined && !enabled) {
+      this.captureHTTPsRequests = false;
+
+      return;
+    }
+
+    const customConfigValue = this.getCustomConfigService()?.getCaptureHTTPsRequests();
+    if (customConfigValue !== undefined && customConfigValue.toLowerCase() === 'false') {
+      this.captureHTTPsRequests = false;
+
+      return;
+    }
+
+    const envVarsValue = this.getEnvVarsService()?.getCaptureHTTPsRequests();
+    if (envVarsValue.toLowerCase() === 'false') {
+      this.captureHTTPsRequests = false;
+
+      return;
+    }
+  }
+
   /**
    * Setter for `captureResponse` based on configuration passed and environment variables.
    * Used internally during initialization.
@@ -679,6 +718,7 @@ class Tracer extends Utility implements TracerInterface {
     const {
       enabled,
       serviceName,
+      captureHTTPsRequests,
       customConfigService
     } = options;
 
@@ -688,6 +728,7 @@ class Tracer extends Utility implements TracerInterface {
     this.setCaptureResponse();
     this.setCaptureError();
     this.setServiceName(serviceName);
+    this.setCaptureHTTPsRequests(captureHTTPsRequests);
 
     return this;
   }