# PromEx: Prometheus metrics and Grafana dashboards for the Elixir ecosystem

> PromEx is an Elixir library that turns Telemetry events into Prometheus metrics and ships matching Grafana dashboards for popular community libraries, with a plugin model so an application can add its own. It is MIT licensed, published on Hex, and its setup has one sharp edge, the PromEx module has to be started before your repo and endpoint.

**akoutmos/prom_ex** — An Elixir Prometheus metrics collection library built on top of Telemetry with accompanying Grafana dashboards

- Repository: https://github.com/akoutmos/prom_ex
- Stars: 712 · Forks: 138
- Language: Elixir
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/akoutmos-prom-ex

## Telemetry in, Prometheus out, with the dashboards provided

PromEx is a library for Prometheus metrics and Grafana dashboards for the popular Elixir libraries, built on top of Telemetry, and it is published on Hex.

The mechanism follows from the Elixir ecosystem's own conventions. Telemetry is the standard instrumentation interface in the BEAM, so any library that emits telemetry events can be scraped without the library knowing anything about Prometheus. PromEx sits on that seam: it receives the events, maintains the metrics, and exposes them.

The stated ambition is broad, and it is worth taking seriously because of how it is phrased. PromEx aims to provide Prometheus metrics and Grafana dashboards for as many libraries in the Elixir ecosystem as possible, as well as a framework so that you can manage the lifecycle of your own metrics and dashboards. That second half is the important part for a reader deciding whether to depend on it: the plugins are the visible feature, the framework is the durable one.

The dashboards are a real part of the offer rather than an afterthought. Prometheus gives you the numbers, and a Grafana dashboard gives you the picture, and building the second is where the effort usually goes. A library that ships both turns a two day task into a dependency.

The repository layout backs the framing. There is a lib/ directory for the library, priv/ for the dashboard assets, guides/ for the documentation, test/ and benchmarks/ for the test suite and the performance work, example_applications/ for working examples, a CHANGELOG.md, a mix.exs and mix.lock, and configuration for Credo, Doctor and the formatter.

## The generated module has to start before everything else

The setup is three steps, and the third one carries the important warning.

First, the dependency. The package is available on Hex and you add it to your dependencies in mix.exs:

```elixir
def deps do
  [
    {:prom_ex, "~> 1.11.0"}
  ]
end
```

Second, generate the configuration module with a mix task, passing the name of your Prometheus data source as configured in Grafana:

```
$ mix prom_ex.gen.config --datasource YOUR_PROMETHEUS_DATASOURCE_ID
```

Third, add the generated module to your application supervision tree, and the documentation is emphatic about where it goes. It should be at the top of the supervisor children list so that you do not miss any init-style events from other processes, with Ecto.Repo named as the example.

The reason is stated in the comment in the generated code itself. PromEx should be started before anything else, because it will capture init events from libraries like Ecto, Phoenix and Oban. If it is started after those other supervision trees, you will miss those events and metrics.

That is a subtle failure. Nothing crashes. The application starts, the metrics endpoint responds, and the dependency and boot time metrics are simply absent. This is the kind of ordering constraint that is easy to get wrong once and hard to notice, which is why it is worth reading before you wire it up rather than after the first dashboard shows a gap.

## A plug on the endpoint, and a caveat about your logs

The third piece is a plug, added to your endpoint.ex file. The documentation suggests putting it before your Plug.Telemetry call so that you do not pollute your logs with calls to /metrics.

The example shows the endpoint with the plug in place:

```elixir
defmodule MyCoolAppWeb.Endpoint do
  use Phoenix.Endpoint, otp_app: :my_cool_app

  ...

  plug PromEx.Plug, prom_ex_module: MyCoolApp.PromEx
  # Or plug PromEx.Plug, path: "/some/other/metrics/path", prom_ex_module: MyCoolApp.PromEx

  ...

  plug Plug.RequestId
  plug Plug.Telemetry, event_prefix: [:phoenix, :endpoint]

  ...

  plug MyCoolAppWeb.Router
end
```

The plug takes the module you generated, and the comment shows the alternative where you also set a path, so the metrics endpoint does not have to sit at the default location.

The ordering advice is not cosmetic. Every scrape of a metrics endpoint becomes a request through your endpoint, and with Plug.Telemetry ahead of it, every Prometheus pull is logged as a request. On a dashboard that refreshes every fifteen seconds, that is a constant stream of noise in your application logs, and it is the kind of noise that makes people stop reading logs.

With that in place, the documentation says to start the server and hit the metrics endpoint, and the sample output shows what you should see. The example is a dependency information gauge:

```terminal
$ curl localhost:4000/metrics
# HELP my_cool_app_application_dependency_info Information regarding the application's dependencies.
# TYPE my_cool_app_application_dependency_info gauge
my_cool_app_application_dependency_info{modules="69",name="hex",version="0.20.5"} 1
my_cool_app_application_dependency_info{modules="1",name="connection",version="1.0.4"} 1
my_cool_app_application_dependency_info{modules="4",name="telemetry_poller",version="0.5.1"} 1
...
```

Those dependency metrics are a good illustration of the value. Knowing which version of hex, of a database driver and of the telemetry poller is running in a deployed environment, without adding a line of application code, is the sort of thing that is painful to retrofit and trivial here.

## Your own metrics follow the same plugin shape

The plugins are the mechanism, and they are not restricted to the bundled libraries.

PromEx provides plugins for many of the popular community libraries, and the documentation explains that you can also use it to collect metrics specific to your application. The parallel given is the Ecto plugin: if you use the PromEx Ecto plugin to collect metrics relevant to Ecto, you can write your own plugin to collect metrics relevant to your application, and the same tools PromEx uses for its plugins are the ones to use for yours.

That is the design decision that determines whether PromEx is a dependency you use or a framework you build on. If your business metrics need to sit alongside the framework metrics in the same Prometheus instance and the same Grafana dashboards, and if you want them to follow the same lifecycle handling, then writing a plugin is the right move rather than bolting a second system on.

The application specific plugin is also the point at which the boundary with the alternative approaches becomes visible. A team that already has a Telemetry handler writing to Prometheus, plus its own dashboard as code, plus a convention for metric names and labels, gains little from PromEx. A team starting from nothing gains a great deal, because the alternative is building the metric naming scheme, the dashboard and the plugin lifecycle from scratch.

The documentation also tells you to read the module docs for each plugin you choose, to be familiar with all of the options they provide. That matters because a plugin with a dozen options is where the behaviour differences hide, and a dashboard that shows a metric that was never enabled is a confusing artefact.

## MIT licensed, single maintainer, and a slow release line

The licence is MIT, with the LICENSE file at the root of the repository. For a library that sits in the dependency list of a production Phoenix application, that removes any licensing question.

The maintenance picture deserves a careful reading. The repository is not archived, the default branch is master, and the last push was on 2026-06-19, four months before the current date. The three most recent releases are 1.12.0 from 2026-06-19, 1.11.0 from 2024-10-24 and 1.10.0 from 2024-08-10.

So the most recent version is current with the last commit, but the gap before it is close to two years. The pattern is a project that gets a burst of work when something needs doing and then goes quiet, which fits a library whose changes are driven by the needs of the maintainer's own applications and by the community libraries it wraps.

The sponsorship structure is worth noting too, because it explains the shape of the funding. There are three tiers of GitHub sponsors, gold, silver and bronze, and the readme frames sponsorship as supporting continued development, with the note that if you rely on PromEx in production, giving back would be appreciated.

Technical support is offered too, but through the maintainer's own consultancy rather than through the project, which is a common pattern and worth being explicit about: there is no support commitment attached to the MIT licence, and the commercial route is the author's business.

For an adopter, the practical guidance is to pin the version you test against, and to expect the 1.x line to move in occasional jumps rather than on a schedule.

## Conclusion

PromEx suits an Elixir team running Phoenix and Ecto that wants metrics and a dashboard without writing either by hand, and that wants a plugin shape to copy for its own business metrics. It does not suit a team that has already built its Telemetry to Prometheus pipeline and dashboard stack, and it does not suit a non-Phoenix application that does not want the plug and the supervision tree entry. Before adopting it, add the dependency, run mix prom_ex.gen.config against your Grafana data source name, and place the generated module at the top of your supervision children so the init events are not missed.

## FAQ

### What is PromEx and what does it provide?

PromEx is an Elixir library for Prometheus metrics and Grafana dashboards for the popular Elixir libraries, built on top of Telemetry. It provides plugins for many community libraries and a framework for managing the lifecycle of your own metrics and dashboards.

### How do I install PromEx in an Elixir project?

The package is on Hex, so you add {:prom_ex, "~> 1.11.0"} to the deps list in mix.exs, run mix prom_ex.gen.config --datasource with your Grafana Prometheus data source name, add the generated module to your supervision tree, and plug PromEx.Plug into your endpoint.

### Why must the PromEx module start first in the supervision tree?

Because PromEx captures init-style events from libraries like Ecto, Phoenix and Oban, and it only sees them if it is started before those other supervision trees. Starting it later does not crash, it just leaves those events and metrics missing.

### Can I collect my own application metrics with PromEx?

Yes. You can write your own plugin to collect metrics specific to your application, using the same tools PromEx uses for its plugins, in the same way the Ecto plugin collects metrics relevant to Ecto.

### What licence is PromEx released under?

MIT, with the LICENSE file at the root of the repository. The most recent release is 1.12.0 from 2026-06-19, and the previous one, 1.11.0, dates from 2024-10-24.

## Sources

- [akoutmos/prom_ex on GitHub](https://github.com/akoutmos/prom_ex)
- [Issues](https://github.com/akoutmos/prom_ex/issues)
- [License: MIT](https://github.com/akoutmos/prom_ex/blob/master/LICENSE)
- [README](https://github.com/akoutmos/prom_ex/blob/master/README.md)
- [Releases](https://github.com/akoutmos/prom_ex/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/akoutmos-prom-ex