PromEx behaviour (PromEx v0.1.2-alpha) 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.
All metrics collection will be delegated to plugins which can be found here:
Foundational metrics:
- [~]
PromEx.Plugins.Application
Application related informational metrics - [~]
PromEx.Plugins.Beam
BEAM virtual machine metrics
Upcoming Elixir library metrics:
- [~] Phoenix (https://hexdocs.pm/phoenix/Phoenix.Logger.html)
- [ ] Plug (https://hexdocs.pm/plug/Plug.Telemetry.html)
- [ ] Ecto (https://hexdocs.pm/ecto/Ecto.Repo.html#module-telemetry-events)
- [ ] Broadway (https://hexdocs.pm/broadway/Broadway.html#module-telemetry)
- [ ] Finch (https://hexdocs.pm/finch/Finch.Telemetry.html#content)
Backlog Elixir library metrics:
- [ ] 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)
- [ ] PhoenixLiveView (https://hexdocs.pm/phoenix_live_view/telemetry.html)
- [ ] Memcachex (https://hexdocs.pm/memcachex/0.5.0/Memcache.html#module-telemetry)
- [ ] Oban (https://hexdocs.pm/oban/Oban.Telemetry.html)
- [ ] 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)
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)
Each plugin also has an accompanying Grafana dashboard that you can leverage to plot all of the captured data (see each project's GitHub repo for details).
In order to expose captured metrics, you can leverage the PromEx provided Plug
found here (for use with Phoenix) PromEx.Plug
. See that modules' documentation
for specifics on how to use it.
Link to this section Summary
Functions
Returns a specification to start this module under a supervisor.
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.
Starts a PromEx process with the provided plugins initialized.
Callbacks
The event_metrics/1 callback returns the configured event based metrics that the plugin exposes. If the plugin does not expose any event style metrics, there is a default implementation of this function that returns an empty list. In other words, if your plugin does not expose any event style metrics, there is no action needed on your part.
The manual_metrics/1 callback returns the configured manual based metrics that the plugin exposes. If the plugin does not expose any manual style metrics, there is a default implementation of this function that returns an empty list. In other words, if your plugin does not expose any manual style metrics, there is no action needed on your part.
The polling_metrics/1 callback returns the configured polling based metrics that the plugin exposes. If the plugin does not expose any polling style metrics, there is a default implementation of this function that returns an empty list. In other words, if your plugin does not expose any polling style metrics, there is no action needed on your part.
Link to this section Types
Specs
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
Returns a specification to start this module under a supervisor.
See Supervisor
.
Specs
get_metrics() :: 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.
Starts a PromEx process with the provided plugins initialized.
Options
:plugins
- The list of plugin modules that you would like PromEx to initialize. Each plugin definition can either be a two element tuple with the structure{PlugIn.Module, keyword: "list", of: "options"}
or just the module namePlugIn.Module
. Be sure to check the documentation for each plugin that you are using to ensure that you satisfy any required option fields.:delay_manual_start
- Manual metrics are gathered once on start up and then only when you callPromEx.ManualMetricsManager.refresh_metrics()
. Sometimes, you may have metrics that require your entire supervision tree to be started in order to fetch accurate data. This option will allow you to delays the initial metrics capture of theManualMetricsManager
by a certain number of milliseconds or the:no_delay
atom if you want the metrics to be captured as soon as theManualMetricsManager
starts up.:drop_metrics_groups
- A list of all the metrics groups that you are not interested in tracking. For example, if your application does not leverage Phoenix channels at all but you still would like to use thePromEx.Plugins.Phoenix
plugin, you can pass [:phoenix_channel_event_metrics
] as the value to:drop_metrics_groups
and that set of metrics will not be caputred.
Link to this section Callbacks
Specs
event_metrics(keyword()) :: [PromEx.MetricTypes.Event.t()] | PromEx.MetricTypes.Event.t()
The event_metrics/1 callback returns the configured event based metrics that the plugin exposes. If the plugin does not expose any event style metrics, there is a default implementation of this function that returns an empty list. In other words, if your plugin does not expose any event style metrics, there is no action needed on your part.
This function is expected to either return a single PromEx.Plugins.Event
struct
or a list of PromEx.Plugins.Event
structs.
Specs
manual_metrics(keyword()) :: [PromEx.MetricTypes.Manual.t()] | PromEx.MetricTypes.Manual.t()
The manual_metrics/1 callback returns the configured manual based metrics that the plugin exposes. If the plugin does not expose any manual style metrics, there is a default implementation of this function that returns an empty list. In other words, if your plugin does not expose any manual style metrics, there is no action needed on your part.
This function is expected to either return a single PromEx.Plugins.Manual
struct
or a list of PromEx.Plugins.Manual
structs.
Specs
polling_metrics(keyword()) :: [PromEx.MetricTypes.Polling.t()] | PromEx.MetricTypes.Polling.t()
The polling_metrics/1 callback returns the configured polling based metrics that the plugin exposes. If the plugin does not expose any polling style metrics, there is a default implementation of this function that returns an empty list. In other words, if your plugin does not expose any polling style metrics, there is no action needed on your part.
This function is expected to either return a single PromEx.Plugins.Polling
struct
or a list of PromEx.Plugins.Polling
structs.