Options
All
  • Public
  • Public/Protected
  • All
Menu

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' });

export const handler = middy(async (_event: any, _context: any) => {
  ...
}).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';

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

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

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

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

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';
import { Segment } from 'aws-xray-sdk-core';

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 {
      res = ...
      // 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

Implements

Index

Constructors

Properties

Methods

Constructors

constructor

Properties

provider

provider: ProviderServiceInterface

Methods

addErrorAsMetadata

  • addErrorAsMetadata(error: Error): void

addResponseAsMetadata

  • addResponseAsMetadata(data?: unknown, methodName?: string): void

addServiceNameAnnotation

  • addServiceNameAnnotation(): void

annotateColdStart

  • annotateColdStart(): void

captureAWS

  • captureAWS<T>(aws: T): T

captureAWSClient

  • captureAWSClient<T>(service: T): T

captureAWSv3Client

  • captureAWSv3Client<T>(service: T): T

captureLambdaHandler

  • 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.

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

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

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

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

    Class

    Returns <internal>.HandlerMethodDecorator

captureMethod

  • 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.

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

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

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

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

    export const handlerClass = new Lambda();
    export const myMethod = handlerClass.myMethod; 
    export const handler = handlerClass.handler;
    decorator

    Class

    Returns MethodDecorator

getColdStart

  • getColdStart(): boolean

getSegment

  • getSegment(): Segment | Subsegment

isColdStart

  • isColdStart(): boolean

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.

putAnnotation

  • putAnnotation(key: string, value: string | number | boolean): void

putMetadata

  • putMetadata(key: string, value: unknown, namespace?: string): void

setSegment

  • setSegment(segment: Segment | Subsegment): 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.

    see

    https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-nodejs-subsegments.html

    example
    import { Tracer } from '@aws-lambda-powertools/tracer';
    import { Segment } 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);
    }

    Parameters

    • segment: Segment | Subsegment

      Subsegment to set as the current segment

    Returns void

Generated using TypeDoc