PromEx behaviour (PromEx v1.1.1) View Source

PromEx is a plugin based library which can be used to capture telemetry events and report them out for consumption by Prometheus. The main purpose of this particular library is to provide the behaviour that all PromEx plugins leverage so that a consistent interface can be achieved and so that leveraging multiple plugins is effortless from the user's point of view.

To use PromEx you need to define a module that uses the PromEx library. This module will also need to have some application config set for it similarly to how Ecto does. For example, for a PromEx module defined like so:

defmodule MyApp.PromEx do
  use PromEx,  otp_app: :web_app

  ...
end

You would have an application configuration set like so:

config :my_app, MyApp.PromEx,
  manual_metrics_start_delay: :no_delay,
  drop_metrics_groups: [],
  grafana: [
    host: System.get_env("GRAFANA_HOST", "http://grafana:3000"),
    auth_token: System.get_env("GRAFANA_TOKEN", ""),
    upload_dashboards_on_start: true,
    folder_name: "My App Dashboards",
    annotate_app_lifecycle: true
  ]

The options that you can pass to PromEx macro are outlined in the following section. In order to tell PromEx what plugins you would like to use and what dashboards you would like PromEx to upload for you, implement the plugins/0 and dashboards/0 callbacks respectively. The dashboard_assigns/0 callback will be used when your EEx template Grafana dashboards are rendered so that the dashboards that are created for your application coincide with the PromEx configuration for the application. If your dashboards are not EEx templates, then the dashboard assigns are not passed through. Each plugin also has an accompanying Grafana dashboard that you can leverage to plot all of the plugin captured data.

In order to expose captured metrics, you can leverage the PromEx provided Plug PromEx.Plug. See the PromEx.Plug documentation modules for specifics on how to use it.

Options

:otp_app - This is a REQUIRED field and is used by PromEx to fetch the application configuration values for the various PromEx capture modules. Make sure that this value matches the :app value in project/0 from your mix.exs file. If you use the PromEx mix prom_ex.create mix task this will be done automatically for you.

PromEx Plugins

All metrics collection will be delegated to plugins which can be found here:

Foundational metrics:

[X] PromEx.Plugins.Application Application related informational metrics
[X] PromEx.Plugins.Beam BEAM virtual machine metrics
[ ] Operating System (http://erlang.org/doc/man/os_mon_app.html)

Library metrics:

[X] Ecto (https://hexdocs.pm/ecto/Ecto.Repo.html#module-telemetry-events)
[X] Oban (https://hexdocs.pm/oban/Oban.Telemetry.html)
[X] Phoenix (https://hexdocs.pm/phoenix/Phoenix.Logger.html)
[X] Phoenix LiveView (https://hexdocs.pm/phoenix_live_view/telemetry.html)

Backlog Elixir library metrics:

[ ] Broadway (https://hexdocs.pm/broadway/Broadway.html#module-telemetry)
[ ] Absinthe (https://hexdocs.pm/absinthe/1.5.3/telemetry.html)
[ ] Dataloader (https://hexdocs.pm/dataloader/telemetry.html)
[ ] GenRMQ (https://hexdocs.pm/gen_rmq/3.0.0/GenRMQ.Publisher.Telemetry.html and https://hexdocs.pm/gen_rmq/3.0.0/GenRMQ.Consumer.Telemetry.html)
[ ] Plug (https://hexdocs.pm/plug/Plug.Telemetry.html)
[ ] PlugCowboy (https://hexdocs.pm/plug_cowboy/2.4.0/Plug.Cowboy.html#module-instrumentation)
[ ] Redix (https://hexdocs.pm/redix/Redix.Telemetry.html)
[ ] Tesla (https://hexdocs.pm/tesla/Tesla.Middleware.Telemetry.html)
[ ] Memcachex (https://hexdocs.pm/memcachex/0.5.0/Memcache.html#module-telemetry)
[ ] Finch (https://hexdocs.pm/finch/Finch.Telemetry.html#content)
[ ] Nebulex (https://hexdocs.pm/nebulex/2.0.0-rc.0/telemetry.html)
[ ] Horde (https://github.com/derekkraan/horde/blob/master/lib/horde/supervisor_telemetry_poller.ex)
[ ] Cachex (Need to open up PR)
[ ] Quantum (https://hexdocs.pm/quantum/3.3.0/telemetry.html#content)

Database cron based metrics:

[ ] Postgres (https://github.com/pawurb/ecto_psql_extras for inspiration)
[ ] Mnesia (https://github.com/deadtrickster/prometheus.erl/blob/master/src/collectors/mnesia/prometheus_mnesia_collector.erl for inspiration)
[ ] MySQL (https://github.com/prometheus/mysqld_exporter for inspiration)
[ ] Redis (https://github.com/oliver006/redis_exporter for inspiration)
[ ] MongoDB (https://github.com/percona/mongodb_exporter for inspiration)

Link to this section Summary

Types

dashboard_definition()

measurements_mfa()

plugin_definition()

telemetry_metrics()

Functions

get_metrics(prom_ex_module)

A simple pass-through to fetch all of the currently configured metrics. This is primarily used by the exporter plug to fetch all of the metrics so that they can be scraped.

Callbacks

dashboard_assigns()

dashboards()

init_opts()

plugins()

Link to this section Types

dashboard_definition()

Specs

dashboard_definition() ::
  {atom(), String.t()} | {atom(), String.t(), keyword(String.t())}

measurements_mfa()

Specs

measurements_mfa() :: {module(), atom(), list()}

plugin_definition()

Specs

plugin_definition() :: module() | {module(), keyword()}

telemetry_metrics()

Specs

telemetry_metrics() ::
  Telemetry.Metrics.Counter.t()
  | Telemetry.Metrics.Distribution.t()
  | Telemetry.Metrics.LastValue.t()
  | Telemetry.Metrics.Sum.t()
  | Telemetry.Metrics.Summary.t()

Link to this section Functions

get_metrics(prom_ex_module)

Specs

get_metrics(prom_ex_module :: module()) :: String.t() | :prom_ex_down

A simple pass-through to fetch all of the currently configured metrics. This is primarily used by the exporter plug to fetch all of the metrics so that they can be scraped.

Link to this section Callbacks

dashboard_assigns()

Specs

dashboard_assigns() :: keyword()

dashboards()

Specs

dashboards() :: [dashboard_definition()]

init_opts()

Specs

init_opts() :: PromEx.Config.t()

plugins()

Specs

plugins() :: [plugin_definition()]