Medea

Sorceress, wife to Jason, tiny logger of nicely formatted structured messages.

Medea is a tiny package that provides a formatter and a translator to preserve structured logs. For example, here is the difference between structured logging with inspection and the structured JSON we’d expect:

# Inspected
"message":"%{args: %{id: 1, on: false}}"

# Structured
"message":{"args":{"id":1, "on":false}}

The former contains an inspected Elixir map, while the latter is easily parsable as JSON.

With Medea, all terms are safely escaped and converted to JSON printable values. That means structured logging like this:

Logger.info(event: %{name: :stuff, safe: false}, user: %User{id: 123})

Outputs nested JSON like this:

{
  "level":"info",
  "message":{
    "event":{
      "name":"stuff",
      "safe":false
    },
    "user":{
      "id":123
    }
  },
  "metadata":[],
  "time":"2022-10-11T15:07:33.000"
}

Installation

The package can be installed by adding medea to your list of dependencies in mix.exs:

def deps do
  [
    {:medea, "~> 0.1"}
  ]
end

Usage

Medea has two components: Medea.Formatter and Medea.Translator. For complete functionality, both components must be configured.

First, configure the logger backend with the formatter:

config :logger, :console,
  format: {Medea.Formatter, :format},
  metadata: [:request_id]

Next, enable the translator at the top of your applications start/2 function:

def start(_type, _args) do
  Logger.add_translator({Medea.Translator, :translate})

  children = [
    # whichever children you have
  ]

  Supervisor.start_link(children, strategy: :one_for_one, name: MyApp.Supervisor)
end

Logging With Ecto

If you’re using Ecto, you should disable the default logger:

config :my_app, MyApp.Repo, log: false

Now replace it with a simple telemetry based instrumenter that logs structured queries with metadata:

defmodule MyApp.EctoLogger do
  @moduledoc false

  require Logger

  def handle_event(_event, measure, %{query: query, repo: repo}, level) do
    query_meta = Map.take(measure, ~w(idle_time queue_time query_time decode_time total_time)a)

    Logger.log(level, query, repo: inspect(repo), query: query_meta)
  end
end

Attach the logger with telemetry:

:telemetry.attach(
  "ecto-logger",
  [:my_app, :repo, :query],
  &MyApp.EctoLogger.handle_event/4,
  :info
)

Additional documentation can be found at https://hexdocs.pm/medea.