Luminous

Luminous is a framework for creating dashboards within Phoenix Live View. It is somewhat inspired by grafana both conceptually and functionally in that:

• it focuses on time series data (albeit not exclusively)
• it is organized around panels
• it is parameterized by a time range
• it can be parameterized by user-defined variables

Dashboards are defined at compile time using elixir code (see Luminous.Dashboard.define/5). At runtime, Luminous uses the following javascript libraries (as live view hooks) for supporting client-side visualizations and interactions with the live view process:

• chartjs for plots
• flatpickr for time range selection

Luminous is currently used in production systems and has demonstrated solid performance and stability characteristics. At the same time, it is currently under development and some things may change.

Installation

The package is not yet published to hex.pm but can be installed directly from this repo by adding luminous to your list of dependencies in mix.exs like so:

def deps do
  [
    {:luminous, git: "https://github.com/elinverd/luminous.git", branch: "main"}
  ]
end

luminous assumes that it will be embedded in a standard Phoenix LiveView application with tailwindcss.

In order to be able to use the provided components, the library's javascript and CSS files must be imported to your project:

In assets/package.json:

...
"dependencies": {
  "luminous": "file:../deps/luminous"
}

In assets/js/app.js:

import { ChartJSHook, TimeRangeHook } from "luminous"

let Hooks = {
  TimeRangeHook: new TimeRangeHook(),
  ChartJSHook: new ChartJSHook()
}

...

let liveSocket = new LiveSocket("/live", Socket, {
  ...
  hooks: Hooks
})
...

Finally, in assets/css/app.css:

@import "luminous/dist/luminous";

Usage

A demo dashboard has been provided that showcases some of Luminous' capabilities.

The demo can be inspected live using the project's dev server (run mix dev in the project and then visit this page).

Luminous is a framework in the sense that the luminous client is responsible for specifying queries, variables etc. and Luminous.Live will call the client's code by setting up all the required plumbing.

In general, a custom dashboard needs to:

• implement the Luminous.Variable behaviour for the dashboard-specific variables
• implement the Luminous.Query behaviour for loading the necessary data that will be visualized in the client
• implement the Luminous.TimeRangeSelector behaviour for determining the default time range for the dashboard
• use the Luminous.Live module for leveraging the live dashboard functionality and capabilities
• render the dashboard in the view template (only Luminous.Components.dashboard is necessary but the layout can be customized by using directly the various components in Luminous.Components)

Features

• Time range selection and refresh of all dashboard panel queries
• Asynchronous queries and page updates
• User-facing variable dropdowns that are available to panel queries
• Client-side zoom in charts
• Multiple supported chart types (currently :line and :bar)
• Download panel data (CSV, PNG)
• Stat panels (show single or multiple stats)
• Summary statistics in panels

Development

Documentation can be generated with ExDoc and published on HexDocs. Once published, the docs can be found at https://hexdocs.pm/luminous.