Notion is a thin wrapper around :telemetry
that defines functions that dispatch telemetry events, documentation, and specs for your applications events.
The package can be installed by adding notion
to your list of dependencies in mix.exs
:
def deps do
[
{:notion, "~> 0.2.0"}
]
end
Add an Instrumentation
module and use Notion
.
Specify an app :name
to be prepended to all events dispatched to telemetry. Optionally you can set metadata
that will be the defaults and merged with lower precendence for all events.
defmodule MyApp.Instrumentation do
use Notion, name: :my_app, metadata: %{env: "prod"}
@doc "Processed an HTTP request"
# Generate a default typespec of http_request(map, map) :: :ok
defevent [:http, :request]
@doc "Docs for my [:my_app, :cc_charge, :succeeded] event"
# Override a typespec
@spec cc_charge_succeeded(integer, map) :: :ok
defevent [:cc_charge, :succeeded]
@doc "Docs for my [:my_app, :cc_charge, :failed] event"
defevent [:cc_charge, :failed]
end
A default @moduledoc
will be generated for your module. To override it, simple re-define @moduledoc
. Four "variables" exist that can be interpolated into your docs:
MODULE_NAME
- The name of the module using NotionNOTION_NAME
- will be the valuename
inuse Notion, name: :foo
NOTION_EVENTS
- a markdown formatted unordered list of emitted eventsNOTION_DEFAULT_METADATA
the default metadata added to events, if set.
Notion will create two functions for each event, described below. In additiona any @doc
provided before the defevent
call will be associated to that event.
The following default typespec will be added for each function.
@spec function_name(map(), map()) :: ok
When using the 1 arity telemetry
will receive the provided measurements
and the default metadata
.
MyApp.Instrumentation.cc_charge_succeeded(%{"latency" => 300})
MyApp.Instrumentation.cc_charge_failed(%{"latency" => 300})
When using the 2 arity telemetry
will receive the provided measurements
and will merge the provided metadata
with the defaults.
MyApp.Instrumentation.cc_charge_succeeded(%{"latency" => 300}, %{"cc_type" => "visa"})
MyApp.Instrumentation.cc_charge_failed(%{"latency" => 300}, %{"cc_type" => "visa"})
To override the default typespec of map(), map()
simple define a @spec
before calling defevent/0
. Note, the return type will always be :ok
.
defmodule MyApp.Telemetry do
@spec foo(integer, %{my_label: binary}) :: :ok
defevent :foo
end
Notion provides a events/0
function that provides all the event names telemetry receives. This is handy for binding handlers to
def MyApp.InstrumentationHandler do
def setup() do
:telemetry.attach_many("my-app-handler", MyApp.Instrumentation.events(), &handle_event/4, nil)
end
def handle_event(event, measurements, _metadata, _config) do
IO.puts("Dispatched: #{inspect(event)} -> #{inspect(measurements)}")
end
end
Documentation can be be found at https://hexdocs.pm/notion.
There is currently an issue open on credo to add support for checking if a use
d module adds a @moduledoc
.
In the meantime if you want to mute the error, you can add @moduledoc false
to the top of your instrumenter and docs will still be generated.
defmodule Bar.Instrumenter do
@moduledoc false
use Notion, ...
end