# Notion

[![Build Status](](

Notion is a thin wrapper around [`:telemetry`]( that defines functions that dispatch telemetry events, documentation, and specs for your applications events.

## Installation

The package can be installed by adding `notion` to your list of dependencies in `mix.exs`:

def deps do
    {:notion, "~> 0.2.0"}

## Usage

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]

### Generated `@moduledoc`

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 Notion
- `NOTION_NAME` - will be the value `name` in `use Notion, name: :foo`
- `NOTION_EVENTS` - a markdown formatted unordered list of emitted events
- `NOTION_DEFAULT_METADATA` the default metadata added to events, if set.

### Generated Event Functions

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

#### 1 arity event function form

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})

#### 2 arity event function form

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"})

### Overriding the default typespec for an event

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

### Attaching all events to a handler

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",, &handle_event/4, nil)

  def handle_event(event, measurements, _metadata, _config) do
    IO.puts("Dispatched: #{inspect(event)} -> #{inspect(measurements)}")

Documentation can be be found at [](