Skip to content

Commit

Permalink
feat: added captureHTTPsRequest feature (#677)
Browse files Browse the repository at this point in the history 
* fix: increased test cases timeout to make it more stable

* test: increase timeout to 4min

* feat: added captureHTTPsRequest feature

* docs: added 3rd party clients notice

* fix: removed unused import

* chore: add integ tests

* fix: increased timeout to 3min

* fix: error introduced in test fn

* fix: revert changes on e2e test from this PR

* fix: reverted e2e test

* fix: reintroduced some changes

* fix: re-added manual e2e tests

* fixtroubleshooting

* fixtroubleshooting

* fix/troubleshooting

* fix/troubleshooting

* fix/troubleshooting

* Update docs/core/tracer.md

Co-authored-by: Florian Chazal <florianchazal@gmail.com>

* fix: addressed review comments

* build(deps): updated client-dynamodb dev dep

* Update docs/core/tracer.md

Co-authored-by: Sara Gerion <47529391+saragerion@users.noreply.github.com>

* Update packages/tracing/tests/unit/ProviderService.test.ts

Co-authored-by: Sara Gerion <47529391+saragerion@users.noreply.github.com>

* Update packages/tracing/src/Tracer.ts

Co-authored-by: Sara Gerion <47529391+saragerion@users.noreply.github.com>

Co-authored-by: Florian Chazal <florianchazal@gmail.com>
Co-authored-by: Sara Gerion <47529391+saragerion@users.noreply.github.com>
  • Loading branch information
@dreamorosi @flochaz @saragerion
3 people authored Apr 5, 2022
1 parent ff3d153 commit 5a36723
Show file tree
Hide file tree
Showing 22 changed files with 790 additions and 498 deletions.
76 changes: 65 additions & 11 deletions docs/core/tracer.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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).

Expand Down Expand Up @@ -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' });

Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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';

Expand All @@ -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
1 change: 1 addition & 0 deletions docs/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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` |
Expand Down
Loading

0 comments on commit 5a36723

Please sign in to comment.