PromEx.Plugins.Phoenix (PromEx v1.6.0) View Source

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

Plugin options

This plugin supports the following options:

• metric_prefix: This option is OPTIONAL and is used to override the default metric prefix of [otp_app, :prom_ex, :phoenix]. If this changes you will also want to set phoenix_metric_prefix in your dashboard_assigns to the snakecase version of your prefix, the default phoenix_metric_prefix is {otp_app}_prom_ex_phoenix.

Single Endpoint/Router

• router: This option is REQUIRED and is the full module name of your Phoenix Router (e.g MyAppWeb.Router).

• endpoint: This is a REQUIRED option and is the full module name of your Phoenix Endpoint (e.g MyAppWeb.Endpoint).

• event_prefix: This option is OPTIONAL and allows you to set the event prefix for the Telemetry events. This value should align with what you pass to Plug.Telemetry in your endpoint.ex file (see the plug docs for more information https://hexdocs.pm/plug/Plug.Telemetry.html) This value should align with what you pass to Plug.Telemetry in your endpoint.ex file (see the plug docs for more information https://hexdocs.pm/plug/Plug.Telemetry.html)

• additional_routes: This option is OPTIONAL and allows you to specify route path labels for applications routes not defined in your Router module.

  For example, if you want to track telemetry events for a plug in your endpoint.ex file, you can provide a keyword list with the structure [some-route: ~r(/some-path)] and any time that the route is called and the plug handles the call, the path label for this particular Prometheus metric will be set to some-route. You can pass in either a regular expression or a string to match the incoming request.

Example plugin configuration

{
  PromEx.Plugins.Phoenix,
  endpoint: MyApp.Endpoint,
  router: MyAppWeb.Public.Router,
  event_prefix: [:admin, :endpoint]
}

Multiple Endpoints/Router

• endpoints: This accepts a list of per Phoenix Endpoint options {endpoint_name, endpoint_opts}

  • endpoint_name: This option is REQUIRED and is the full module name of your Phoenix Endpoint (e.g MyAppWeb.Endpoint).

  • endpoint_opts: Per endpoint plugin options:

    • :routers: This option is REQUIRED and lists all of routers modules for the endpoint, the HTTP metrics will be augmented with controller/action/path information from the routers.
    • :event_prefix: This option is OPTIONAL and allows you to set the event prefix for the Telemetry events. This value should align with what you pass to Plug.Telemetry in the corresponding endpoint module (see the plug docs for more information https://hexdocs.pm/plug/Plug.Telemetry.html)
    • :additional_routes: This option is OPTIONAL and allows you to specify route path labels for applications routes not defined in your Router modules for the corresponding endpoint.

Example plugin configuration

{
  PromEx.Plugins.Phoenix,
  endpoints: [
    {MyApp.Endpoint, routers: [MyAppWeb.Public.Router]},
    {MyApp.Endpoint2, routers: [MyAppWeb.Admin.Router], event_prefix: [:admin, :endpoint]}
  ]
}

Metric Groups

This plugin exposes the following metric groups:

• :phoenix_http_event_metrics
• :phoenix_channel_event_metrics
• :phoenix_socket_event_metrics
• :phoenix_endpoint_manual_metrics

Usage

To use plugin in your application, add the following to your PromEx module:

defmodule WebApp.PromEx do
  use PromEx, otp_app: :web_app

  @impl true
  def plugins do
    [
      ...
      {
        PromEx.Plugins.Phoenix,
        endpoint: MyApp.Endpoint,
        router: MyAppWeb.Public.Router
      }
    ]
  end

  @impl true
  def dashboards do
    [
      ...
      {:prom_ex, "phoenix.json"}
    ]
  end
end

When working with multiple Phoenix routers use the endpoints option instead:

defmodule WebApp.PromEx do
  use PromEx, otp_app: :web_app

  @impl true
  def plugins do
    [
      ...
      {
        PromEx.Plugins.Phoenix,
        endpoints: [
          {MyApp.Endpoint, routers: [MyAppWeb.Public.Router]},
          {MyApp.Endpoint2, routers: [MyAppWeb.Admin.Router], event_prefix: [:admin, :endpoint]}
        ]
      }
    ]
  end

  @impl true
  def dashboards do
    [
      ...
      {:prom_ex, "phoenix.json"}
    ]
  end
end