Timber v0.4.5 Timber.Eventable protocol

Converts a data structure to a Timber.Event.t. This is the heart of how custom events work. Any value passed in the :timber_event Logger metadata must implement this.

Basic map example

iex> require Logger iex> event_data = %{customer_id: “xiaus1934”, amount: 1900, currency: “USD”} iex> Logger.info(“Payment rejected”, timber_event: %{name: :payment_rejected, data: event_data})

This is the simplest example, and demonstrates Timber’s no lock-in / no code debt promise. Please see Timber.Events.CustomEvent for field explanations.

Using Timber.Events.CustomEvent

iex> require Logger iex> event = Timber.Events.CustomEvent.new(name: :payment_rejected, data: %{customer_id: “xiaus1934”, amount: 1900, currency: “USD”}) iex> Logger.info(“Payment rejected”, timber_event: event)

This adds compile time guarantees in exchange for relying on the Timber library. Please see Timber.Events.CustomEvent for field explanations.

Using your own structured events

iex> require Logger iex> defmodule PaymentRejectedEvent do iex> @derive Timber.Eventable iex> defstruct [:customer_id, :amount, :currency] iex> end iex> event = %PaymentRejectedEvent{customer_id: “xiaus1934”, amount: 1900, currency: “USD”} iex> Logger.info(“Payment rejected”, timber_event: event)

At Timber, we prefer this, the lock-in to the Timber library is minimal, and it creates a stronger contract with any downstream consumers. Such as graphing on the Timber interface, alerts, BI tools, etc.

Timing events

Any of the above examples can pass a :time_ms key. This is a special key that Timber (and other systems) can use to make assumptions about your data and enhance your experience. An example:

iex> require Logger iex> timer = Timber.Timer.start() iex> event_data = %{customer_id: “xiaus1934”, amount: 1900, currency: “USD”} iex> time_ms = Timber.Timer.duration_ms(timer) iex> Logger.info(“Payment rejected”, timber_event: %{name: :payment_rejected, data: event_data, time_ms: time_ms})

Pro tip!

We recommend defining a message(t) :: String.t method or a message attribute. This works just like the Exception behaviour. This way if event creation and logging are separated, logging is as simple as:

iex> require Logger iex> {message, metadata} = Timber.Event.logger_tuple(my_internal_event) iex> Logger.info(message, metadata)

Summary

Types

t()
t :: term

Functions

to_event(data)
to_event(any) :: t