Class Logger

Intro

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

Key features

  • Capture key fields from Lambda context, cold start and structures logging output as JSON
  • Log Lambda context when instructed (disabled by default)
  • Log sampling prints all logs for a percentage of invocations (disabled by default)
  • Append additional keys to structured log at any point in time

Usage

For more usage examples, see our documentation.

Basic usage

Example

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

// Logger parameters fetched from the environment variables:
const logger = new Logger();

Functions usage with middleware

If you use function-based Lambda handlers you can use the injectLambdaContext() middy middleware to automatically add context to your Lambda logs.

Example

import { Logger, injectLambdaContext } from '@aws-lambda-powertools/logger';
import middy from '@middy/core';

const logger = new Logger();

const lambdaHandler = async (_event: any, _context: any) => {
    logger.info('This is an INFO log with some context');
};

export const handler = middy(lambdaHandler).use(injectLambdaContext(logger));

Object oriented usage with decorators

If instead you use TypeScript classes to wrap your Lambda handler you can use the @logger.injectLambdaContext() decorator.

Example

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

const logger = new Logger();

class Lambda implements LambdaInterface {

  // FYI: Decorator might not render properly in VSCode mouse over due to https://github.com/microsoft/TypeScript/issues/47679 and might show as *@logger* instead of `@logger.injectLambdaContext`

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

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

Functions usage with manual instrumentation

If you prefer to manually instrument your Lambda handler you can use the methods in the Logger class directly.

Example

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

const logger = new Logger();

export const handler = async (_event, context) => {
    logger.addContext(context);
    logger.info('This is an INFO log with some context');
};

Implements

See

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

Hierarchy

Implements

Constructors

constructor

Accessors

level

Methods

addContext addPersistentLogAttributes appendKeys createChild createLogger critical debug error getColdStart getDefaultServiceName getLevelName getLogEvent getLogsSampled info injectLambdaContext isColdStart isValidServiceName logEventIfEnabled refreshSampleRateCalculation removeKeys removePersistentLogAttributes setLogLevel setPersistentLogAttributes setSampleRateValue shouldPrint 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

  • It adds 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

    Returns void

addPersistentLogAttributes

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

    Parameters

    Returns void

appendKeys

createChild

Protected createLogger

critical

debug

error

getColdStart

  • Returns boolean

Protected getDefaultServiceName

getLevelName

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

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

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

    The log level name.

getLogEvent

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

    Returns boolean

getLogsSampled

  • It returns a boolean value, if true all the logs will be printed.

    Returns boolean

info

injectLambdaContext

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

    The decorator can be used only when attached to a Lambda function handler which is written as method of a class, and should be declared just before the handler declaration.

    Note: Currently TypeScript only supports decorators on classes and methods. If you are using the function syntax, you should use the middleware instead.

    Parameters

    Returns HandlerMethodDecorator

    Example

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

    const logger = new Logger();

    class Lambda implements LambdaInterface {
        // Decorate your handler class method
        @logger.injectLambdaContext()
        public async handler(_event: any, _context: any): 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

  • Returns boolean

Protected isValidServiceName

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

    Parameters

    • Optional serviceName: string

      Service name to validate

    Returns boolean

logEventIfEnabled

  • Logs a Lambda invocation event, if it should.

    Parameters

    • event: unknown
    • Optional overwriteValue: boolean

    Returns void

refreshSampleRateCalculation

  • If the sample rate feature is enabled, the calculation that determines whether the logs will actually be printed or not for this invocation is done when the Logger class is initialized. This method will repeat that calculation (with possible different outcome).

    Returns void

removeKeys

  • Alias for removePersistentLogAttributes.

    Parameters

    • keys: string[]

    Returns void

removePersistentLogAttributes

  • It removes attributes based on provided keys to all log items generated by this Logger instance.

    Parameters

    • keys: string[]

    Returns void

setLogLevel

  • Set the log level for this Logger instance.

    Parameters

    • logLevel: LogLevel

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

    Returns void

setPersistentLogAttributes

  • It sets 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

setSampleRateValue

  • It sets the user-provided sample rate value.

    Parameters

    • Optional sampleRateValue: number

    Returns void

Protected shouldPrint

  • Protected

    Decides whether the current log item should be printed or not.

    The decision is based on the log level and the sample rate value. A log item will be printed if:

    1. The log level is greater than or equal to the Logger's log level.
    2. The log level is less than the Logger's log level, but the current sampling value is set to true.

    Parameters

    • logLevel: number

    Returns boolean

warn

Static injectLambdaContextAfterOrOnError

Static injectLambdaContextBefore

Settings

Member Visibility

Theme

On This Page

Generated using TypeDoc