PromEx v0.1.1-alpha
PromEx

PromEx behaviour (PromEx v0.1.1-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:

Upcoming Elixir library metrics:

Backlog Elixir library metrics:

Database cron based metrics:

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

Types

measurements_mfa()
telemetry_metrics()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

get_metrics()

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.

start_link(init_arg)

Starts a PromEx process with the provided plugins initialized.

Callbacks

event_metrics(keyword)

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.

manual_metrics(keyword)

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.

polling_metrics(keyword)

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

Link to this type

measurements_mfa()

View Source

Specs

measurements_mfa() :: {module(), atom(), list()}
Link to this type

telemetry_metrics()

View Source

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

Link to this function

child_spec(init_arg)

View Source

Returns a specification to start this module under a supervisor.

See Supervisor.

Link to this function

get_metrics()

View Source

Specs

get_metrics() :: String.t()

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 function

start_link(init_arg)

View Source

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 name PlugIn.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 call PromEx.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 the ManualMetricsManager by a certain number of milliseconds or the :no_delay atom if you want the metrics to be captured as soon as the ManualMetricsManager 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 the PromEx.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

Link to this callback

event_metrics(keyword)

View Source

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.

Link to this callback

manual_metrics(keyword)

View Source

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.

Link to this callback

polling_metrics(keyword)

View Source

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.