{"action":"created","issue":{"url":"https://api.github.com/repos/beam-telemetry/telemetry/issues/56","repository_url":"https://api.github.com/repos/beam-telemetry/telemetry","labels_url":"https://api.github.com/repos/beam-telemetry/telemetry/issues/56/labels{/name}","comments_url":"https://api.github.com/repos/beam-telemetry/telemetry/issues/56/comments","events_url":"https://api.github.com/repos/beam-telemetry/telemetry/issues/56/events","html_url":"https://github.com/beam-telemetry/telemetry/issues/56","id":547904896,"node_id":"MDU6SXNzdWU1NDc5MDQ4OTY=","number":56,"title":"Static API for discovering events","user":{"login":"josevalim","id":9582,"node_id":"MDQ6VXNlcjk1ODI=","avatar_url":"https://avatars0.githubusercontent.com/u/9582?v=4","gravatar_id":"","url":"https://api.github.com/users/josevalim","html_url":"https://github.com/josevalim","followers_url":"https://api.github.com/users/josevalim/followers","following_url":"https://api.github.com/users/josevalim/following{/other_user}","gists_url":"https://api.github.com/users/josevalim/gists{/gist_id}","starred_url":"https://api.github.com/users/josevalim/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/josevalim/subscriptions","organizations_url":"https://api.github.com/users/josevalim/orgs","repos_url":"https://api.github.com/users/josevalim/repos","events_url":"https://api.github.com/users/josevalim/events{/privacy}","received_events_url":"https://api.github.com/users/josevalim/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":8,"created_at":"2020-01-10T07:09:39Z","updated_at":"2020-01-12T01:20:32Z","closed_at":null,"author_association":"CONTRIBUTOR","body":"_Originally posted by @bryannaegele in https://github.com/beam-telemetry/telemetry/issues/12#issuecomment-572889254_:\r\n\r\nWe've discussed a number of ways to discover telemetry events for a variety of use cases, most recently as it pertains to registering of event handlers for tracing purposes. Knowledge of event names is a predicate to registering handlers, so we are left with two potential avenues: compile-time introspection or explicit declaration.\r\n\r\nNote that this is not intended to be the sole mechanism for event discovery. Issue #12 talks about a way to discover events as they happen. This discussion is about discovering events before they happen so they can be listened to in an unintrusive way.\r\n\r\n### Compile-time Introspection\r\n\r\nThis is arguably the best overall solution since it requires no additional steps by the user. In my initial investigation, introspection would be difficult to achieve, especially across languages.\r\n\r\n### Explicit Declaration\r\n\r\nBy requiring the user or library author to explicitly declare possible events, we have a straightforward mechanism to make use of that declaration at various steps and with a broad range of applications.\r\n\r\n#### Behaviour\r\n\r\nOne option would be to provide a behaviour with a `telemetry_events/0` function which returns a list of discoverable events.\r\n\r\n#### Module Attribute\r\n\r\nIntroduce an attribute of `telemetry_events` with a list of discoverable events.\r\n\r\nEach of the above is easily discoverable at runtime and compile-time. My initial idea was to use module attributes but, after further consideration, I'm leaning towards @josevalim's idea of going with a behaviour. It's just as easy to use for a user, feels more idiomatic, and provides flexibility going forward. It's probably more useful from a tooling perspective, as well.\r\n\r\n### Proposal\r\n\r\n- [ ] Introduce a `telemetry` behaviour with a `telemetry_events/0` callback (default impl returns `[]`).\r\n- [ ] Expand the API to add `telemetry:register_event/1`, `telemetry:deregister_event/1`, and `telemetry:register_all_events/1` functions to support further runtime declaration flexibility and discoverability (ETS storage is probably fine).\r\n  - [ ] Fire events for invocation of each of the above which a tracing or other interested library could listen for.\r\n  - [ ] Validate event name declarations during registration.\r\n  - [ ] Validate against duplicate event names. (Raise an exception? This situation is likely to cause handler detachments. We should at least warn.)\r\n  - [ ] Store registering module names with the event name? This could be useful in debugging or warning against duplicate event names being registered from different namespaces.\r\n- [ ] Add `telemetry:list_all_events/0` would return all registered events.\r\n\r\n/cc @arkgil @GregMefford @tsloughter @hauleth @binaryseed\r\n"},"comment":{"url":"https://api.github.com/repos/beam-telemetry/telemetry/issues/comments/573370679","html_url":"https://github.com/beam-telemetry/telemetry/issues/56#issuecomment-573370679","issue_url":"https://api.github.com/repos/beam-telemetry/telemetry/issues/56","id":573370679,"node_id":"MDEyOklzc3VlQ29tbWVudDU3MzM3MDY3OQ==","user":{"login":"binaryseed","id":39946,"node_id":"MDQ6VXNlcjM5OTQ2","avatar_url":"https://avatars1.githubusercontent.com/u/39946?v=4","gravatar_id":"","url":"https://api.github.com/users/binaryseed","html_url":"https://github.com/binaryseed","followers_url":"https://api.github.com/users/binaryseed/followers","following_url":"https://api.github.com/users/binaryseed/following{/other_user}","gists_url":"https://api.github.com/users/binaryseed/gists{/gist_id}","starred_url":"https://api.github.com/users/binaryseed/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/binaryseed/subscriptions","organizations_url":"https://api.github.com/users/binaryseed/orgs","repos_url":"https://api.github.com/users/binaryseed/repos","events_url":"https://api.github.com/users/binaryseed/events{/privacy}","received_events_url":"https://api.github.com/users/binaryseed/received_events","type":"User","site_admin":false},"created_at":"2020-01-12T01:20:32Z","updated_at":"2020-01-12T01:20:32Z","author_association":"CONTRIBUTOR","body":"Another idea that would remove the need for knowing the event types upfront that would be a whole lot simpler: let a handler attach to _all_ events."}}
{"actor":{"display_login":"binaryseed"}}