API Reference PromEx v1.1.1

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.

This module provides functions to generate histogram bucket ranges. The lists of buckets that can be generated are either linear or exponential.

This module defines a struct that contains all of the fields necessary to configure an instance of PromEx.

This module is used to read dashboard definitions, render EEx dashboards, and ensure that requested files actually exist

This GenServer is responsible for uploading the configured PromEx module dashboards to Grafana. This is a transient process and will terminate after the dashboards have been successfully uploaded. It requires the name of the PromEx module as an option so that it can look into the application config for the appropriate Grafana settings. For example, if the name of the PromEx module is WebApp.PromEx, then your config should provide the following settings

This is a convenience module used for debugging and introspecting telemetry events. Primarily used to ease the development of PromEx itself.

This module is used to regularly flush ETS of any buffered distribution type metrics (see https://github.com/beam-telemetry/telemetry_metrics_prometheus_core/blob/main/lib/core.ex#L25-L28) for more information. At the moment the flush interval is not configurable but that could change in the future.

This module is used by the Mix tasks that are available in PromEx to update dashboards in Grafana and also by the PromEx.DashboardUpdater to update dashboards automatically on application initialization.

This struct encapsulates all of the data necessary to connect to a Grafana instance.

This module is used to validate Grafana dashboard to ensure that they adhere to certain style and structure requirements.

This GenServer is responsible to keeping track of the life cycle of the application and sending annotation requests to Grafana when the application starts and when it terminates. It will include things in the message like

This GenServer is responsible to keeping track of all the manual metrics from your configured plugins. It will fetch metrics initially when starting (either immediately or after a configured delay). At that point if you would like to refresh your metrics data points call the refresh_metrics/1 function.

This struct defines the fields necessary to export a group of standard metrics from a plugin.

This struct defines the fields necessary to export a group of manually collected metric sources from a plugin.

This struct defines the fields necessary to export a group of pollable metric sources from a plugin.

This plug is used to serve metrics when PromEx is run in a standalone server configuration. This plug supports the following options

Use this plug in your Endpoint file to expose your metrics. The following options are supported by this plug

This module defines the behaviour that PromEx plugins need to implement in order to be properly loaded by PromEx on application start. As a convenience, this module can also be used as a macro to automatically import all of the necessary utility functions for writing plugins and also providing default implementations of behaviour functions that you may not be implementing.

This plugin captures metrics regarding your application, and its dependencies. Specifically, it captures the versions of your application and the application dependencies and also how many modules each dependency is bringing into the project.

Telemetry metrics for the BEAM.

This plugin captures metrics emitted by Ecto. Be sure that your PromEx module is listed before your Repo module in your supervision tree so that the Ecto init events are not missed. If you miss those events the dashboard variable dropdowns for the repo value will be broken.

This plugin captures metrics emitted by Oban. Specifically, it captures metrics from job events, producer events, and also from internal polling jobs to monitor queue sizes

This plugin captures metrics emitted by Phoenix. Specifically, it captures HTTP request metrics and Phoenix channel metrics.

This plugin captures metrics emitted by PhoenixLiveView. Specifically, it captures events related to the mount, handle_event, and handle_params callbacks for live views and live components.

This will render a PromEx dashboard either to STDOUT or to a file depending on the CLI arguments that are provided.

This will lint Grafana dashboards to ensure that PromEx dashboards meeting certain requirements.

This mix task will publish dashboards to Grafana for a PromEx module. It is recommended that you use the functionality that is part of the PromEx supervision tree in order to upload dashboards as opposed to this, given that mix may not always be available (like in a mix release). This is more so a convenience for testing and validating dashboards without starting the whole application.

This Mix Task generates a PromEx config module in your project. This config file acts as a starting point with instructions on how to set up PromEx in your application, some default PromEx metrics plugins, and their accompanying dashboards.