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

  • addPersistentLogAttributes(attributes: LogAttributes): void

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

    Parameters

    • attributes: LogAttributes

      The attributes to add to all log items.

    Returns void

    Deprecated

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

appendKeys

  • appendKeys(attributes: LogAttributes): void

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

    Parameters

    • attributes: LogAttributes

      The attributes to add to all log items.

    Returns void

appendPersistentKeys

  • appendPersistentKeys(attributes: LogAttributes): void

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

    Parameters

    • attributes: LogAttributes

      The attributes to add to all log items.

    Returns void

ProtectedcreateAndPopulateLogItem

  • createAndPopulateLogItem(
        logLevel: number,
        input: LogItemMessage,
        extraInput: LogItemExtraInput,
    ): LogItem

  • Create a log item and populate it with the given log level, input, and extra input.

    We start with creating an object with base attributes managed by Powertools. Then we create a second object with persistent attributes provided by customers either directly to the log entry or through initial configuration and appendKeys method.

    Once we have the two objects, we pass them to the formatter that will apply the desired formatting to the log item.

    Parameters

    • logLevel: number

      The log level of the log item to be printed

    • input: LogItemMessage

      The main input of the log item, this can be a string or an object with additional attributes

    • extraInput: LogItemExtraInput

      Additional attributes to be added to the log item

    Returns LogItem

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[]

      The keys to remove.

    Returns void

    Deprecated

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

resetKeys

  • resetKeys(): void

  • Remove all temporary log attributes added with appendKeys() method.

    Returns void

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: LogAttributes): void

  • Set the given attributes (key-value pairs) to all log items generated by this Logger instance. Note: this replaces the pre-existing value.

    Parameters

    Returns void

    Deprecated

    This method is deprecated and will be removed in the future major versions, please use () 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