feat: added captureHTTPsRequest feature

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,67 @@ 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 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).
+    Support to 3rd party HTTP clients is provided on a best effort basis.
+
+=== "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<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 +415,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 +433,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

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`               |