Class Logger

The Logger utility provides an opinionated logger with output structured as JSON for AWS Lambda.

Key features

  • Capture key fields from AWS Lambda context, cold start, and structure log output as JSON
  • Append additional keys to one or all log items
  • Switch log level to DEBUG based on a sample rate value for a percentage of invocations

After initializing the Logger class, you can use the methods to log messages at different levels.

Example

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

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

export const handler = async (event, context) => {
  logger.info('This is an INFO log');
  logger.warn('This is a WARNING log');
};

To enrich the log items with information from the Lambda context, you can use the addContext() method.

Example

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

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

export const handler = async (event, context) => {
  logger.addContext(context);

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

You can also add additional attributes to all log items using the appendKeys() method.

Example

export const handler = async (event, context) => {
  logger.appendKeys({ key1: 'value1' });

  logger.info('This is an INFO log with additional keys');

  logger.removeKeys(['key1']);
};

If you write your functions as classes and use TypeScript, you can use the Logger.injectLambdaContext class method decorator to automatically add context to your logs and clear the state after the invocation.

If instead you use Middy.js middlewares, you use the injectLambdaContext() middleware.

See

https://docs.powertools.aws.dev/lambda/typescript/latest/core/logger/

Hierarchy (View Summary)

Implements

Constructors

constructor

Accessors

level

Methods

addContext addPersistentLogAttributes appendKeys appendPersistentKeys createAndPopulateLogItem createChild createLogger critical debug error getColdStart getDefaultServiceName getJsonReplacer getLevelName getLogEvent getPersistentLogAttributes info injectLambdaContext isColdStart isValidServiceName logEventIfEnabled printLog processLogItem refreshSampleRateCalculation removeKeys removePersistentKeys removePersistentLogAttributes resetKeys setLogLevel setPersistentLogAttributes shouldLogEvent trace warn injectLambdaContextAfterOrOnError injectLambdaContextBefore

Constructors

constructor

Accessors

level

  • get level(): number

    Log level used by the current instance of Logger.

    Returns the log level as a number. The higher the number, the less verbose the logs. To get the log level name, use the () method.

    Returns number

Methods

addContext

  • addContext(context: Context): void

    Add the current Lambda function's invocation context data to the powertoolLogData property of the instance. This context data will be part of all printed log items.

    Parameters

    • context: Context

      The Lambda function's invocation context.

    Returns void

addPersistentLogAttributes

appendKeys

  • appendKeys(attributes: LogKeys): void

    Add the given temporary attributes (key-value pairs) to all log items generated by this Logger instance.

    If the key already exists in the attributes, it will be overwritten. If the key is one of level, message, sampling_rate, service, or timestamp we will log a warning and drop the value.

    Parameters

    • attributes: LogKeys

      The attributes to add to all log items.

    Returns void

appendPersistentKeys

  • appendPersistentKeys(attributes: LogKeys): void

    Add the given persistent attributes (key-value pairs) to all log items generated by this Logger instance.

    If the key already exists in the attributes, it will be overwritten. If the key is one of level, message, sampling_rate, service, or timestamp we will log a warning and drop the value.

    Parameters

    • attributes: LogKeys

      The attributes to add to all log items.

    Returns void

ProtectedcreateAndPopulateLogItem

createChild

  • createChild(options?: ConstructorOptions): Logger

    Create a separate Logger instance, identical to the current one. It's possible to overwrite the new instance options by passing them.

    Parameters

    Returns Logger

ProtectedcreateLogger

  • createLogger(options?: ConstructorOptions): Logger

    Factory method for instantiating logger instances. Used by createChild method. Important for customization and subclassing. It allows subclasses, like MyOwnLogger, to override its behavior while keeping the main business logic in createChild intact.

    Parameters

    Returns Logger

    Example

    // MyOwnLogger subclass
    class MyOwnLogger extends Logger {
      protected createLogger(options?: ConstructorOptions): MyOwnLogger {
        return new MyOwnLogger(options);
      }
      // No need to re-implement business logic from `createChild` and keep track on changes
      public createChild(options?: ConstructorOptions): MyOwnLogger {
        return super.createChild(options) as MyOwnLogger;
      }
    }

critical

debug

error

getColdStart

  • getColdStart(): boolean

    Get the cold start status of the current execution environment.

    Returns boolean

    Example

    import { Utility } from '@aws-lambda-powertools/commons';

    const utility = new Utility();
    utility.isColdStart(); // true
    utility.isColdStart(); // false

    The method also flips the cold start status to false after the first invocation.

ProtectedgetDefaultServiceName

  • getDefaultServiceName(): string

    Get the default service name.

    Returns string

ProtectedgetJsonReplacer

  • getJsonReplacer(): (key: string, value: unknown) => void

    A custom JSON replacer function that is used to serialize the log items.

    By default, we already extend the default serialization behavior to handle BigInt and Error objects, as well as remove circular references. When a custom JSON replacer function is passed to the Logger constructor, it will be called before our custom rules for each key-value pair in the object being stringified.

    This allows you to customize the serialization while still benefiting from the default behavior.

    Returns (key: string, value: unknown) => void

    See

    ConstructorOptions.jsonReplacerFn

getLevelName

  • getLevelName(): | "CRITICAL"
    | "TRACE"
    | "DEBUG"
    | "INFO"
    | "WARN"
    | "ERROR"
    | "SILENT"

    Get the log level name of the current instance of Logger.

    Returns the log level name, i.e. INFO, DEBUG, etc. To get the log level as a number, use the Logger.level property.

    Returns "CRITICAL" | "TRACE" | "DEBUG" | "INFO" | "WARN" | "ERROR" | "SILENT"

getLogEvent

  • getLogEvent(): boolean

    Return a boolean value. True means that the Lambda invocation events are printed in the logs.

    Returns boolean

getPersistentLogAttributes

  • getPersistentLogAttributes(): LogAttributes

    Return the persistent log attributes, which are the attributes that will be logged in all log items.

    Returns LogAttributes

info

injectLambdaContext

  • injectLambdaContext(
        options?: InjectLambdaContextOptions,
    ): HandlerMethodDecorator

    Class method decorator that adds the current Lambda function context as extra information in all log items.

    This decorator is useful when you want to add the Lambda context to all log items and it works only when decorating a class method that is a Lambda function handler.

    Parameters

    Returns HandlerMethodDecorator

    Example

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

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

    class Lambda implements LambdaInterface {
      // Decorate your handler class method
      ⁣@logger.injectLambdaContext()
      public async handler(_event: unknown, _context: unknown): Promise<void> {
        logger.info('This is an INFO log with some context');
      }
    }

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

    See

    https://www.typescriptlang.org/docs/handbook/decorators.html#method-decorators

isColdStart

  • isColdStart(): boolean

    Get the cold start status of the current execution environment.

    Returns boolean

    Example

    import { Utility } from '@aws-lambda-powertools/commons';

    const utility = new Utility();
    utility.isColdStart(); // true
    utility.isColdStart(); // false

    See

    getColdStart

ProtectedisValidServiceName

  • isValidServiceName(serviceName?: string): boolean

    Validate that the service name provided is valid. Used internally during initialization.

    Parameters

    • OptionalserviceName: string

      Service name to validate

    Returns boolean

logEventIfEnabled

  • logEventIfEnabled(event: unknown, overwriteValue?: boolean): void

    Log the AWS Lambda event payload for the current invocation if the environment variable POWERTOOLS_LOGGER_LOG_EVENT is set to true.

    Parameters

    • event: unknown

      The AWS Lambda event payload.

    • OptionaloverwriteValue: boolean

      Overwrite the environment variable value.

    Returns void

    Example

    process.env.POWERTOOLS_LOGGER_LOG_EVENT = 'true';

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

    const logger = new Logger();

    export const handler = async (event) => {
      logger.logEventIfEnabled(event);
      // ... your handler code
    }

ProtectedprintLog

  • printLog(logLevel: number, log: LogItem): void

    Print a given log with given log level.

    Parameters

    • logLevel: number

      The log level

    • log: LogItem

      The log item to print

    Returns void

ProtectedprocessLogItem

refreshSampleRateCalculation

  • refreshSampleRateCalculation(): void

    This method allows recalculating the initial sampling decision for changing the log level to DEBUG based on a sample rate value used during initialization, potentially yielding a different outcome.

    Returns void

removeKeys

  • removeKeys(keys: string[]): void

    Remove temporary attributes based on provided keys to all log items generated by this Logger instance.

    Parameters

    • keys: string[]

      The keys to remove.

    Returns void

removePersistentKeys

  • removePersistentKeys(keys: string[]): void

    Remove the given keys from the persistent keys.

    Parameters

    • keys: string[]

      The keys to remove from the persistent attributes.

    Returns void

    Example

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

    const logger = new Logger({
      persistentKeys: {
        environment: 'prod',
      },
    });

    logger.removePersistentKeys(['environment']);

removePersistentLogAttributes

  • removePersistentLogAttributes(keys: string[]): void

    Parameters

    • keys: string[]

    Returns void

    Deprecated

    This method is deprecated and will be removed in the future major versions. Use () instead.

resetKeys

setLogLevel

  • setLogLevel(logLevel: LogLevel): void

    Set the log level for this Logger instance.

    If the log level is set using AWS Lambda Advanced Logging Controls, it sets it instead of the given log level to avoid data loss.

    Parameters

    • logLevel: LogLevel

      The log level to set, i.e. error, warn, info, debug, etc.

    Returns void

setPersistentLogAttributes

  • setPersistentLogAttributes(attributes: LogKeys): void

    Parameters

    Returns void

    Deprecated

    This method is deprecated and will be removed in the future major versions, please use () appendPersistentKeys() instead.

shouldLogEvent

  • shouldLogEvent(overwriteValue?: boolean): boolean

    Check whether the current Lambda invocation event should be printed in the logs or not.

    Parameters

    • OptionaloverwriteValue: boolean

      Overwrite the environment variable value.

    Returns boolean

trace

warn

StaticinjectLambdaContextAfterOrOnError

StaticinjectLambdaContextBefore

Settings

Member Visibility

On This Page

Constructors
Accessors
Methods