Fix CI and add examples (#69)

.github/workflows/test.yml

@@ -14,7 +14,7 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        otp_version: [21, 22, 23, 24]
+        otp_version: [24, 25, 26]
         os: [ubuntu-latest]
     env:
       OTP_VERSION: ${{ matrix.otp_version }}
@@ -23,7 +23,7 @@ jobs:
     - uses: erlef/setup-beam@v1
       with:
         otp-version: ${{ matrix.otp_version }}
-        rebar3-version: 3.14.4
+        rebar3-version: 3.22.0
     - uses: actions/cache@v2
       name: Cache
       with:
@@ -42,4 +42,4 @@ jobs:
       run: rebar3 xref
     - name: Dialyzer
       run: rebar3 dialyzer
-      if: ${{ matrix.otp_version == 24 }}
+      if: ${{ matrix.otp_version == 26 }}

README.md

@@ -78,6 +78,37 @@ end
 See [documentation](https://hexdocs.pm/telemetry_poller/) for more concrete examples and usage
 instructions.
 
+## VM metrics example
+
+### Erlang
+
+Find, in `examples/telemetry_poller_vm.erl`, an example on how to retrieve to VM measurements,
+mentioned above.
+
+To see it in action, fire up `rebar3 shell`, then
+
+```erlang
+{ok, telemetry_poller_vm} = c("examples/telemetry_poller_vm").
+ok = file:delete("telemetry_poller_vm.beam").  % Deletes generated BEAM
+ok = telemetry_poller_vm:attach().
+```
+
+### Elixir
+
+Find, in `examples/TelemetryPollerVM.ex`, an example on how to retrieve to VM measurements,
+mentioned above.
+
+To see it in action, first compile the Erlang sources with `rebar3 compile`.
+
+Then fire up `iex -pa "_build/default/lib/*/ebin"`, then
+
+```elixir
+{:ok, _} = Application.ensure_all_started(:telemetry_poller)
+
+[TelemetryPollerVM] = c("examples/TelemetryPollerVM.ex")
+:ok = TelemetryPollerVM.attach()
+```
+
 ## Copyright and License
 
 telemetry_poller is copyright (c) 2018 Chris McCord and Erlang Solutions.

examples/TelemetryPollerVM.ex

@@ -0,0 +1,70 @@
+defmodule TelemetryPollerVM do
+  def attach do
+    Enum.each(
+      [
+        [:vm, :memory],
+        [:vm, :total_run_queue_lengths],
+        [:vm, :system_counts]
+      ],
+      fn [:vm, namespace] = event_name ->
+        handler_id = "vm.#{Atom.to_string(namespace)}"
+
+        :telemetry.attach(handler_id, event_name, &TelemetryPollerVM.handle/4, _config = [])
+      end
+    )
+  end
+
+  def handle(
+        [:vm, :memory],
+        event_measurements,
+        _event_metadata,
+        _handler_config
+      ) do
+    # Do something with the measurements
+    IO.puts(
+      "memory\n" <>
+        "------\n" <>
+        "  atom: #{event_measurements.atom}\n" <>
+        "  atom_used: #{event_measurements.atom_used}\n" <>
+        "  binary: #{event_measurements.binary}\n" <>
+        "  code: #{event_measurements.code}\n" <>
+        "  ets: #{event_measurements.ets}\n" <>
+        "  processes: #{event_measurements.processes}\n" <>
+        "  processes_used: #{event_measurements.processes_used}\n" <>
+        "  system: #{event_measurements.system}\n" <>
+        "  total: #{event_measurements.total}\n"
+    )
+  end
+
+  def handle(
+        [:vm, :total_run_queue_lengths],
+        event_measurements,
+        _event_metadata,
+        _handler_config
+      ) do
+    # Do something with the measurements
+    IO.puts(
+      "total_run_queue_lengths\n" <>
+        "-----------------------\n" <>
+        "  cpu: #{event_measurements.cpu}\n" <>
+        "  io: #{event_measurements.io}\n" <>
+        "  total: #{event_measurements.total}\n"
+    )
+  end
+
+  def handle(
+        [:vm, :system_counts],
+        event_measurements,
+        _event_metadata,
+        _handler_config
+      ) do
+    # Do something with the measurements
+    IO.puts(
+      "system_counts\n" <>
+        "-------------\n" <>
+        "  atom_count: #{event_measurements.atom_count}\n" <>
+        "  port_count: #{event_measurements.port_count}\n" <>
+        "  process_count: #{event_measurements.process_count}\n"
+    )
+  end
+end

examples/telemetry_poller_vm.erl

@@ -0,0 +1,94 @@
+-module(telemetry_poller_vm).
+
+-export([attach/0]).
+-export([handle/4]).
+
+attach() ->
+    lists:foreach(
+        fun([vm, Namespace] = EventName) ->
+            NamespaceBin = atom_to_binary(Namespace),
+            HandlerId = <<"vm.", NamespaceBin/binary>>,
+            telemetry:attach(HandlerId, EventName, fun telemetry_poller_vm:handle/4, _Config = [])
+        end,
+        [
+            [vm, memory],
+            [vm, total_run_queue_lengths],
+            [vm, system_counts]
+        ]
+    ).
+
+handle([vm, memory], EventMeasurements, _EventMetadata, _HandlerConfig) ->
+    #{
+        atom := Atom,
+        atom_used := AtomUser,
+        binary := Binary,
+        code := Code,
+        ets := ETS,
+        processes := Processes,
+        processes_used := ProcessesUsed,
+        system := System,
+        total := Total
+    } = EventMeasurements,
+    % Do something with the measurements
+    io:format(
+        "memory~n"
+        "------~n"
+        "  atom: ~p~n"
+        "  atom_used: ~p~n"
+        "  binary: ~p~n"
+        "  code: ~p~n"
+        "  ets: ~p~n"
+        "  processes: ~p~n"
+        "  processes_used: ~p~n"
+        "  system: ~p~n"
+        "  total: ~p~n~n",
+        [
+            Atom,
+            AtomUser,
+            Binary,
+            Code,
+            ETS,
+            Processes,
+            ProcessesUsed,
+            System,
+            Total
+        ]
+    );
+handle([vm, total_run_queue_lengths], EventMeasurements, _EventMetadata, _HandlerConfig) ->
+    #{
+        cpu := CPU,
+        io := IO,
+        total := Total
+    } = EventMeasurements,
+    % Do something with the measurements
+    io:format(
+        "total_run_queue_lengths~n"
+        "-----------------------~n"
+        "  cpu: ~p~n"
+        "  io: ~p~n"
+        "  total: ~p~n~n",
+        [
+            CPU,
+            IO,
+            Total
+        ]
+    );
+handle([vm, system_counts], EventMeasurements, _EventMetadata, _HandlerConfig) ->
+    #{
+        atom_count := AtomCount,
+        port_count := PortCount,
+        process_count := ProcessCount
+    } = EventMeasurements,
+    % Do something with the measurements
+    io:format(
+        "system_counts~n"
+        "-------------~n"
+        "  atom_count: ~p~n"
+        "  port_count: ~p~n"
+        "  process_count: ~p~n~n",
+        [
+            AtomCount,
+            PortCount,
+            ProcessCount
+        ]
+    ).

rebar.config

@@ -18,7 +18,7 @@
     ]}
 ]}.
 
-{shell, [{apps, [telemetry_poller_app]}]}.
+{shell, [{apps, [telemetry_poller]}]}.
 
 %% take out warnings for unused exported functions
 {xref_checks,[undefined_function_calls, undefined_functions, locals_not_used,

src/telemetry_poller.erl

@@ -199,10 +199,10 @@
 
 -include_lib("kernel/include/logger.hrl").
 
--type t() :: gen_server:server().
+-type t() :: gen_server:server_ref().
 -type options() :: [option()].
 -type option() ::
-    {name, gen_server:name() | gen_server:server_name()}
+    {name, atom() | gen_server:server_name()}
     | {period, period()}
     | {measurements, [measurement()]}.
 -type measurement() ::
@@ -219,7 +219,7 @@
 %% Useful for starting Pollers as a part of a supervision tree.
 %%
 %% Default options: [{name, telemetry_poller}, {period, timer:seconds(5)}]
--spec start_link(options()) -> gen_server:on_start().
+-spec start_link(options()) -> gen_server:start_ret().
 start_link(Opts) when is_list(Opts) ->
     Args = parse_args(Opts),