@aws-lambda-powertools/logger

What is @aws-lambda-powertools/logger?

@aws-lambda-powertools/logger is a structured logging utility designed for AWS Lambda functions. It simplifies the process of creating consistent and meaningful logs, which can be crucial for debugging and monitoring serverless applications.

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

Basic Logging

This feature allows you to log basic information. The logger.info method is used to log informational messages.

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

exports.handler = async (event) => {
  logger.info('This is an info log');
  return { statusCode: 200, body: 'Hello World' };
};

Structured Logging

Structured logging allows you to add context to your logs, making them more useful for debugging and monitoring. You can add persistent attributes that will be included in every log entry.

const { Logger } = require('@aws-lambda-powertools/logger');
const logger = new Logger({
  persistentLogAttributes: {
    service: 'my-service',
    environment: 'production'
  }
});

exports.handler = async (event) => {
  logger.info('This is a structured log', { userId: '12345' });
  return { statusCode: 200, body: 'Hello World' };
};

Error Logging

This feature allows you to log errors with additional context. The logger.error method is used to log error messages.

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

exports.handler = async (event) => {
  try {
    throw new Error('Something went wrong');
  } catch (error) {
    logger.error('An error occurred', { error });
  }
  return { statusCode: 500, body: 'Internal Server Error' };
};

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

winston

Winston is a versatile logging library for Node.js that supports multiple transports (e.g., console, file, HTTP). It offers more flexibility and customization options compared to @aws-lambda-powertools/logger but requires more setup.

bunyan

Bunyan is another structured logging library for Node.js. It provides a JSON-based logging format and includes features like log levels and serializers. It is similar to @aws-lambda-powertools/logger in terms of structured logging but is more general-purpose.

pino

Pino is a fast JSON logger for Node.js applications. It is designed for high performance and low overhead. While it offers similar structured logging capabilities, it is more focused on performance compared to @aws-lambda-powertools/logger.

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
  • Inject Lambda context
  • Logging incoming event
  • Append additional keys and data
• Contribute
• Roadmap
• Connect
• How to support Powertools for AWS Lambda (TypeScript)?
  • Becoming a reference customer
  • Sharing your work
  • Using Lambda Layer
• License

Intro

The Logger utility provides a structured logging experience with additional features tailored for AWS Lambda functions.

Usage

To get started, install the library by running:

npm i @aws-lambda-powertools/logger

Basic usage

Initialize the logger with a service name and log messages:

import { Logger } from '@aws-lambda-powertools/logger';

const logger = new Logger({ serviceName: 'serverlessAirline' });

export const handler = async (_event, _context): Promise<void> => {
  logger.info('Hello World');
  
};

You can also log errors and additional data:

import { Logger } from '@aws-lambda-powertools/logger';

const logger = new Logger();

export const handler = async (
  _event: unknown,
  _context: unknown
): Promise<void> => {
  try {
    throw new Error('Unexpected error #1');
  } catch (error) {
    // Log information about the error using the default "error" key
    logger.error('This is the first error', error as Error);
  }

  try {
    throw new Error('Unexpected error #2');
  } catch (error) {
    // Log information about the error using a custom "myCustomErrorKey" key
    logger.error('This is the second error', {
      myCustomErrorKey: error as Error,
    });
  }
};

Inject Lambda context

You can enrich your structured logs with key Lambda context information:

import { Logger } from '@aws-lambda-powertools/logger';
import type { Context } from 'aws-lambda';

const logger = new Logger();

export const handler = async (
  _event: unknown,
  context: Context
): Promise<void> => {
  logger.addContext(context);

  logger.info('This is an INFO log with some context');
};

The log statement will look like this:

{
    "cold_start": true,
    "function_arn": "arn:aws:lambda:eu-west-1:123456789012:function:shopping-cart-api-lambda-prod-eu-west-1",
    "function_memory_size": 128,
    "function_request_id": "c6af9ac6-7b61-11e6-9a41-93e812345678",
    "function_name": "shopping-cart-api-lambda-prod-eu-west-1",
    "level": "INFO",
    "message": "This is an INFO log with some context",
    "service": "serverlessAirline",
    "timestamp": "2021-12-12T21:21:08.921Z",
    "xray_trace_id": "abcdef123456abcdef123456abcdef123456"
}

Logging incoming event

You can log the incoming event with (here as decorator, works also as middy middleware):

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

const logger = new Logger();

class Lambda implements LambdaInterface {
  // Set the log event flag to true
  @logger.injectLambdaContext({ logEvent: true })
  public async handler(_event: unknown, _context: unknown): Promise<void> {
    logger.info('This is an INFO log with some context');
  }
}

const myFunction = new Lambda();
export const handler = myFunction.handler.bind(myFunction); //

Append additional keys and data

Append additional keys:

import { Logger } from '@aws-lambda-powertools/logger';

const logger = new Logger();

export const handler = async (
  event: unknown,
  _context: unknown
): Promise<unknown> => {
  const myImportantVariable = {
    foo: 'bar',
  };

  // Log additional data in single log items
  // As second parameter
  logger.info('This is a log with an extra variable', {
    data: myImportantVariable,
  });

  // You can also pass multiple parameters containing arbitrary objects
  logger.info(
    'This is a log with 3 extra objects',
    { data: myImportantVariable },
    { correlationIds: { myCustomCorrelationId: 'foo-bar-baz' } },
    { lambdaEvent: event }
  );

  // Simply pass a string for logging additional data
  logger.info('This is a log with additional string value', 'string value');

  // Directly passing an object containing both the message and the additional info
  const logObject = {
    message: 'This is a log message',
    additionalValue: 42,
  };

  logger.info(logObject);

  return {
    foo: 'bar',
  };
};

Add persistent keys to the logger instance:

import { Logger } from '@aws-lambda-powertools/logger';

const logger = new Logger({
  serviceName: 'serverlessAirline',
  persistentKeys: {
    environment: 'prod',
    version: process.env.BUILD_VERSION,
  },
});

export const handler = async (
  _event: unknown,
  _context: unknown
): Promise<void> => {
  logger.info('processing transaction');

  // ... your business logic
};

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
• 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.8.0 (2024-09-16)

Bug Fixes

• idempotency: include cause in idempotency persistence layer error (#2916) (47f0161)
• tracer: include request pathname in trace data (#2955) (6864e53)

Features

• logger: introduce log key reordering functionality (#2736) (9677258)
• logger: introduce loglevel trace #1589 (#2902) (650252c)
• parameters: adds setParameter function to store SSM parameters (#3020) (8fd5479)