prometheus_plugs v1.1.1 Prometheus.PlugInstrumenter

Helps you create a plug that instruments another plug(s).

Internally works like and uses Plug.Builder so can instrument many plugs at once. Just use regular plug macro!

Usage

  1. Define your instrumenter:
defmodule EnsureAuthenticatedInstrumenter do
  use Prometheus.PlugInstrumenter

  plug Guardian.Plug.EnsureAuthenticated

  def label_value(:authenticated, {conn, _}) do
    conn.status != 401
  end
end
  1. Configuration:
config :phoenix, EnsureAuthenticatedInstrumenter,
  counter: :guardian_ensure_authenticated_total,
  counter_help: "Total number of EnsureAuthenticated plug calls."
  histogram: :guardian_ensure_authenticated_duration_microseconds,
  histogram_help: "Duration of EnsureAuthenticated plug calls."
  labels: [:authenticated]
  1. Call EnsureAuthenticatedInstrumenter.setup/0 when application starts (e.g. supervisor setup):
EnsureAuthenticatedInstrumenter.setup()
  1. Add EnsureAuthenticatedInstrumenter to your plug pipeline or replace Guardian.Plug.EnsureAuthenticated if it already present.

elixir: plug EnsureAuthenticatedInstrumenter, handler: Guardian.Plug.ErrorHandler

As you can see you can transparently pass options to the underlying plug.

Metrics

Currently PlugInstrumenter supports two metrics - counter for total calls count and histogram for calls duration. Metric can be disabled by setting it’s name to false:

counter: false

There should be at least one active metric.

Configuration

Plug pipeline instrumenter can be configured via EnsureAuthenticatedInstrumenter (you should replace this with the name of your plug) key of prometheus app env.

Mandatory keys:

  • counter or histogram.

Optional keys with defaults:

  • registry - Prometheus registry for metrics (:default);
  • counter - counter metric name (false);
  • counter_help - help string for counter metric (“”);
  • histogram - histogram metric name (false);
  • histogram_help - help string for histogram metric (“”);
  • histogram_buckets - histogram metric buckets (Prometheus.Contrib.HTTP.microseconds_duration_buckets());
  • labels - labels for counter and histogram ([]);
  • duration_units - duration units for the histogram, if histogram name already has known duration unit this can be omitted (:undefined).

As noted above at least one metric name should be given. Of course you must tell what plug(s) to instrument.

We don’t have default labels because they are highly specific to a particular plug(s) hence default is [].

Bear in mind that buckets are so if you are not using default unit you also have to override buckets.

Summary

Macros

Stores a plug to be instrumented

Macros

plug(plug, opts \\ [])

Stores a plug to be instrumented.