{"id":16701661,"url":"https://github.com/coryodaniel/notion","last_synced_at":"2025-03-21T19:33:18.340Z","repository":{"id":34931412,"uuid":"191988930","full_name":"coryodaniel/notion","owner":"coryodaniel","description":"Notion is a thin wrapper around telemetry that defines functions that dispatch telemetry events, documentation, and specs for your applications events.","archived":false,"fork":false,"pushed_at":"2022-02-13T06:19:46.000Z","size":20,"stargazers_count":12,"open_issues_count":6,"forks_count":4,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-18T04:42:49.291Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/coryodaniel.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-06-14T18:27:15.000Z","updated_at":"2024-04-29T09:44:09.000Z","dependencies_parsed_at":"2022-08-08T03:00:34.536Z","dependency_job_id":null,"html_url":"https://github.com/coryodaniel/notion","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coryodaniel%2Fnotion","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coryodaniel%2Fnotion/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coryodaniel%2Fnotion/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coryodaniel%2Fnotion/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/coryodaniel","download_url":"https://codeload.github.com/coryodaniel/notion/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244855719,"owners_count":20521694,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-12T18:45:06.741Z","updated_at":"2025-03-21T19:33:18.000Z","avatar_url":"https://github.com/coryodaniel.png","language":"Elixir","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Notion\n\n[![Build Status](https://travis-ci.org/coryodaniel/notion.svg?branch=master)](https://travis-ci.org/coryodaniel/notion)\n[![Hex.pm](http://img.shields.io/hexpm/v/notion.svg?style=flat)](https://hex.pm/packages/notion)\n![Hex.pm](https://img.shields.io/hexpm/l/notion.svg?style=flat)\n\nNotion is a thin wrapper around [`:telemetry`](https://github.com/beam-telemetry/telemetry) that defines functions that dispatch telemetry events, documentation, and specs for your applications events.\n\n## Installation\n\nThe package can be installed by adding `notion` to your list of dependencies in `mix.exs`:\n\n```elixir\ndef deps do\n  [\n    {:notion, \"~\u003e 0.2.0\"}\n  ]\nend\n```\n\n## Usage\n\nAdd an `Instrumentation` module and `use Notion`.\n\nSpecify 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.\n\n```elixir\ndefmodule MyApp.Instrumentation do\n  use Notion, name: :my_app, metadata: %{env: \"prod\"}\n\n  @doc \"Processed an HTTP request\"\n  # Generate a default typespec of http_request(map, map) :: :ok\n  defevent [:http, :request]\n\n  @doc \"Docs for my [:my_app, :cc_charge, :succeeded] event\"\n  # Override a typespec\n  @spec cc_charge_succeeded(integer, map) :: :ok\n  defevent [:cc_charge, :succeeded]\n\n  @doc \"Docs for my [:my_app, :cc_charge, :failed] event\"\n  defevent [:cc_charge, :failed]\nend\n```\n\n### Generated `@moduledoc`\n\nA 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:\n\n- `MODULE_NAME` - The name of the module using Notion\n- `NOTION_NAME` - will be the value `name` in `use Notion, name: :foo`\n- `NOTION_EVENTS` - a markdown formatted unordered list of emitted events\n- `NOTION_DEFAULT_METADATA` the default metadata added to events, if set.\n\n### Generated Event Functions\n\nNotion will create two functions for each event, described below. In additiona any `@doc` provided before the `defevent` call will be associated to that event.\n\nThe following default typespec will be added for each function.\n\n```elixir\n@spec function_name(map(), map()) :: ok\n```\n\n#### 1 arity event function form\n\nWhen using the 1 arity `telemetry` will receive the provided `measurements` and the default `metadata`.\n\n```elixir\nMyApp.Instrumentation.cc_charge_succeeded(%{\"latency\" =\u003e 300})\nMyApp.Instrumentation.cc_charge_failed(%{\"latency\" =\u003e 300})\n```\n\n#### 2 arity event function form\n\nWhen using the 2 arity `telemetry` will receive the provided `measurements` and will merge the provided `metadata` with the defaults.\n\n```elixir\nMyApp.Instrumentation.cc_charge_succeeded(%{\"latency\" =\u003e 300}, %{\"cc_type\" =\u003e \"visa\"})\nMyApp.Instrumentation.cc_charge_failed(%{\"latency\" =\u003e 300}, %{\"cc_type\" =\u003e \"visa\"})\n```\n\n### Overriding the default typespec for an event\n\nTo override the default typespec of `map(), map()` simple define a `@spec` before calling `defevent/0`. Note, the return type will always be `:ok`.\n\n```elixir\ndefmodule MyApp.Telemetry do\n  @spec foo(integer, %{my_label: binary}) :: :ok\n  defevent :foo\nend\n```\n\n### Attaching all events to a handler\n\nNotion provides a `events/0` function that provides all the event names telemetry receives. This is handy for binding handlers to\n\n```elixir\ndef MyApp.InstrumentationHandler do\n  def setup() do\n    :telemetry.attach_many(\"my-app-handler\", MyApp.Instrumentation.events(), \u0026handle_event/4, nil)\n  end\n\n  def handle_event(event, measurements, _metadata, _config) do\n    IO.puts(\"Dispatched: #{inspect(event)} -\u003e #{inspect(measurements)}\")\n  end\nend\n```\n\nDocumentation can be be found at [https://hexdocs.pm/notion](https://hexdocs.pm/notion).\n\n## Etc\n\n### Credo: Modules should have a @moduledoc tag.\n\nThere is currently an issue open on [credo](https://github.com/rrrene/credo/issues/530) to add support for checking if a `use`d module adds a `@moduledoc`.\n\nIn 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.\n\n```elixir\ndefmodule Bar.Instrumenter do\n  @moduledoc false\n  use Notion, ...\nend\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoryodaniel%2Fnotion","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcoryodaniel%2Fnotion","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoryodaniel%2Fnotion/lists"}