Timber v1.1.11 Timber.Transports.IODevice

The IODevice transport mechanism allows you to log directly to stdout (default; see below) or any other IODevice of your choice

Default Output

The suggestion above is that the default configuration of this transport will log to stdout by default. This is true in most cases, but it is misleadingly generic. The output will actually be sent to the process registered under the name :user. This process is registered by the VM at startup and is designed to handle IO redirection. In other words, :user is the middleman that will typically write to stdout unless you have additional configuration that would make it redirect output elsewhere.

Synchronicity

The IODevice transport will output messages asynchronously to the IO device using standard BEAM process messaging. After sending output to be written, the transport will begin buffering all new log events. When the remote IO device responds that the output was successful, the buffer will be flushed to the IO device, repeating the process. If the buffer reaches its maximum size, the transport will switch to simulated synchronous mode, blocking until the IO device sends a response about the last write operation.

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, :io_device,
  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 IODevice logger:

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.

When the IODevice transport is initialized, it will check for 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.

max_buffer_size

The maximum number of log entries that the log event buffer will hold until the transport switchs to synchronous mode. This value should be tuned to accomodate your system’s IO capability versus the amount of logging you perform.

Defaults to 100.

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 “timber.io”).

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.