# PromEx v1.12.0 - Table of Contents

> Prometheus metrics and Grafana dashboards for all of your favorite Elixir libraries

## Pages

- [README](readme.md)

- How-To's
  - [Writing PromEx Plugins](writing-promex-plugins.md)
  - [Introduction to Telemetry](telemetry.md)
  - [Running Multiple Agents](running-multiple-agents.md)
  - [Seeding Metrics](seeding-metrics.md)

- Grafana
  - [Dashboards Screenshots](all.md)

## Modules

- [PromEx](PromEx.md): 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.
- [PromEx.BucketGenerator](PromEx.BucketGenerator.md): This module provides functions to generate histogram bucket ranges.
The lists of buckets that can be generated are either linear
or exponential.

- [PromEx.Config](PromEx.Config.md): This module defines a struct that contains all of the fields necessary to configure
an instance of PromEx.
- [PromEx.DashboardRenderer](PromEx.DashboardRenderer.md): This module is used to read dashboard definitions, render EEx dashboards,
and ensure that requested files actually exist

- [PromEx.DashboardUploader](PromEx.DashboardUploader.md): 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
- [PromEx.Debug](PromEx.Debug.md): This is a convenience module used for debugging and introspecting
telemetry events. Primarily used to ease the development of
PromEx itself.

- [PromEx.ETSCronFlusher](PromEx.ETSCronFlusher.md): 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.

- [PromEx.GrafanaAgent](PromEx.GrafanaAgent.md): This GenServer is responsible for starting the Grafana Agent
binary via a port and ensuring that it stays up and running.

- [PromEx.GrafanaAgent.ConfigRenderer](PromEx.GrafanaAgent.ConfigRenderer.md): This module is used to render the YAML configuration file for
GrafanaAgent.

- [PromEx.GrafanaAgent.Downloader](PromEx.GrafanaAgent.Downloader.md): This module is responsible for downloading the GrafanaAgent binary.

- [PromEx.GrafanaClient](PromEx.GrafanaClient.md): 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.
- [PromEx.GrafanaClient.Connection](PromEx.GrafanaClient.Connection.md): This struct encapsulates all of the data necessary
to connect to a Grafana instance.

- [PromEx.GrafanaClient.DashboardChecker](PromEx.GrafanaClient.DashboardChecker.md): This module is used to validate Grafana dashboard to ensure that
they adhere to certain style and structure requirements.

- [PromEx.LifecycleAnnotator](PromEx.LifecycleAnnotator.md): 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
- [PromEx.ManualMetricsManager](PromEx.ManualMetricsManager.md): 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.

- [PromEx.MetricTypes.Event](PromEx.MetricTypes.Event.md): This struct defines the fields necessary to export a group of
standard metrics from a plugin.

- [PromEx.MetricTypes.Manual](PromEx.MetricTypes.Manual.md): This struct defines the fields necessary to export a group
of manually collected metric sources from a plugin.

- [PromEx.MetricTypes.Polling](PromEx.MetricTypes.Polling.md): This struct defines the fields necessary to export a group
of pollable metric sources from a plugin.

- [PromEx.MetricsServer.Plug](PromEx.MetricsServer.Plug.md): This plug is used to serve metrics when PromEx is run in a
standalone server configuration. This plug supports the
following options
- [PromEx.Plug](PromEx.Plug.md): Use this plug in your Endpoint file to expose your metrics. The following options are supported by this plug
- [PromEx.Plugin](PromEx.Plugin.md): 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.

- [PromEx.Plugins.Absinthe](PromEx.Plugins.Absinthe.md): This plugin captures metrics emitted by Absinthe. Specifically, it captures timings and metrics
around execution times, query complexity, and subscription timings. In order to get complexity
metrics you'll need to make sure that you have `:analyze_complexity` enabled in
[Absinthe.Plug](https://hexdocs.pm/absinthe_plug/Absinthe.Plug.html#t:opts/0). This plugin can
generate a large amount of Prometheus series, so it is suggested that you use the
`ignored_entrypoints` and `only_entrypoints` (TODO: coming soon) options to prune down the
resulting metrics if needed.
- [PromEx.Plugins.Application](PromEx.Plugins.Application.md): 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.
- [PromEx.Plugins.Beam](PromEx.Plugins.Beam.md): Telemetry metrics for the BEAM.
- [PromEx.Plugins.Broadway](PromEx.Plugins.Broadway.md): This plugin captures metrics emitted by Broadway.
- [PromEx.Plugins.Ecto](PromEx.Plugins.Ecto.md): 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.
- [PromEx.Plugins.Oban](PromEx.Plugins.Oban.md): 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
- [PromEx.Plugins.Phoenix](PromEx.Plugins.Phoenix.md): This plugin captures metrics emitted by Phoenix. Specifically, it captures HTTP request metrics and
Phoenix channel metrics.
- [PromEx.Plugins.PhoenixLiveView](PromEx.Plugins.PhoenixLiveView.md): 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.
- [PromEx.Plugins.PlugCowboy](PromEx.Plugins.PlugCowboy.md): This plugin captures HTTP request metrics emitted by Plug.Cowboy.
- [PromEx.Plugins.PlugRouter](PromEx.Plugins.PlugRouter.md): This plugin captures HTTP request metrics emitted by `Plug.Router` and `Plug.Telemetry`.
- [PromEx.Storage](PromEx.Storage.md): Storage definition behaviour.

- [PromEx.Storage.Core](PromEx.Storage.Core.md): This store uses [TelemetryMetricsPrometheus.Core](https://github.com/beam-telemetry/telemetry_metrics_prometheus_core) as the storage
mechanism for metrics.

- [PromEx.Storage.Peep](PromEx.Storage.Peep.md): This store uses [Peep](https://github.com/rkallos/peep) as the storage
mechanism for metrics.

- [PromEx.Utils](PromEx.Utils.md): This module provides several general purpose utilities
for use in PromEx plugs.

## Mix Tasks

- [mix prom_ex.dashboard.export](Mix.Tasks.PromEx.Dashboard.Export.md): This will render a PromEx dashboard either to STDOUT or to a file depending on
the CLI arguments that are provided.
- [mix prom_ex.dashboard.lint](Mix.Tasks.PromEx.Dashboard.Lint.md): This will lint Grafana dashboards to ensure that PromEx dashboards
meeting certain requirements.

- [mix prom_ex.dashboard.publish](Mix.Tasks.PromEx.Dashboard.Publish.md): 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.
- [mix prom_ex.gen.config](Mix.Tasks.PromEx.Gen.Config.md): 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.

