🌲 Timber - Log Better. Solve Problems Faster.

ISC License Hex.pm Documentation Build Status

Overview

Timber for Elixir is an optional upgrade you can install for Elixir apps on the Timber.io logging platform. Instead of completely replacing your log messages, Timber augments your logs with critical metadata. Turning them into rich events with context. This preserves the readability of your logs while still improving the quality of your log data.

How it works

For example, Timber turns this raw text log:

Sent 200 in 45.ms

Into a rich http_server_response event.

Sent 200 in 45.2ms @metadata {"dt": "2017-02-02T01:33:21.154345Z", "level": "info", "context": {"user": {"id": 1}, "http": {"method": "GET", "host": "timber.io", "path": "/path", "request_id": "abcd1234"}}, "event": {"http_response": {"status": 200, "time_ms": 45.2}}}

In the Timber console simply click the line to view this metdata. Moreover, this data allows you to run powerful queries like:

  1. context.request_id:abcd1234 - View all logs generated for a specific request.
  2. context.user.id:1 - View logs generated by a specific user.
  3. type:http_response - View specific events (exceptions, sql queries, etc)
  4. http_server_response.time_ms:>=1000 - View slow responses with the ability to zoom out and view them in context (request, user, etc).
  5. level:error - Levels in your logs!

For a complete overview, see the Timber for Elixir docs.

Installation

  1. Add timber as a dependency in mix.exs:

    # Mix.exs
    
    def application do
      [applications: [:timber]]
    end
    
    def deps do
      [{:timber, "~> 2.1"}]
    end
  2. In your shell, run mix deps.get.

  3. In your shell, run mix timber.install.

Usage

Basic text logging

No special API, Timber works directly with [`Logger`](https://hexdocs.pm/logger/Logger.html): ```elixir Logger.info("My log message") # => My log message @metadata {"level": "info", "context": {...}} ``` ---

Structured logging (metadata)

Simply use Elixir's native Logger metadata: ```elixir Logger.info("Payment rejected", meta: %{customer_id: "abcd1234", amount: 100, currency: "USD"}) # => My log message @metadata {"level": "info", "meta": {"customer_id": "abcd1234", "amount": 100}} ``` * In the [Timber console](https://app.timber.io) use the query: `customer_id:abcd1234` or `amount:>100`. * **Warning:** metadata keys must use consistent types as the values. If `customer_id` key was sent an integer, it would not be indexed because it was first sent a string. See the "Custom events" example below if you'd like to avoid this. See [when to use metadata or events](#jibber-jabber). ---

Custom events

Events are just defined structures with a namespace. They are more formal and avoid type collisions. Custom events, specifically, allow you to extend beyond events already defined in the [`Timber.Events`](lib/timber/events) namespace. ```elixir event_data = %{customer_id: "xiaus1934", amount: 1900, currency: "USD"} Logger.info("Payment rejected", event: %{payment_rejected: event_data}) # => Payment rejected @metadata {"level": "warn", "event": {"payment_rejected": {"customer_id": "xiaus1934", "amount": 100, "reason": "Card expired"}}, "context": {...}} ``` * In the [Timber console](https://app.timber.io) use the query: `type:payment_rejected` or `payment_rejected.amount:>100`. * See [when to use metadata or events](#jibber-jabber) ---

Custom contexts

Context is additional data shared across log lines. Think of it like log join data. It's stored in the local process dictionary and is incldued in every log written within that process. Custom contexts allow you to extend beyond contexts already defined in the [`Timber.Contexts`](lib/timber/contexts) namespace. ```elixir Timber.add_context(build: %{version: "1.0.0"}) Logger.info("My log message") # => My log message @metadata {"level": "info", "context": {"build": {"version": "1.0.0"}}} ``` * Notice the `:build` root key. Timber will classify this context as such. * In the [Timber console](https://app.timber.io) use the query: `build.version:1.0.0`

Metrics

Logging metrics is accomplished by logging custom events. Please see our [metrics docs page](https://timber.io/docs/elixir/metrics/) for a more detailed explanation with examples.

## Jibber-Jabber
Which log events does Timber structure for me?

Out of the box you get everything in the [`Timber.Events`](lib/timber/events) namespace. We also add context to every log, everything in the [`Timber.Contexts`](lib/timber/contexts) namespace. Context is structured data representing the current environment when the log line was written. It is included in every log line. Think of it like join data for your logs. ---

What about my current log statements?

They'll continue to work as expected. Timber adheres strictly to the default [`Logger`](https://hexdocs.pm/logger/Logger.html) interface and will never deviate in *any* way. In fact, traditional log statements for non-meaningful events, debug statements, etc, are encouraged. In cases where the data is meaningful, consider [logging a custom event](#usage).

When to use metadata or events?

At it's basic level, both metadata and eventa serve the same purpose: they add structured data to your logs. And anyone that's implemented structured logging know's this can quickly get out of hand. This is why we created events. Here's how we recommend using them: 1. Use `events` when the log cleanly maps to an event that is core to your business. Something that you'd like to alert on, graph, or use in a meaningful way. 2. Use metadata for debugging purposes; when you simply want additional insight without polluting the message. ### Example: Logging that a payment was rejected This is clearly an event that is meaningful to your business. You'll probably want to alert and graph this data. So let's log it as an official event: ```elixir event_data = %{customer_id: "xiaus1934", amount: 1900, currency: "USD"} Logger.info("Payment rejected", event: %{payment_rejected: event_data}) ``` ### Example: Gaining additional insight before an error occurs This is not an event, but it is helpful data. Let's add it as metadata so that we don't pollute the message, ensuring the log is reable: ```elixir Logger.info("Received parameters", meta: %{parameters: %{key: "val"}}) ``` ---

---