A collection of formatters and utilities for JSON-based logging for various cloud tools and platforms.

Supported formatters

• LoggerJSON.Formatters.Basic - a basic JSON formatter that logs messages in a structured format, can be used with any JSON-based logging system, like ElasticSearch, Logstash, etc.

• LoggerJSON.Formatters.GoogleCloud - a formatter that logs messages in a structured format that can be consumed by Google Cloud Logger and Google Cloud Error Reporter.

• LoggerJSON.Formatters.Datadog - a formatter that logs messages in a structured format that can be consumed by Datadog.

• LoggerJSON.Formatters.Elastic - a formatter that logs messages in a structured format that conforms to the Elastic Common Schema (ECS), so it can be consumed by ElasticSearch, LogStash, FileBeat and Kibana.

Installation

Add logger_json to your list of dependencies in mix.exs:

def deps do
  [
    # ...
    {:logger_json, "~> 6.1"}
    # ...
  ]
end

and install it running mix deps.get.

Then, enable the formatter in your config.exs:

config :logger, :default_handler,
  formatter: {LoggerJSON.Formatters.Basic, []}

or during runtime (eg. in your application.ex):

:logger.update_handler_config(:default, :formatter, {Basic, %{}})

Configuration

Configuration can be set using 2nd element of the tuple of the :formatter option in Logger configuration. For example in config.exs:

config :logger, :default_handler,
  formatter: {LoggerJSON.Formatters.GoogleCloud, metadata: :all, project_id: "logger-101"}

or during runtime:

:logger.update_handler_config(:default, :formatter, {Basic, %{metadata: {:all_except, [:conn]}}})

Shared Options

Some formatters require additional configuration options. Here are the options that are common for each formatter:

• :encoder_opts - options to be passed directly to the JSON encoder. This allows you to customize the behavior of the JSON encoder. See the documentation for Jason for available options. By default, no options are passed to the encoder.

• :metadata - a list of metadata keys to include in the log entry. By default, no metadata is included. If :allis given, all metadata is included. If {:all_except, keys} is given, all metadata except the specified keys is included. If {:from_application_env, {app, module}, path} is given, the metadata is fetched from the application environment (eg. {:from_application_env, {:logger, :default_formatter}, [:metadata]}) on each logged message.

• :redactors - a list of tuples, where first element is the module that implements the LoggerJSON.Redactor behaviour, and the second element is the options to pass to the redactor module. By default, no redactors are used.

Metadata

You can set some well-known metadata keys to be included in the log entry. The following keys are supported for all formatters:

• :conn - the Plug.Conn struct, setting it will include the request and response details in the log entry;
• :crash_reason - a tuple where the first element is the exception struct and the second is the stacktrace. For example: Logger.error("Exception!", crash_reason: {e, __STACKTRACE__}). Setting it will include the exception details in the log entry.

Formatters may encode the well-known metadata differently and support additional metadata keys, see the documentation of the formatter for more details.