Pharos

BEACON / PHAROS (φάρος), (...) The system was reportedly created by Leo the Mathematician, who devised a code tor the interpretation of signals, and had two identical water clocks (see Horologion) made for the terminal stations. His work took account of the difference in longitude and of the time the signal needed for transmission. Modern experiments suggest that one hour would suffice for the entire distance. The beacons consisted of huge bonfires on platforms or towers within fortifications on isolated hills. (...) ¹

Pharos is a decentralized "smart sensor" for the BEAM: a producer-only monitor and alert manager that watches a node and its host, evaluates thresholds locally, and streams metrics to a central collector, while staying alive through network partitions.

It is built as a plugin over :telemetry and telemetry_poller, and runs as a supervised OTP application that you embed in your own program via pharos.start_link/1.

Features

• Three-tier collection out of the box:
  • Host (OS): memory (/proc/meminfo), disk and CPU (OTP os_mon), network throughput (/proc/net/dev).
  • BEAM runtime: memory, run queues, system counts, persistent terms, scheduler utilization, reductions.
  • Application: any :telemetry signal, via a pluggable custom-probe lane.
• Local alerting engine:
  • Per-threshold soak/cool state machines (built on eparch) that debounce, de-duplicate, and auto-resolve alerts. Nothing fires on a transient blip; nothing stays stuck firing after recovery.
• Resilient metric pipeline:
  • A connection-manager gen_statem with exponential backoff and a jitter, a bounded in-memory hot buffer (ETS), and an optional disk-backed spillover (Dets) so metrics survive a partition and replay disk-first on reconnect.
• Pluggable alert sinks:
  • Console
  • Webhook (JSON)
  • Native BEAM-to-BEAM (ETF) with an OTLP exporter stub.
• Type-safe configuration:
  • A builder Config where every threshold maps 1:1 to a measured field, so adding a metric is a compiler-guided change.

Installation

gleam add pharos

Pharos targets the Erlang runtime (OTP 27+). Host disk/CPU collection uses OTP's os_mon, native delivery uses distributed Erlang (ETF over the distribution protocol).

Quick start

import pharos
import pharos/alert
import pharos/config
import pharos/statistic

pub fn main() {
  let assert Ok(started) =
    pharos.start_link(
      config.new()
      |> config.with_statistics([
        statistic.poll(statistic.BeamMemory),
        statistic.poll_every(statistic.BeamRunQueues, 500),
        statistic.poll(statistic.HostCpu),
      ])
      |> config.with_thresholds([
        config.TotalMemory(above: 500.0),
        config.HostCpuUtil(above: 85.0),
      ]),
    )

  // React to firing / resolved alerts on the event bus.
  let assert Ok(_handler) =
    pharos.subscribe(started.data, fn(event) {
      case event {
        alert.AlertFiring(id:, level:, diagnostic:) -> handle_firing(id, level, diagnostic)
        alert.AlertResolved(id:) -> handle_resolved(id)
      }
    })

  // ... later, when shutting the owning process down:
  // pharos.stop(started.data)
}

See the Quick Start and the usage guide & architecture for thresholds, custom probes, alert sinks, and the resilient Brain metric stream.

Documentation

• Usage guide & architecture
• Quick Start
• API reference: https://hexdocs.pm/pharos

Development

The project uses devenv and Nix for a hermetic development environment:

nix develop

Or, if you are already using direnv:

direnv allow .