API Reference
    Preparing search index...

    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.

    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.

    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.

    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.

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

    Hierarchy (View Summary)

    Implements

    Index

    Constructors

    constructor

    Properties

    coldStart defaultServiceName

    Accessors

    level

    Methods

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

    Constructors

    Properties

    coldStart: boolean
    defaultServiceName: string

    Accessors

    • 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

    • 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

    • 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

    • 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

    • 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

    • 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

      // 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;
        }
      }

    • 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

    • Get the value of the AWS_LAMBDA_INITIALIZATION_TYPE environment variable.

      Returns "unknown" | "on-demand" | "provisioned-concurrency"

    • 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

      ConstructorOptions.jsonReplacerFn

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

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

      Returns boolean

    • 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

        Options for the () method.

        • OptionalclearState?: boolean

          Use ()` instead.

        • OptionalcorrelationIdPath?: string

          The path to the correlation ID in the event object, used to extract the correlation ID from the event object and add it to the log attributes.

        • OptionalflushBufferOnUncaughtError?: boolean

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

          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

      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.

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

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

      Parameters

      • OptionalserviceName: string

        Service name to validate

      Returns boolean

    • 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

      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
      }

    • 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

    • 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

    • Remove the given keys from the persistent keys.

      Parameters

      • keys: string[]

        The keys to remove from the persistent attributes.

      Returns void

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

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

      logger.removePersistentKeys(['environment']);

    • Parameters

      • keys: string[]

      Returns void

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

    • Set the correlation ID for the log item.

      This method can be used to set the correlation ID for the log item or to search for the correlation ID in the event.

      Parameters

      • value: unknown

        The value to set as the correlation ID or the event to search for the correlation ID

      • OptionalcorrelationIdPath: string

        Optional JMESPath expression to extract the correlation ID for the payload

      Returns void

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

      const logger = new Logger();
      logger.setCorrelationId('my-correlation-id'); // sets the correlation ID directly with the first argument as value

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

      const logger = new Logger({ correlationIdSearchFn: search });
      logger.setCorrelationId(event, 'requestContext.requestId'); // sets the correlation ID from the event using JMSPath expression

    • 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

    • 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

    • 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

    Settings

    Member Visibility

    On This Page

    Constructors
    Properties
    Accessors
    Methods