Óg

Óg is a small collection of debugging functions for logging data.

Note

• Functions Og.log/2 and Og.log_r/2 are primarily intended as debugging tools.

Installation

Add óg to your list of dependencies in mix.exs:

def deps, do: [{:og, "~> 1.0"}]

Ensure that :logger is started in the applications:

def application do [applications: [:logger, :og]] end

Summary

• log/2 - logs the data transformed by the inspector function and returns :ok

• log_r/2 - logs the data transformed by the inspector function and returns the original data.

• Inspection of the data before logging it can be helpful in a debugging context for example for

  • Avoiding the Protocol.UndefinedError when logging tuples.
  • Not needing to require Logger

• Formatting with Kernel.inspect on the data carries an overhead so Og.log/2 and Og.log_r/2 should be probably be reserved for debugging code in :dev environments.

Configuration

config :logger, :og,
  kernel_opts: [width: 70],
  apex_opts: [numbers: :false, color: :false],
  sanitize_by_default: :false,
  default_inspector: :kernel

Configuration options

• kernel_opts - corresponds to elixir inspect opts for IO.inspect/2 and Kernel.inspect/2, refer to https://hexdocs.pm/elixir/Inspect.Opts.html

• apex_opts - corresponds to options for the Apex.Format.format/2 function, refer to https://github.com/BjRo/apex/blob/master/lib/apex/format.ex

• sanitize_by_default - defaults to :false, when set to :true, an attempt will be made to apply the SecureLogFormatter.sanitize/1 function on the data before applying the inspection function. For this function to take any effect, the settings for SecureLogFormatter must also be placed in config.exs. See the following secure_log_formatter url for more details.

• default_inspector - corresponds to the default inspector which will apply to the data passed to the log function. This can be overriden in the options of the log function. The options are :kernel or :apex, the default is :kernel.

Example configuration for secure_log_formatter, as referenced at the following secure_log_formatter url.

config :logger,
  secure_log_formatter:
    [
      # Map and Keyword List keys who's value should be hidden
      fields: ["password", "credit_card", ~r/.*_token/],

      # Patterns which if found, should be hidden
      patterns: [~r/4[0-9]{15}/] # Simple credit card example

      # defaults to "[REDACTED]"
      replacement: "[PRIVATE]"
    ]

some examples

• Basic logging

Og.log(:this_is_a_test)

• Logging at the :warn level

Og.log(:this_is_a_test, level: :warn)

• Logging at the :warn level and with ENV specified to get richer information

Og.log(:this_is_a_test, level: :warn, env: __ENV__)

• Logging with the Apex inspector

Og.log(:this_is_a_test, inspector: :apex)

• Logging and applying sanitization with the features of secure_log_formatter

Og.log(%{credit_card: 4111111111111}, sanitize: :true)

• Logging inside a chain of piped functions

defmodule OgTest do
  def log() do
    %{first: "john", last: "doe"}
    |> Map.to_list()
    |> Enum.filter( &(&1 === {:first, "john"}))
    |> Og.log_r()
    |> List.last()
    |> Tuple.to_list()
    |> List.last()
    |> Og.log_r(env: __ENV__, inspector: :kernel, level: :info)
    |> String.upcase()
  end
end
OgTest.log()

Dependencies

• Apex library --- Björn Rochel

  • Setting the config.exs opts or the log function opts to inspector: :apex will use the Apex.Format.format/2 function from the apex library.

• SecureLogFormatter library --- Sean Callan

  • Setting config.exs opts or the log function opts to sanitize: :true will use the SecureLogFormatter.sanitize/1 function from the SecureLogFormatter library.

Todo

• Investigate adding a custom formatting module as an optional additional means of logging.

Licence

MIT