@aws-lambda-powertools/tracer

What is @aws-lambda-powertools/tracer?

@aws-lambda-powertools/tracer is an npm package designed to simplify the implementation of distributed tracing in AWS Lambda functions. It helps in capturing and propagating trace data, making it easier to monitor and debug serverless applications.

What are @aws-lambda-powertools/tracer's main functionalities?

Initialize Tracer

This code initializes the Tracer object, which is the starting point for using the tracing functionalities provided by the package.

const { Tracer } = require('@aws-lambda-powertools/tracer');
const tracer = new Tracer();

Capture Lambda Handler

This code demonstrates how to wrap a Lambda handler with the tracer to automatically capture trace data for the entire function execution.

const { Tracer } = require('@aws-lambda-powertools/tracer');
const tracer = new Tracer();

exports.handler = tracer.captureLambdaHandler(async (event, context) => {
  // Your Lambda function code here
  return { statusCode: 200, body: 'Hello World' };
});

Capture Method

This code shows how to use the @tracer.captureMethod() decorator to capture trace data for individual methods within a class.

const { Tracer } = require('@aws-lambda-powertools/tracer');
const tracer = new Tracer();

class MyService {
  @tracer.captureMethod()
  myMethod() {
    // Your method code here
  }
}

Add Annotation

This code demonstrates how to add custom annotations to the trace, which can be useful for adding additional context to the trace data.

const { Tracer } = require('@aws-lambda-powertools/tracer');
const tracer = new Tracer();

exports.handler = tracer.captureLambdaHandler(async (event, context) => {
  tracer.annotate('key', 'value');
  // Your Lambda function code here
  return { statusCode: 200, body: 'Hello World' };
});

Add Metadata

This code shows how to add custom metadata to the trace, which can be useful for adding structured data to the trace.

const { Tracer } = require('@aws-lambda-powertools/tracer');
const tracer = new Tracer();

exports.handler = tracer.captureLambdaHandler(async (event, context) => {
  tracer.addMetadata('key', { foo: 'bar' });
  // Your Lambda function code here
  return { statusCode: 200, body: 'Hello World' };
});

Other packages similar to @aws-lambda-powertools/tracer

aws-xray-sdk

The aws-xray-sdk package provides similar functionalities for distributed tracing in AWS Lambda functions. It allows you to capture trace data and propagate it across different services. Compared to @aws-lambda-powertools/tracer, aws-xray-sdk is more general-purpose and can be used in a variety of AWS services, not just Lambda.

opentelemetry

OpenTelemetry is a popular open-source project that provides a set of APIs, libraries, agents, and instrumentation to enable observability. It supports distributed tracing, metrics, and logging. Compared to @aws-lambda-powertools/tracer, OpenTelemetry is more comprehensive and can be used across different cloud providers and environments.

datadog-lambda-js

The datadog-lambda-js package is designed to enable distributed tracing and custom metrics for AWS Lambda functions using Datadog. It provides similar functionalities to @aws-lambda-powertools/tracer but is specifically tailored for integration with Datadog's observability platform.

README

Powertools for AWS Lambda (TypeScript)

Powertools for AWS Lambda (TypeScript) is a developer toolkit to implement Serverless best practices and increase developer velocity.

You can use the library in both TypeScript and JavaScript code bases.

• Intro
• Usage
  • Basic usage
  • Capture AWS SDK clients
  • Add metadata and annotations
• Contribute
• Roadmap
• Connect
• How to support Powertools for AWS Lambda (TypeScript)?
  • Becoming a reference customer
  • Sharing your work
  • Using Lambda Layer
• License

Intro

The Tracer utility is an opinionated thin wrapper for AWS X-Ray SDK for Node.js, to automatically capture cold starts, trace HTTP(S) clients including fetch and generate segments and add metadata or annotations to traces.

Usage

To get started, install the library by running:

npm i @aws-lambda-powertools/tracer

Basic usage

Add Tracer to your Lambda handler as decorator:

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

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

class Lambda implements LambdaInterface {
  // Decorate your handler class method
  @tracer.captureLambdaHandler()
  public async handler(_event: unknown, _context: unknown): Promise<void> {
    tracer.getSegment();
  }
}

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

or using middy:

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

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

const lambdaHandler = async (
  _event: unknown,
  _context: unknown
): Promise<void> => {
  tracer.putAnnotation('successfulBooking', true);
};

// Wrap the handler with middy
export const handler = middy(lambdaHandler)
  // Use the middleware by passing the Tracer instance as a parameter
  .use(captureLambdaHandler(tracer));

Capture AWS SDK clients

To capture AWS SDK clients, you can use the captureAWSv3Client method:

import { Tracer } from '@aws-lambda-powertools/tracer';
import { SecretsManagerClient } from '@aws-sdk/client-secrets-manager';

const tracer = new Tracer({ serviceName: 'serverlessAirline' });
// Instrument the AWS SDK client
const client = tracer.captureAWSv3Client(new SecretsManagerClient({}));

export default client;

Add metadata and annotations

You can add metadata and annotations to trace:

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

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

export const handler = async (
  _event: unknown,
  _context: unknown
): Promise<void> => {
  const handlerSegment = tracer.getSegment()?.addNewSubsegment('### handler');
  handlerSegment && tracer.setSegment(handlerSegment); 

  tracer.putMetadata('paymentResponse', {
      foo: 'bar',
    });
  tracer.putAnnotation('successfulBooking', true);

  handlerSegment?.close();
  handlerSegment && tracer.setSegment(handlerSegment?.parent); 
};

Contribute

If you are interested in contributing to this project, please refer to our Contributing Guidelines.

Roadmap

The roadmap of Powertools for AWS Lambda (TypeScript) is driven by customers’ demand.
Help us prioritize upcoming functionalities or utilities by upvoting existing RFCs and feature requests, or creating new ones, in this GitHub repository.

Connect

• Powertools for AWS Lambda on Discord: #typescript - Invite link
• Email: [e-mail]

How to support Powertools for AWS Lambda (TypeScript)?

Becoming a reference customer

Knowing which companies are using this library is important to help prioritize the project internally. If your company is using Powertools for AWS Lambda (TypeScript), you can request to have your name and logo added to the README file by raising a Support Powertools for AWS Lambda (TypeScript) (become a reference) issue.

The following companies, among others, use Powertools:

• Alma Media
• AppYourself
• Bailey Nelson
• Banxware
• Caylent
• Certible
• Elva
• Flyweight
• globaldatanet
• Hashnode
• LocalStack
• Perfect Post
• Sennder
• tecRacer GmbH & Co. KG
• Trek10
• WeSchool

Sharing your work

Share what you did with Powertools for AWS Lambda (TypeScript) 💞💞. Blog post, workshops, presentation, sample apps and others. Check out what the community has already shared about Powertools for AWS Lambda ( TypeScript) here.

Using Lambda Layer

This helps us understand who uses Powertools for AWS Lambda (TypeScript) in a non-intrusive way, and helps us gain future investments for other Powertools for AWS Lambda languages. When using Layers, you can add Powertools as a dev dependency to not impact the development process.

License

This library is licensed under the MIT-0 License. See the LICENSE file.

Changelog

2.15.0 (2025-02-25)

Bug Fixes

• ci: Add permissions to jobs (#3586) (90c93ea)
• ci: fix path for latest SSM param (#3585) (e34952d)
• logger: handle illegal null/undefined as extra args (#3614) (6f99073)

Features

• idempotency: add support for custom key prefix (#3532) (7be7a83)
• logger: add circular buffer (#3593) (618cdee)
• logger: Add log buffer and flush method (#3617) (6968ca8)
• logger: Emit a warning on buffer flush (#3639) (f471552)
• logger: refresh sample rate calculation per invocation (#3644) (1d66a2a)
• parser: provide sub-path exports (#3598) (09f0aaa)