Class Logger

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

Key features Capturing key fields from the Lambda context, cold starts, and structure logging output as JSON. Logging Lambda invocation events when instructed (disabled by default). Switch log level to DEBUG for a percentage of invocations (sampling). Buffering logs for a specific request or invocation, and flushing them automatically on error or manually as needed. Appending additional keys to structured logs at any point in time. Providing a custom log formatter (Bring Your Own Formatter) to output logs in a structure compatible with your organization’s Logging RFC.

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

Properties

coldStart defaultServiceName

Accessors

level

Methods

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

Constructors

constructor

Properties

ProtectedcoldStart

coldStart: boolean

Protected ReadonlydefaultServiceName

defaultServiceName: string

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

ProtectedbufferLogItem

  • bufferLogItem(xrayTraceId: string, log: LogItem, logLevel: number): void

    Add a log to the buffer.

    Parameters

    • xrayTraceId: string

      _X_AMZN_TRACE_ID of the request

    • log: LogItem

      Log to be buffered

    • logLevel: number

      The level of log to be buffered

    Returns void

clearBuffer

ProtectedcreateAndPopulateLogItem

createChild

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

flushBuffer

ProtectedgetColdStart

  • getColdStart(): boolean

    Get the cold start status of the current execution environment.

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

    Returns boolean

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

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 enrich your logs with information from the function context, such as the function name, version, and request ID, and more.

    Parameters

    • Optionaloptions: InjectLambdaContextOptions
      • OptionalclearState?: boolean

        Deprecated

        Use ()` instead.

      • OptionalflushBufferOnUncaughtError?: boolean

        Whether to flush the log buffer when an uncaught error is logged.

        Default

        false

      • OptionallogEvent?: boolean

        When true the logger will log the event.

        To avoid logging sensitive information, we recommend using this option only for debugging purposes in local environments.

      • OptionalresetKeys?: boolean

        If true, the logger will reset the keys added via ()

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

    The decorator can also be used to log the Lambda invocation event; this can be configured both via the logEvent parameter and the POWERTOOLS_LOGGER_LOG_EVENT environment variable. When both are set, the logEvent parameter takes precedence.

    Additionally, the decorator can be used to reset the temporary keys added with the appendKeys() method after the invocation, or to flush the buffer when an uncaught error is thrown in the handler.

    See

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

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

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.

    This only works for warm starts, because we don't to avoid double sampling.

    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

ProtectedshouldBufferLog

  • shouldBufferLog(traceId: undefined | string, logLevel: number): boolean

    Test if the log meets the criteria to be buffered.

    Parameters

    • traceId: undefined | string

      _X_AMZN_TRACE_ID of the request

    • logLevel: number

      The level of the log being considered

    Returns boolean

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
Properties
Accessors
Methods