Handles instrumentation of Phoenix.Endpoint.

This module is designed to log events when Phoenix calls a controller or renders a template. It hooks into the instrumentation tools built into Phoenix. Because of this, you will have to trigger a Phoenix recompile in order for the instrumentation to take effect.

Adding Instrumentation

Phoenix instrumenetation is controlled through the configuration for your Phoenix endpoint module, typically named along the lines of MyApp.Endpoint. This module will be configured in config/config.exs similar to the following:

config :my_app, MyApp.Endpoint,
  http: [port: 4001],
  root: Path.dirname(__DIR__),
  pubsub: [name: MyApp.PubSub,
            adapter: Phoenix.PubSub.PG2]

You will need to add an :instrumenters key to this configuration with a value of [Timber.Phoenix]. This would update the configuration to something like the following:

config :my_app, MyApp.Endpoint,
  http: [port: 4001],
  root: Path.dirname(__DIR__),
  instrumenters: [Timber.Phoenix],
  pubsub: [name: MyApp.PubSub,
            adapter: Phoenix.PubSub.PG2]

In order for this to take affect locally, you will need to recompile Phoenix using the command mix deps.compile phoenix. By default, Timber will log calls to controllers and template renders at the :info level. You can change this by adding an additional configuration line:

config :timber_phoenix, :instrumentation_level, :debug

If you're currently displaying logs at the :debug level, you will also see that Phoenix has built-in logging already at this level. The Phoenix logger will not emit Timber events, so you can turn it off to stop the duplicate output. The Phoenix logger is controlled through the MyApp.Web module. Look for a definition block like the following:

def controller do
  quote do
    use Phoenix.Controller
  end
end

You will want to modify this to the following

def controller do
  quote do
    use Phoenix.Controller, log: false
  end
end

Ignoring Controller Actions for Instrumentation

If you have specific controller actions that you don't want to be instrumented, you can add them to the instrumentation blacklist. For example, if your application provides a health controller for external applications, you may want to stop instrumentation on that controller's actions to reduce noise.

The :parsed_controller_actions_blacklist configuration key can be used to control which controller actions to suppress instrumentation for. It takes a list of two-element tuples. The first element is the controller name, and the second element is the action.

If you would like to blacklist a specific controller or action, nil can be used as a wildcard.

As an example, here's how we would prevent instrumentation of the :check action in TimberClientAPI.HealthController and every action in the PostController:

config :timber_phoenix,
  parsed_controller_actions_blacklist: MapSet.new([
    {TimberClientAPI.HealthController, :check}
    {TimberClientAPI.PostController, nil}
  ])

Now, when Phoenix calls check/2 on the TimberClientAPI.HealthController module, no log lines will be produced!

Note: If you're on a version of Phoenix prior to 1.3, you will still see logs for render events even if the controller is blacklisted.