Logger.Backends.Logfmt (LoggerLogfmt v2.0.0)

View Source

A Logfmt formatter for Elixir's Logger.

This module provides functions to format log messages in the logfmt format, a structured logging format that is easy to parse and human-readable.

Features

  • Flexible format configuration with customizable fields
  • Support for metadata filtering (whitelist/blacklist modes)
  • Multiple timestamp formats (Elixir, ISO8601, Unix epoch)
  • Automatic quoting and escaping of values
  • Nested map support with dot notation

Configuration

Configure the formatter in your config/config.exs:

config :logger, :logfmt,
  format: [:timestamp, :level, :message, :metadata],
  metadata: [:application, :request_id],
  mode: :whitelist,
  timestamp_format: :iso8601

Format Options

The :format option accepts a list of atoms that determine which fields to include in the output:

  • :timestamp - Log event timestamp
  • :level - Log level (debug, info, warn, error)
  • :message - Log message
  • :domain - Logger domain
  • :node - Node name
  • :pid - Process identifier
  • :metadata - Additional metadata
  • :file - Source file
  • :line - Line number

Examples

iex> result = Logger.Backends.Logfmt.format(:info, "User logged in", {{2024, 1, 15}, {10, 30, 45, 123}}, [user_id: 42])
iex> output = IO.iodata_to_binary(result)
iex> output =~ ~r/timestamp=2024-01-15T10:30:45.123/
true
iex> output =~ ~r/level=info/
true
iex> output =~ ~r/message="User logged in"/
true

Summary

Types

format_field()

One of the atoms accepted in the :format option, selecting a field to render.

mode()

Metadata filtering mode: :whitelist includes only the listed keys, :blacklist excludes them.

timestamp()

The timestamp tuple Elixir's :logger passes to a formatter's format/4 callback.

Functions

format(level, message, timestamp, metadata, opts \\ [])

Formats a log message in logfmt format.

Types

format_field()

@type format_field() ::
  :timestamp
  | :level
  | :message
  | :domain
  | :node
  | :pid
  | :metadata
  | :file
  | :line

One of the atoms accepted in the :format option, selecting a field to render.

mode()

@type mode() :: :whitelist | :blacklist

Metadata filtering mode: :whitelist includes only the listed keys, :blacklist excludes them.

timestamp()

@type timestamp() ::
  {{non_neg_integer(), 1..12, 1..31}, {0..23, 0..59, 0..59, 0..999}}

The timestamp tuple Elixir's :logger passes to a formatter's format/4 callback.

Functions

format(level, message, timestamp, metadata, opts \\ [])

@spec format(Logger.level(), Logger.message(), timestamp(), keyword(), keyword()) ::
  iodata()

Formats a log message in logfmt format.

This is the function configured as {Logger.Backends.Logfmt, :format} in config :logger, :console, format: ... - Elixir's :logger application calls it once per log event with that event's level, message, timestamp, and metadata.

Parameters

  • level - The log level (:debug, :info, :warning, :error, etc. - see Logger.level/0)
  • message - The log message
  • timestamp - The timestamp tuple {{year, month, day}, {hour, minute, second, millisecond}}
  • metadata - A keyword list of metadata
  • opts - Optional keyword list of formatting options (merged over config :logger, :logfmt); see format_field/0 and mode/0 for the atoms accepted below
    • :format - list of format_field/0 fields to include, in order (default: all fields)
    • :metadata - :default or an explicit list of metadata keys to whitelist/blacklist
    • :mode - mode/0, :whitelist (default) or :blacklist
    • :delimiter - key-value delimiter character (default: ?=)
    • :timestamp_format - :elixir, :iso8601 (default), or :epoch_time
    • :metadata_timestamp_format - same formats, applied to DateTime/NaiveDateTime metadata values (default: :epoch_time)
    • :timestamp_key, :level_key, :message_key, :domain_key, :node_key, :pid_key, :file_key, :line_key - rename the corresponding output key

Returns

An iolist containing the formatted log message.

Examples

iex> result = Logger.Backends.Logfmt.format(:info, "Hello", {{2024, 1, 1}, {12, 0, 0, 0}}, [])
iex> output = IO.iodata_to_binary(result)
iex> output =~ ~r/level=info/
true
iex> output =~ ~r/message=Hello/
true