Skip to content

Commit e733b57

Browse files
dreamorosidreamorosi
committed
feat: added captureHTTPsRequest feature
1 parent e2a9132 commit e733b57

16 files changed

+792
-40
lines changed

Diff for: ‎docs/core/tracer.md

+64-11
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ Tracer is an opinionated thin wrapper for [AWS X-Ray SDK for Node.js](https://gi
1616

1717
* Auto capture cold start and service name as annotations, and responses or full exceptions as metadata
1818
* Auto-disable when not running in AWS Lambda environment
19+
* Automatically trace HTTP(s) clients and generate segments for each request
1920
* Support tracing functions via decorators, middleware, and manual instrumentation
2021
* Support tracing AWS SDK v2 and v3 via AWS X-Ray SDK for Node.js
2122

@@ -49,13 +50,13 @@ The `Tracer` utility must always be instantiated outside of the Lambda handler.
4950

5051
### Utility settings
5152

52-
The library has one optional setting. You can set it as environment variable, or pass it in the constructor.
53-
54-
This setting will be used across all traces emitted:
53+
The library has three optional settings. You can set them as environment variables, or pass them in the constructor:
5554

5655
Setting | Description | Environment variable | Constructor parameter
5756
------------------------------------------------- |------------------------------------------------------------------------------------------------| ------------------------------------------------- | -------------------------------------------------
57+
**Tracing enabled** | Enables or disables tracing. By default tracing is enabled when running in AWS Lambda. | `POWERTOOLS_TRACE_ENABLED` | `enabled`
5858
**Service name** | Sets an annotation with the **name of the service** across all traces e.g. `serverlessAirline` | `POWERTOOLS_SERVICE_NAME` | `serviceName`
59+
**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`
5960

6061
For a **complete list** of supported environment variables, refer to [this section](./../index.md#environment-variables).
6162

@@ -137,13 +138,9 @@ You can quickly start by importing the `Tracer` class, initialize it outside the
137138

138139
=== "Middy Middleware"
139140

140-
!!! tip "Using Middy for the first time?"
141-
You can install Middy by running `npm i @middy/core`.
142-
Learn more about [its usage and lifecycle in the official Middy documentation](https://github.com/middyjs/middy#usage){target="_blank"}.
143-
144141
```typescript hl_lines="1-2 11 13"
145142
import { Tracer, captureLambdaHandler } from '@aws-lambda-powertools/tracer';
146-
import middy from '@middy/core';
143+
import middy from '@middy/core'; // (1)
147144

148145
const tracer = new Tracer({ serviceName: 'serverlessAirline' });
149146

@@ -157,6 +154,9 @@ You can quickly start by importing the `Tracer` class, initialize it outside the
157154
.use(captureLambdaHandler(tracer));
158155
```
159156

157+
1. Using Middy for the first time? You can install Middy by running `npm i @middy/core`.
158+
Learn more about [its usage and lifecycle in the official Middy documentation](https://github.com/middyjs/middy#usage){target="_blank"}.
159+
160160
=== "Decorator"
161161

162162
!!! info
@@ -326,13 +326,66 @@ If you're looking to shave a few microseconds, or milliseconds depending on your
326326
=== "index.ts"
327327

328328
```typescript hl_lines="5"
329-
import { S3 } from "aws-sdk";
329+
import { S3 } from 'aws-sdk';
330330
import { Tracer } from '@aws-lambda-powertools/tracer';
331331

332332
const tracer = new Tracer({ serviceName: 'serverlessAirline' });
333333
const s3 = tracer.captureAWSClient(new S3());
334334
```
335335

336+
### Tracing HTTP requests
337+
338+
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.
339+
340+
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.
341+
342+
!!! info
343+
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)
344+
345+
=== "index.ts"
346+
347+
```typescript hl_lines="2 7"
348+
import { Tracer } from '@aws-lambda-powertools/tracer';
349+
import axios from 'axios'; // (1)
350+
351+
const tracer = new Tracer({ serviceName: 'serverlessAirline' });
352+
353+
export const handler = async (event: any, context: Context): Promise<void> => {
354+
await axios.get('https://httpbin.org/status/200');
355+
};
356+
```
357+
358+
1. You can install the [axios](https://www.npmjs.com/package/axios) package using `npm i axios`
359+
=== "Example Raw X-Ray Trace excerpt"
360+
361+
```json hl_lines="6 9 12-21"
362+
{
363+
"id": "22883fbc730e3a0b",
364+
"name": "## index.handler",
365+
"start_time": 1647956168.22749,
366+
"end_time": 1647956169.0679862,
367+
"subsegments": [
368+
{
369+
"id": "ab82ab2b7d525d8f",
370+
"name": "httpbin.org",
371+
"start_time": 1647956168.407,
372+
"end_time": 1647956168.945,
373+
"http": {
374+
"request": {
375+
"url": "https://httpbin.org/status/200",
376+
"method": "GET"
377+
},
378+
"response": {
379+
"status": 200,
380+
"content_length": 0
381+
}
382+
},
383+
"namespace": "remote"
384+
}
385+
]
386+
}
387+
```
388+
336389
## Advanced
337390

338391
### Disabling response auto-capture
@@ -361,7 +414,7 @@ This is useful when you need a feature available in X-Ray that is not available
361414

362415
=== "index.ts"
363416

364-
```typescript hl_lines="6"
417+
```typescript hl_lines="7"
365418
import { Logger } from '@aws-lambda-powertools/logger';
366419
import { Tracer } from '@aws-lambda-powertools/tracer';
367420

@@ -379,4 +432,4 @@ Tracer is disabled by default when not running in the AWS Lambda environment - T
379432

380433
* Use annotations on key operations to slice and dice traces, create unique views, and create metrics from it via Trace Groups
381434
* Use a namespace when adding metadata to group data more easily
382-
* 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
435+
* 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

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

0 commit comments

Comments
 (0)