Formatter

CLASS	DESCRIPTION
BasePowertoolsFormatter
LambdaPowertoolsFormatter	Powertools for AWS Lambda (Python) Logging formatter.

BasePowertoolsFormatter

Bases: Formatter

METHOD	DESCRIPTION
clear_state	Removes any previously added logging keys
thread_safe_clear_keys	Removes any previously added logging keys in a specific thread

clear_state abstractmethod

clear_state() -> None

Removes any previously added logging keys

Source code in aws_lambda_powertools/logging/formatter.py

@abstractmethod
def clear_state(self) -> None:
    """Removes any previously added logging keys"""
    raise NotImplementedError()

thread_safe_clear_keys

thread_safe_clear_keys() -> None

Removes any previously added logging keys in a specific thread

Source code in aws_lambda_powertools/logging/formatter.py

def thread_safe_clear_keys(self) -> None:
    """Removes any previously added logging keys in a specific thread"""
    raise NotImplementedError()

LambdaPowertoolsFormatter

LambdaPowertoolsFormatter(
    json_serializer: (
        Callable[[LogRecord], str] | None
    ) = None,
    json_deserializer: (
        Callable[[dict | str | bool | int | float], str]
        | None
    ) = None,
    json_default: Callable[[Any], Any] | None = None,
    datefmt: str | None = None,
    use_datetime_directive: bool = False,
    log_record_order: list[str] | None = None,
    utc: bool = False,
    use_rfc3339: bool = False,
    serialize_stacktrace: bool = True,
    **kwargs
)

Bases: BasePowertoolsFormatter

Powertools for AWS Lambda (Python) Logging formatter.

Formats the log message as a JSON encoded string. If the message is a dict it will be used directly.

The log_record_order kwarg is used to specify the order of the keys used in the structured json logs. By default the order is: "level", "location", "message", "timestamp", "service".

Other kwargs are used to specify log field format strings.

PARAMETER	DESCRIPTION
json_serializer	function to serialize obj to a JSON formatted str, by default json.dumps TYPE: Callable DEFAULT: None
json_deserializer	function to deserialize str, bytes, bytearraycontaining a JSON document to a Pythonobj`, by default json.loads TYPE: Callable DEFAULT: None
json_default	function to coerce unserializable values, by default str Only used when no custom JSON encoder is set TYPE: Callable DEFAULT: None
datefmt	String directives (strftime) to format log timestamp. See https://docs.python.org/3/library/time.html#time.strftime or TYPE: str DEFAULT: None
use_datetime_directive	Interpret datefmt as a format string for datetime.datetime.strftime, rather than time.strftime - Only useful when used alongside datefmt. See https://docs.python.org/3/library/datetime.html#strftime-strptime-behavior . This also supports a custom %F directive for milliseconds. TYPE: bool DEFAULT: False
utc	set logging timestamp to UTC, by default False to continue to use local time as per stdlib TYPE: bool DEFAULT: False
use_rfc3339	Whether to use a popular dateformat that complies with both RFC3339 and ISO8601. e.g., 2022-10-27T16:27:43.738+02:00. TYPE: bool DEFAULT: False
log_record_order	set order of log keys when logging, by default ["level", "location", "message", "timestamp"] TYPE: list DEFAULT: None
kwargs	Key-value to be included in log messages DEFAULT: {}

METHOD	DESCRIPTION
append_context_keys	Context manager to temporarily add logging keys.
format	Format logging record as structured JSON str
serialize	Serialize structured log dict to JSON str

Source code in aws_lambda_powertools/logging/formatter.py

def __init__(
    self,
    json_serializer: Callable[[LogRecord], str] | None = None,
    json_deserializer: Callable[[dict | str | bool | int | float], str] | None = None,
    json_default: Callable[[Any], Any] | None = None,
    datefmt: str | None = None,
    use_datetime_directive: bool = False,
    log_record_order: list[str] | None = None,
    utc: bool = False,
    use_rfc3339: bool = False,
    serialize_stacktrace: bool = True,
    **kwargs,
) -> None:
    """Return a LambdaPowertoolsFormatter instance.

    The `log_record_order` kwarg is used to specify the order of the keys used in
    the structured json logs. By default the order is: "level", "location", "message", "timestamp",
    "service".

    Other kwargs are used to specify log field format strings.

    Parameters
    ----------
    json_serializer : Callable, optional
        function to serialize `obj` to a JSON formatted `str`, by default json.dumps
    json_deserializer : Callable, optional
        function to deserialize `str`, `bytes`, bytearray` containing a JSON document to a Python `obj`,
        by default json.loads
    json_default : Callable, optional
        function to coerce unserializable values, by default str

        Only used when no custom JSON encoder is set

    datefmt : str, optional
        String directives (strftime) to format log timestamp.

        See https://docs.python.org/3/library/time.html#time.strftime or
    use_datetime_directive: str, optional
        Interpret `datefmt` as a format string for `datetime.datetime.strftime`, rather than
        `time.strftime` - Only useful when used alongside `datefmt`.

        See https://docs.python.org/3/library/datetime.html#strftime-strptime-behavior . This
        also supports a custom %F directive for milliseconds.
    utc : bool, optional
        set logging timestamp to UTC, by default False to continue to use local time as per stdlib
    use_rfc3339: bool, optional
        Whether to use a popular dateformat that complies with both RFC3339 and ISO8601.
        e.g., 2022-10-27T16:27:43.738+02:00.
    log_record_order : list, optional
        set order of log keys when logging, by default ["level", "location", "message", "timestamp"]
    kwargs
        Key-value to be included in log messages

    """

    self.json_deserializer = json_deserializer or json.loads
    self.json_default = json_default or str
    self.json_indent = (
        constants.PRETTY_INDENT if powertools_dev_is_set() else constants.COMPACT_INDENT
    )  # indented json serialization when in AWS SAM Local
    self.json_serializer = json_serializer or partial(
        json.dumps,
        default=self.json_default,
        separators=(",", ":"),
        indent=self.json_indent,
        ensure_ascii=False,  # see #3474
    )

    self.datefmt = datefmt
    self.use_datetime_directive = use_datetime_directive

    self.utc = utc
    self.log_record_order = log_record_order or ["level", "location", "message", "timestamp"]
    self.log_format = dict.fromkeys(self.log_record_order)  # Set the insertion order for the log messages
    self.update_formatter = self.append_keys  # alias to old method
    self.use_rfc3339_iso8601 = use_rfc3339

    if self.utc:
        self.converter = time.gmtime
    else:
        self.converter = time.localtime

    self.keys_combined = {**self._build_default_keys(), **kwargs}
    self.log_format.update(**self.keys_combined)

    self.serialize_stacktrace = serialize_stacktrace

    super().__init__(datefmt=self.datefmt)

append_context_keys

append_context_keys(
    **additional_keys: Any,
) -> Generator[None, None, None]

Context manager to temporarily add logging keys.

PARAMETER	DESCRIPTION
**additional_keys	Key-value pairs to include in the log context during the lifespan of the context manager. TYPE: Any DEFAULT: {}

Example

logger = Logger(service="example_service")
with logger.append_context_keys(user_id="123", operation="process"):
    logger.info("Log with context")
logger.info("Log without context")

Source code in aws_lambda_powertools/logging/formatter.py

@contextmanager
def append_context_keys(self, **additional_keys: Any) -> Generator[None, None, None]:
    """
    Context manager to temporarily add logging keys.

    Parameters
    -----------
    **additional_keys: Any
        Key-value pairs to include in the log context during the lifespan of the context manager.

    Example
    --------
        logger = Logger(service="example_service")
        with logger.append_context_keys(user_id="123", operation="process"):
            logger.info("Log with context")
        logger.info("Log without context")
    """
    # Add keys to the context
    self.append_keys(**additional_keys)
    try:
        yield
    finally:
        # Remove the keys after exiting the context
        self.remove_keys(additional_keys.keys())

format

format(record: logging.LogRecord) -> str

Format logging record as structured JSON str

Source code in aws_lambda_powertools/logging/formatter.py

def format(self, record: logging.LogRecord) -> str:  # noqa: A003
    """Format logging record as structured JSON str"""
    formatted_log = self._extract_log_keys(log_record=record)
    formatted_log["message"] = self._extract_log_message(log_record=record)

    # exception and exception_name fields can be added as extra key
    # in any log level, we try to extract and use them first
    extracted_exception, extracted_exception_name = self._extract_log_exception(log_record=record)
    formatted_log["exception"] = formatted_log.get("exception", extracted_exception)
    formatted_log["exception_name"] = formatted_log.get("exception_name", extracted_exception_name)
    if self.serialize_stacktrace:
        # Generate the traceback from the traceback library
        formatted_log["stack_trace"] = self._serialize_stacktrace(log_record=record)
    formatted_log["xray_trace_id"] = self._get_latest_trace_id()
    formatted_log = self._strip_none_records(records=formatted_log)

    return self.serialize(log=formatted_log)

serialize

serialize(log: LogRecord) -> str

Serialize structured log dict to JSON str

Source code in aws_lambda_powertools/logging/formatter.py

def serialize(self, log: LogRecord) -> str:
    """Serialize structured log dict to JSON str"""
    return self.json_serializer(log)