Timber v2.3.4 Timber.Events.CustomEvent View Source

The CustomEvent represents events that aren’t covered elsewhere.

Custom events can be used to structure information about events that are central to your line of business like receiving credit card payments, saving a draft of a post, or changing a user’s password.

Fields

  • type - (atom, required) This is the type of your event. It should be something unique and unchanging. It will be used to identify this event. Example: :my_event.
  • data - (map, optional) A map of data. This can be anything that can be JSON encoded. Example: %{key: "value"}.

Special data fields

Timber treats these fields as special. We’ll display them on the interface where relevant, create graphs, etc.:

  • :time_ms (float, optional) - Represents the execution time in fractional milliseconds. Example: 45.6

Example

There are 2 ways to log custom events:

  1. Log a map (simplest)
  event_data = %{customer_id: "xiaus1934", amount: 1900, currency: "USD"}
  Logger.info("Payment rejected", event: %{payment_rejected: event_data})

The :payment_rejected key is the event type, and of course the value is the data.

  1. Log a struct (advanced)

    Defining structs for your events creates a contract around your data structure. We recommend this approach when you have downstream consumers that will be affected by data structure changes.

  def PaymentRejectedEvent do
    use Timber.Events.CustomEvent, type: :payment_rejected

    @enforce_keys [:customer_id, :amount, :currency]
    defstruct [:customer_id, :amount, :currency]

    def message(%__MODULE__{customer_id: customer_id}) do
      "Payment rejected for #{customer_id}"
    end
  end

  event = %PaymentRejectedEvent{customer_id: "xiaus1934", amount: 1900, currency: "USD"}
  message = PaymentRejectedEvent.message(event)
  Logger.info(message, event: event)

Link to this section Summary

Link to this section Types

Link to this type t() View Source
t() :: %Timber.Events.CustomEvent{data: map | nil, type: atom}