Plug.Telemetry.ServerTiming (plug_telemetry_server_timing v0.3.0) View Source

This library provides support for Server-Timing header in Plug applications by exposing Telemetry events as metrics in HTTP headers. This allows developers to use their's browser DevTools to display server metrics in readable way.

Installation

The package can be installed by adding plug_server_timing to your list of dependencies in mix.exs:

def deps do
  [
    {:plug_telemetry_server_timing, "~> 0.3.0"}
  ]
end

Then add Plug.ServerTiming to your pipeline BEFORE any Plug.Telemetry definitions:

plug Plug.Telemetry.ServerTiming
plug Plug.Telemetry, event_prefix: [:my, :plug]

And then you need to install/1 metrics you will want to see in the DevTools:

Plug.Telemetry.ServerTiming.install([
  {[:my, :plug, :stop], :duration}
])

Now when you will open given page in browsers with support for Server-Timing you will be able to see the data in DevTools, example in Google Chrome:

Google Chrome DevTools image example

Important

You need to place this plug BEFORE Plug.Telemetry call as otherwise it will not see it's events (before_send callbacks are called in reverse order of declaration, so this one need to be added before Plug.Telemetry one.

Caveats

This will not respond with events that happened in separate processes, only events that happened in the Plug process will be recorded.

WARNING

Current specification of Server-Timing do not provide a way to specify event start time, which mean, that the data displayed in the DevTools isn't trace report (like the content of the "regular" HTTP timings) but raw dump of the data displayed as a bars. This can be a little bit confusing, but right now there is nothing I can do about it.

Link to this section Summary

Functions

Define which events should be available within response headers.

Link to this section Types

Specs

event() ::
  {:telemetry.event_name(), measurement :: atom()}
  | {:telemetry.event_name(), measurement :: atom(), opts :: keyword() | map()}

Specs

events() :: [event()]

Link to this section Functions

Specs

install(events()) :: :ok

Define which events should be available within response headers.

Tuple values are:

  1. List of atoms that is the name of the event that we should listen for.
  2. Atom that contains the name of the metric that should be recorded.
  3. Optionally keyword list or map with additional options. Currently supported options are:
    • :name - alternative name for the metric. By default it will be constructed by joining event name and name of metric with dots. Ex. for {[:foo, :bar], :baz} default metric name will be foo.bar.baz.
    • :description - string that will be set as desc.

Example

Plug.Telemetry.ServerTiming.install([
  {[:phoenix, :endpoint, :stop], :duration, description: "Phoenix time"},
  {[:my_app, :repo, :query], :total_time, description: "DB request"}
])