Timber v3.0.0-alpha.2 Timber.Formatter View Source
Provides utilities for formatting log lines as text
This formatter is designed for use with the default :console
backend provided by
Elixir Logger. To use this, you’ll need to configure the console backend to call
the Timber.Formatter.format/4
function instead of its default formatting function.
This is done with a simple configuration change. You’ll also need to let :console
know that :all
metadata keys should be passed to the formatter.
The result of the configuration looks like:
config :logger, backends: [:console]
config :logger, :console,
format: {Timber.Formatter, :format},
metadata: :all
Further configuration options available on this module are documented below.
Configuration Recommendations: Development vs. Production
In a standard Elixir project, you will probably have different configuration files
for your development and production setups. These configuration files typically
take the form of config/dev.exs
and config/prod.exs
which override defaults set
in config/config.exs
.
Timber’s defaults are production ready, but the production settings also assume that
you’ll be viewing the logs through the Timber console, so they forego some niceties
that help when developing locally. Therefore, to help with local development, we
recommended this configuration for your :dev
environment:
# config/dev.exs
config :timber, Timber.Formatter,
colorize: true,
format: :logfmt,
print_timestamps: true
print_log_level: true
This will configure Timber to output logs in logfmt instead of JSON, print the log level and timestamps, and colorize the logs.
Transport Configuration Options
The following options are available when configuring the formatter:
colorize
When true
, the log level will be printed in a corresponding color using
ANSI console control characters to help identify it.
When false
, the log level will be printed out as standard text.
Defaults to true
.
escape_new_lines
When true
, new lines characters are escaped as \n
.
When false
, new lines characters are left alone.
This circumvents issues with output devices (like Heroku Logplex) that will tranform line breaks into multiple log lines.
The default depends on on the environment variable HEROKU
. If the environment variable
is present, this will be set to true
. Otherwise, this defaults to false
. Setting the
value in your application configuration will always override the initialized setting.
format
Determines the output format to use. Even though the Timber service is designed to receive log metadata in JSON format, it’s not the prettiest format to look at when you’re developing locally. Therefore, we let you print the metadata in logfmt locally to make it easier on the eyes.
Valid values:
:json
:logfmt
(not supported in production)
Defaults to :json
.
print_log_level
When true
, the log level is printed in brackets as part of your log message.
When false
, the log level is not printed.
Regardless of the setting used, the log level will be recorded as part of Timber’s
metadata. Setting this to false
is recommended for production usage if you only
use Timber for viewing logs.
Defaults to false
.
print_metadata
The Timber metadata contains additional information about your log lines, but this can become unwieldy in local development scenarios.
When true
, the Timber metadata is printed out at the end of the log line (starting
with the indicator “@metadata”).
When false
, the Timber metadata is not printed.
Note: This should always be true
in production.
Defaults to true
.
print_timestamps
When true
, the timestamp for the log will be output at the front
of the statement.
When false
, the timestamp will be suppressed. This is only useful in situations
where the log will be written to an evented IO service that automatically adds
timestamps for incoming data, like Heroku Logplex.
Regardless of the setting used, the timestamp will be recorded as part of Timber’s
metadata. Setting this to false
is recommended for production usage if you only
use Timber for viewing logs.
Defaults to false
.
Link to this section Summary
Link to this section Types
Link to this section Functions
Handles formatting a log for the Logger
application
This function allows you to integrate Timber with the default :console
backend
distributed with the Elixir Logger
application. By default, metadata will be
output as a JSON document after the @metadata
keyword on the line. You can also
opt for the output to be in logfmt by setting the appropriate configuration key.