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)