Installation

Observer Web is delivered as a hex package named observer_web. The package is entirely self contained—it doesn't hook into your asset pipeline.

Prerequisites

  1. Ensure Phoenix Live View is installed and working in your application. If you don't have Live View, follow these instructions to get started.

Clustering Required

The Observer Web requires your app to be clustered. Otherwise, observability will only be available on the current node.

Configuration

Add observer_web as a dependency for your application. Open mix.exs and add the following line:

{:observer_web, "~> 0.1.0"}

Now fetch your dependencies:

mix deps.get

This will fetch observer_web.

After fetching the package you'll use the Observer.Web.Router to mount the dashboard within your application's router.ex:

# lib/my_app_web/router.ex
use MyAppWeb, :router

import Observer.Web.Router

...

scope "/" do
  pipe_through :browser

  observer_dashboard "/observer"
end

Here we're using "/observer" as the mount point, but it can be anywhere you like. See the Observer.Web.Router docs for additional options.

After you've verified that the dashboard is loading you'll probably want to restrict access to the dashboard via authentication, either with a custom resolver's access controls or Basic Auth.

Retention period for metrics

The Observer Web can monitor Beam VM metrics by default, using ETS tables to store the data. However, this means that the data is not persisted across restarts. The retention period for this data can be configured.

By default, without a retention time set, the metrics will only show data received during the current session. If you'd like to persist this data for a longer period, you can configure a retention time.

To configure the retention period, use the following optional setting:

config :observer_web, ObserverWeb.Telemetry,
  data_retention_period: :timer.minutes(5)

Usage with Web and Clustering

The Observer Web provides observer ability for the local application as well as any other that is clustered.

Customization

Web customization is done through the Observer.Web.Resolver behaviour. It allows you to enable access controls. Using a custom resolver is entirely optional, but you should familiarize yourself with the default limits and functionality.

Installation is complete and you're all set! Start your Phoenix server and enjoy the observability via OTP distribution!