TelemetryDecorator (TelemetryDecorator v1.0.1) View Source

A function decorator for telemetry.

Usage

defmodule MyApp.MyModule do
  use TelemetryDecorator

  @decorate telemetry([:my_app, :succeed])
  def succeed(arg1, arg2) do
    :...
  end
end

Because we're using :telemetry.span/3 under the hood, you'll get these events:

  • [:my_app, :succeed, :start]
  • [:my_app, :succeed, :stop]
  • [:my_app, :succeed, :exception]

Because we're wrapping it with Decorator, we can provide more metadata than :telemetry.span/3 usually does:

  • Any variables matched by your arguments for :start, :stop, and :exception events

  • Your function's result for :stop events (overriding any variable named result)

To include more internal variables in your :stop events, add the include option:

defmodule MyApp.MyModule do
  use TelemetryDecorator

  def succeed(why), do: succeed(why, [])

  @decorate telemetry([:my_app, :succeed], include: [:type])
  def succeed(why, opts) do
    type = Keyword.get(opts, :type, :ok)
    {type, why}
  end
end

To watch :telemetry.span/3 style events at the iex> prompt:

handler_id = TelemetryDecorator.watch([:my_app, :succeed])
MyApp.MyModule.succeed(42)
# hang up, or explicitly unwatch:
TelemetryDecorator.unwatch(handler_id)

TelemetryDecorator.watch/1 sends to remote consoles, too, and with syntax colours. See the documentation for Pretty to find out how.

Link to this section Summary

Functions

Decorate a method for telemetry.

Detach the handler attached by watch/1 or watch/2.

Attach a quick-and-dirty telemetry handler for watching events in action.

Link to this section Functions

Link to this macro

telemetry(var1)

View Source (macro)
Link to this macro

telemetry(var1, var2)

View Source (macro)
Link to this function

telemetry(event_name, opts \\ [], body, context)

View Source

Decorate a method for telemetry.

@decorate telemetry([:my_app, :succeed])
def succeed(arg1, arg2) do
  :...
end

Options include:

  • include: a list of atoms naming variables in scope at the end of your function, each of which will be included in the metadata of the :stop event.

Detach the handler attached by watch/1 or watch/2.

Delegated to :telemetry.detach/1. These calls are equivalent:

TelemetryDecorator.unwatch(handler_id)
:telemetry.detach(handler_id)
Link to this function

watch(event_prefix, handler_id \\ nil)

View Source

Attach a quick-and-dirty telemetry handler for watching events in action.

    handler_id = TelemetryDecorator.watch([:my_app, :succeed])