Class Tracer

Intro

Tracer is an opinionated thin wrapper for AWS X-Ray SDK for Node.js.

Tracing data can be visualized through AWS X-Ray Console.

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

Usage

For more usage examples, see our documentation.

Functions usage with middleware

If you use function-based Lambda handlers you can use the captureLambdaHandler() middy middleware to automatically:

handle the subsegment lifecycle
add the ServiceName and ColdStart annotations
add the function response as metadata
add the function error as metadata (if any)

Example

import { captureLambdaHandler, Tracer } from '@aws-lambda-powertools/tracer';
import middy from '@middy/core';

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

const lambdaHandler = async (_event: any, _context: any) => {
  ...
};

export const handler = middy(lambdaHandler).use(captureLambdaHandler(tracer));

Object oriented usage with decorators

If instead you use TypeScript Classes to wrap your Lambda handler you can use the @tracer.captureLambdaHandler() decorator to automatically:

handle the subsegment lifecycle
add the ServiceName and ColdStart annotations
add the function response as metadata
add the function error as metadata (if any)

Example

import { Tracer } from '@aws-lambda-powertools/tracer';
import { LambdaInterface } from '@aws-lambda-powertools/commons';

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

// FYI: Decorator might not render properly in VSCode mouse over due to https://github.com/microsoft/TypeScript/issues/47679 and might show as *@tracer* instead of `@tracer.captureLambdaHandler`

class Lambda implements LambdaInterface {
  @tracer.captureLambdaHandler()
  public handler(event: any, context: any) {
    ...
  }
}

const handlerClass = new Lambda();
export const handler = handlerClass.handler.bind(handlerClass);

Functions usage with manual instrumentation

If you prefer to manually instrument your Lambda handler you can use the methods in the tracer class directly.

Example

import { Tracer } from '@aws-lambda-powertools/tracer';

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

export const handler = async (_event: any, context: any) => {
  const segment = tracer.getSegment(); // This is the facade segment (the one that is created by AWS Lambda)
  // Create subsegment for the function & set it as active
  const subsegment = segment.addNewSubsegment(`## ${process.env._HANDLER}`);
  tracer.setSegment(subsegment);

  // Annotate the subsegment with the cold start & serviceName
  tracer.annotateColdStart();
  tracer.addServiceNameAnnotation();

  let res;
  try {
      // ... your own logic goes here
      // Add the response as metadata
      tracer.addResponseAsMetadata(res, process.env._HANDLER);
  } catch (err) {
      // Add the error as metadata
      tracer.addErrorAsMetadata(err as Error);
      throw err;
  } finally {
      // Close the subsegment
      subsegment.close();
      // Set the facade segment as active again
      tracer.setSegment(segment);
  }

  return res;
}

Hierarchy

Utility
- Tracer

Implements

TracerInterface

Constructors

constructor

new Tracer(options?): Tracer
Parameters
- options: TracerOptions = {}
Returns Tracer
Overrides Utility.constructor
- Defined in tracer/src/Tracer.ts:148

Properties

provider

provider: ProviderServiceInterface

Methods

addErrorAsMetadata

addErrorAsMetadata(error, remote?): void
Add an error to the current segment or subsegment as metadata.
Parameters
- error: Error
  
  Error to serialize as metadata
- Optional remote: boolean
  
  Whether the error was thrown by a remote service. Defaults to false
Returns void

See
https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-errors
Implementation of TracerInterface.addErrorAsMetadata
- Defined in tracer/src/Tracer.ts:170

addResponseAsMetadata

addResponseAsMetadata(data?, methodName?): void
Add response data to the current segment or subsegment as metadata.
Parameters
- Optional data: unknown
  
  Data to serialize as metadata
- Optional methodName: string
  
  Name of the method that is being traced
Returns void

See
https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-annotations
Implementation of TracerInterface.addResponseAsMetadata
- Defined in tracer/src/Tracer.ts:197

addServiceNameAnnotation

addServiceNameAnnotation(): void
Add service name to the current segment or subsegment as annotation.

Returns void
Implementation of TracerInterface.addServiceNameAnnotation
- Defined in tracer/src/Tracer.ts:213

annotateColdStart

annotateColdStart(): void
Add ColdStart annotation to the current segment or subsegment.

If Tracer has been initialized outside the Lambda handler then the same instance of Tracer will be reused throughout the lifecycle of that same Lambda execution environment and this method will annotate ColdStart: false after the first invocation.

Returns void

See
https://docs.aws.amazon.com/lambda/latest/dg/runtimes-context.html
Implementation of TracerInterface.annotateColdStart
- Defined in tracer/src/Tracer.ts:229

captureAWS

captureAWS<T>(aws): T
Patch all AWS SDK v2 clients and create traces when your application makes calls to AWS services.

If you want to patch a specific client use captureAWSClient and if you are using AWS SDK v3 use captureAWSv3Client instead.
Type Parameters
- T
Parameters
- aws: T
  
  AWS SDK v2 import
Returns T
AWS - Instrumented AWS SDK
See
https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-nodejs-awssdkclients.html

Example
```
import { Tracer } from '@aws-lambda-powertools/tracer';

const tracer = new Tracer({ serviceName: 'serverlessAirline' });
const AWS = tracer.captureAWS(require('aws-sdk'));

export const handler = async (_event: any, _context: any) => {
  ...
}
```
Implementation of TracerInterface.captureAWS
- Defined in tracer/src/Tracer.ts:257

captureAWSClient

captureAWSClient<T>(service): T
Patch a specific AWS SDK v2 client and create traces when your application makes calls to that AWS service.

If you want to patch all clients use captureAWS and if you are using AWS SDK v3 use captureAWSv3Client instead.
Type Parameters
- T
Parameters
- service: T
  
  AWS SDK v2 client
Returns T
service - Instrumented AWS SDK v2 client
See
https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-nodejs-awssdkclients.html

Example
```
import { S3 } from 'aws-sdk';
import { Tracer } from '@aws-lambda-powertools/tracer';

const tracer = new Tracer({ serviceName: 'serverlessAirline' });
const s3 = tracer.captureAWSClient(new S3({ apiVersion: '2006-03-01' }));

export const handler = async (_event: any, _context: any) => {
  ...
}
```
Implementation of TracerInterface.captureAWSClient
- Defined in tracer/src/Tracer.ts:286

captureAWSv3Client

captureAWSv3Client<T>(service): T
Patch an AWS SDK v3 client and create traces when your application makes calls to that AWS service.

If you are using AWS SDK v2 use captureAWSClient instead.
Type Parameters
- T
Parameters
- service: T
  
  AWS SDK v3 client
Returns T
service - Instrumented AWS SDK v3 client
See
https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-nodejs-awssdkclients.html

Example
```
import { S3Client } from '@aws-sdk/client-s3';
import { Tracer } from '@aws-lambda-powertools/tracer';

const tracer = new Tracer({ serviceName: 'serverlessAirline' });
const client = new S3Client({});
tracer.captureAWSv3Client(client);

export const handler = async (_event: any, _context: any) => {
  ...
}
```
Implementation of TracerInterface.captureAWSv3Client
- Defined in tracer/src/Tracer.ts:329

captureLambdaHandler

captureLambdaHandler(options?): HandlerMethodDecorator
A decorator automating capture of metadata and annotations on segments or subsegments for a Lambda Handler.

Using this decorator on your handler function will automatically:
- handle the subsegment lifecycle
- add the ColdStart annotation
- add the function response as metadata
- add the function error as metadata (if any)
Note: Currently TypeScript only supports decorators on classes and methods. If you are using the function syntax, you should use the middleware instead.
Parameters
- Optional options: CaptureLambdaHandlerOptions
  
  (optional) Options for the decorator
Returns HandlerMethodDecorator
Example
```
import { Tracer } from '@aws-lambda-powertools/tracer';
import { LambdaInterface } from '@aws-lambda-powertools/commons';

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

class Lambda implements LambdaInterface {
  @tracer.captureLambdaHandler()
  public handler(event: any, context: any) {
    ...
  }
}

const handlerClass = new Lambda();
export const handler = handlerClass.handler.bind(handlerClass);
```
Decorator
Class
Implementation of TracerInterface.captureLambdaHandler
- Defined in tracer/src/Tracer.ts:368

captureMethod

captureMethod(options?): MethodDecorator
A decorator automating capture of metadata and annotations on segments or subsegments for an arbitrary function.

Using this decorator on your function will automatically:
- handle the subsegment lifecycle
- add the function response as metadata
- add the function error as metadata (if any)
Note: Currently TypeScript only supports decorators on classes and methods. If you are using the function syntax, you should use the middleware instead.
Parameters
- Optional options: CaptureMethodOptions
  
  (optional) Options for the decorator
Returns MethodDecorator
Example
```
import { Tracer } from '@aws-lambda-powertools/tracer';
import { LambdaInterface } from '@aws-lambda-powertools/commons';

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

class Lambda implements LambdaInterface {
  @tracer.captureMethod()
  public myMethod(param: any) {
    ...
  }

  public handler(event: any, context: any) {
    ...
  }
}

const handlerClass = new Lambda();
export const handler = handlerClass.handler.bind(handlerClass);;
```
Decorator
Class
Implementation of TracerInterface.captureMethod
- Defined in tracer/src/Tracer.ts:458

getColdStart

getColdStart(): boolean
Returns boolean
Inherited from Utility.getColdStart
- Defined in commons/lib/Utility.d.ts:4

`Protected` getDefaultServiceName

getDefaultServiceName(): string
Returns string
Inherited from Utility.getDefaultServiceName
- Defined in commons/lib/Utility.d.ts:6

getRootXrayTraceId

getRootXrayTraceId(): undefined | string

Get the current root AWS X-Ray trace id.

Utility method that returns the current AWS X-Ray Root trace id. Useful as correlation id for downstream processes.

Returns undefined | string

string - The root X-Ray trace id.

See

https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-traces

Example

import { Tracer } from '@aws-lambda-powertools/tracer';

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

export const handler = async () => {
  try {
    ...
  } catch (err) {
    const rootTraceId = tracer.getRootXrayTraceId();

    // Example of returning an error response
    return {
      statusCode: 500,
      // Include the rootTraceId in the response so we can show a "contact support" button that
      // takes the customer to a customer service form with the trace as additional context.
      body: `Internal Error - Please contact support and quote the following id: ${rootTraceId}`,
      headers: { '_X_AMZN_TRACE_ID': rootTraceId },
    };
  }
}

getSegment

getSegment(): undefined | Segment | Subsegment
Get the active segment or subsegment (if any) in the current scope.

Usually you won't need to call this method unless you are creating custom subsegments or using manual mode.

Returns undefined | Segment | Subsegment
The active segment or subsegment in the current scope. Will log a warning and return undefined if no segment is found.
See
- https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-segments
- https://docs.powertools.aws.dev/lambda-typescript/latest/core/tracer/#escape-hatch-mechanism
Example
```
import { Tracer } from '@aws-lambda-powertools/tracer';

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

export const handler = async (_event: any, _context: any) => {
  const currentSegment = tracer.getSegment();
  ... // Do something with segment
}
```
Implementation of TracerInterface.getSegment
- Defined in tracer/src/Tracer.ts:564

isColdStart

isColdStart(): boolean
Returns boolean
Inherited from Utility.isColdStart
- Defined in commons/lib/Utility.d.ts:5

isTraceSampled

isTraceSampled(): boolean
Get the current value of the AWS X-Ray Sampled flag.

Utility method that returns the current AWS X-Ray Sampled flag.

Returns boolean
boolean - true if the trace is sampled, false if tracing is disabled or the trace is not sampled.

See
https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-traces
Implementation of TracerInterface.isTraceSampled
- Defined in tracer/src/Tracer.ts:587

isTracingEnabled

isTracingEnabled(): boolean
Get the current value of the tracingEnabled property.

You can use this method during manual instrumentation to determine if tracer is currently enabled.

Returns boolean
tracingEnabled - true if tracing is enabled, false otherwise.
Implementation of TracerInterface.isTracingEnabled
- Defined in tracer/src/Tracer.ts:601

`Protected` isValidServiceName

isValidServiceName(serviceName?): boolean
Validate that the service name provided is valid. Used internally during initialization.
Parameters
- Optional serviceName: string
  
  Service name to validate
Returns boolean
Inherited from Utility.isValidServiceName
- Defined in commons/lib/Utility.d.ts:7

putAnnotation

putAnnotation(key, value): void
Adds annotation to existing segment or subsegment.
Parameters
- key: string
  
  Annotation key
- value: string | number | boolean
  
  Value for annotation
Returns void
See
https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-nodejs-segment.html#xray-sdk-nodejs-segment-annotations

Example
```
import { Tracer } from '@aws-lambda-powertools/tracer';

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

export const handler = async (_event: any, _context: any) => {
  tracer.putAnnotation('successfulBooking', true);
}
```
Implementation of TracerInterface.putAnnotation
- Defined in tracer/src/Tracer.ts:624

putMetadata

putMetadata(key, value, namespace?): void
Adds metadata to existing segment or subsegment.
Parameters
- key: string
  
  Metadata key
- value: unknown
  
  Value for metadata
- Optional namespace: string
  
  Namespace that metadata will lie under, if none is passed it will use the serviceName
Returns void
See
https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-nodejs-segment.html#xray-sdk-nodejs-segment-metadata

Example
```
import { Tracer } from '@aws-lambda-powertools/tracer';

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

export const handler = async (_event: any, _context: any) => {
  const res = someLogic();
  tracer.putMetadata('paymentResponse', res);
}
```
Implementation of TracerInterface.putMetadata
- Defined in tracer/src/Tracer.ts:651

setSegment

setSegment(segment): void
Sets the passed subsegment as the current active subsegment.

If you are using a middleware or a decorator this is done automatically for you.
Parameters
- segment: Segment | Subsegment
  
  Subsegment to set as the current segment
Returns void
See
https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-nodejs-subsegments.html

Example
```
import { Tracer } from '@aws-lambda-powertools/tracer';
import { Subsegment } from 'aws-xray-sdk-core';

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

export const handler = async (_event: any, _context: any) => {
  const subsegment = new Subsegment('### foo.bar');
  tracer.setSegment(subsegment);
}
```
Implementation of TracerInterface.setSegment
- Defined in tracer/src/Tracer.ts:683

Class Tracer

Intro

Key features

Usage

Functions usage with middleware

Example

Object oriented usage with decorators

Example

Functions usage with manual instrumentation

Example

Hierarchy

Implements

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

options: TracerOptions = {}

Returns Tracer

Properties

provider

Methods

addErrorAsMetadata

Parameters

error: Error

Optional remote: boolean

Returns void

See

addResponseAsMetadata

Parameters

Optional data: unknown

Optional methodName: string

Returns void

See

addServiceNameAnnotation

Returns void

annotateColdStart

Returns void

See

captureAWS

Type Parameters

T

Parameters

aws: T

Returns T

See

Example

captureAWSClient

Type Parameters

T

Parameters

service: T

Returns T

See

Example

captureAWSv3Client

Type Parameters

T

Parameters

service: T

Returns T

See

Example

captureLambdaHandler

Parameters

Optional options: CaptureLambdaHandlerOptions

Returns HandlerMethodDecorator

Example

Decorator

captureMethod

Parameters

Optional options: CaptureMethodOptions

Returns MethodDecorator

Example

Decorator

getColdStart

Returns boolean

Protected getDefaultServiceName

`Optional` remote: boolean

`Optional` data: unknown

`Optional` methodName: string

`Optional` options: CaptureLambdaHandlerOptions

`Optional` options: CaptureMethodOptions

`Protected` getDefaultServiceName

`Protected` isValidServiceName

`Optional` serviceName: string

`Optional` namespace: string