{"id":13651175,"url":"https://github.com/beam-telemetry/telemetry_poller","last_synced_at":"2025-12-11T23:41:36.271Z","repository":{"id":47092598,"uuid":"146449250","full_name":"beam-telemetry/telemetry_poller","owner":"beam-telemetry","description":"Periodically gather measurements and publish them as Telemetry events","archived":false,"fork":false,"pushed_at":"2025-04-14T13:10:13.000Z","size":155,"stargazers_count":124,"open_issues_count":0,"forks_count":18,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-05-08T00:29:01.407Z","etag":null,"topics":["elixir","events","instrumentation","metrics"],"latest_commit_sha":null,"homepage":"https://hexdocs.pm/telemetry_poller","language":"Erlang","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/beam-telemetry.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-08-28T13:09:25.000Z","updated_at":"2025-04-14T13:10:17.000Z","dependencies_parsed_at":"2022-08-29T11:50:16.359Z","dependency_job_id":"9c857367-6085-4fbf-80ac-e11b24818962","html_url":"https://github.com/beam-telemetry/telemetry_poller","commit_stats":{"total_commits":83,"total_committers":18,"mean_commits":4.611111111111111,"dds":0.7228915662650602,"last_synced_commit":"aff10bf66e2269e7d76842950bf462ef7094b9f1"},"previous_names":["elixir-telemetry/telemetry_sampler"],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beam-telemetry%2Ftelemetry_poller","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beam-telemetry%2Ftelemetry_poller/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beam-telemetry%2Ftelemetry_poller/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beam-telemetry%2Ftelemetry_poller/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/beam-telemetry","download_url":"https://codeload.github.com/beam-telemetry/telemetry_poller/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253850767,"owners_count":21973666,"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":["elixir","events","instrumentation","metrics"],"created_at":"2024-08-02T02:00:46.019Z","updated_at":"2025-12-11T23:41:36.265Z","avatar_url":"https://github.com/beam-telemetry.png","language":"Erlang","funding_links":[],"categories":["Erlang","Metrics"],"sub_categories":[],"readme":"# telemetry_poller\n\n[![Test](https://github.com/beam-telemetry/telemetry_poller/actions/workflows/test.yml/badge.svg)](https://github.com/beam-telemetry/telemetry_poller/actions/workflows/test.yml)\n[![Codecov](https://codecov.io/gh/beam-telemetry/telemetry_poller/branch/master/graphs/badge.svg)](https://codecov.io/gh/beam-telemetry/telemetry_poller/branch/master/graphs/badge.svg)\n\nAllows to periodically collect measurements and dispatch them as Telemetry events.\n\n`telemetry_poller` by default runs a poller to perform VM measurements:\n\n  * `[vm, memory]` - contains the total memory, process memory, and all other keys in `erlang:memory/0`\n  * `[vm, total_run_queue_lengths]` - returns the run queue lengths for CPU and IO schedulers. It contains the `total`, `cpu` and `io` measurements\n  * `[vm, system_counts]` - returns the current process, atom and port count as well as their respective limits as per `erlang:system_info/1`\n  * `[vm, persistent_term]` - number of terms and memory byte size for `persistent_term`\n\nYou can directly consume those events after adding `telemetry_poller` as a dependency.\n\nPoller also provides a convenient API for running custom pollers.\n\n## Defining custom measurements\n\nPoller also includes conveniences for performing process-based measurements as well as custom ones.\n\n### Erlang\n\nFirst define the poller with the custom measurements. The first measurement is the built-in `process_info` measurement and the second one is given by a custom module-function-args defined  by you:\n\n```erlang\ntelemetry_poller:start_link(\n  [{measurements, [\n    {process_info, [{name, my_app_worker}, {event, [my_app, worker]}, {keys, [memory, message_queue_len]}]},\n    {example_app_measurements, dispatch_session_count, []}\n  ]},\n  {period, timer:seconds(10)}, % configure sampling period - default is timer:seconds(5)\n  {init_delay, timer:seconds(600)}, % configure sampling initial delay - default is 0\n  {name, my_app_poller}\n]).\n```\n\nNow define the custom measurement and you are good to go:\n\n```erlang\n-module(example_app_measurements).\n\ndispatch_session_count() -\u003e\n    % emit a telemetry event when called\n    telemetry:execute([example_app, session_count], #{count =\u003e example_app:session_count()}, #{}).\n```\n\n### Elixir\n\nYou typically start the poller as a child in your supervision tree:\n\n```elixir\nchildren = [\n  {:telemetry_poller,\n   # include custom measurement as an MFA tuple\n   measurements: [\n     {:process_info, name: :my_app_worker, event: [:my_app, :worker], keys: [:memory, :message_queue_len]},\n     {ExampleApp.Measurements, :dispatch_session_count, []},\n   ],\n   period: :timer.seconds(10), # configure sampling period - default is :timer.seconds(5)\n   init_delay: :timer.seconds(600), # configure sampling initial delay - default is 0\n   name: :my_app_poller}\n]\n\nSupervisor.start_link(children, strategy: :one_for_one)\n```\n\nThe poller above has two periodic measurements. The first is the built-in `process_info` measurement that will gather the memory and message queue length of a process. The second is given by a custom module-function-args defined by you, such as below:\n\n```elixir\ndefmodule ExampleApp.Measurements do\n  def dispatch_session_count() do\n    # emit a telemetry event when called\n    :telemetry.execute([:example_app, :session_count], %{count: ExampleApp.session_count()}, %{})\n  end\nend\n```\n\n## Documentation\n\nSee [documentation](https://hexdocs.pm/telemetry_poller/) for more concrete examples and usage\ninstructions.\n\n## VM metrics example\n\n### Erlang\n\nFind, in `examples/telemetry_poller_vm.erl`, an example on how to retrieve to VM measurements,\nmentioned above.\n\nTo see it in action, fire up `rebar3 shell`, then\n\n```erlang\n{ok, telemetry_poller_vm} = c(\"examples/telemetry_poller_vm\").\nok = file:delete(\"telemetry_poller_vm.beam\").  % Deletes generated BEAM\nok = telemetry_poller_vm:attach().\n```\n\n### Elixir\n\nFind, in `examples/TelemetryPollerVM.ex`, an example on how to retrieve to VM measurements,\nmentioned above.\n\nTo see it in action, first compile the Erlang sources with `rebar3 compile`.\n\nThen fire up `iex -pa \"_build/default/lib/*/ebin\"`, then\n\n```elixir\n{:ok, _} = Application.ensure_all_started(:telemetry_poller)\n\n[TelemetryPollerVM] = c(\"examples/TelemetryPollerVM.ex\")\n:ok = TelemetryPollerVM.attach()\n```\n\n## Copyright and License\n\nCopyright (c) 2025 Erlang Ecosystem Foundation.\n\ntelemetry_poller source code is released under Apache License, Version 2.0.\n\nSee [LICENSE](LICENSE) and [NOTICE](NOTICE) files for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeam-telemetry%2Ftelemetry_poller","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbeam-telemetry%2Ftelemetry_poller","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeam-telemetry%2Ftelemetry_poller/lists"}