pharos/config

User-facing configuration for pharos.start_link.

Build a Config with new/0 (sensible defaults), pipe through the with_* setters to add statistics, thresholds, and tune the alert timing knobs, then pass it to pharos.start_link.

Types

AlertSink

</>

Where pharos should route firing/resolved alert events. Each configured sink becomes one handler on the alert event bus (see pharos/sink).

Console logs the alert locally (NixOS journalctl debugging).
Webhook POSTs a JSON body to url (e.g. Slack) for direct notification when the Brain is unreachable.
Brain ETF-encodes the alert and sends it to the registered process name on node for native BEAM-to-BEAM delivery (an empty node targets the local node).
Otlp exports to an OpenTelemetry collector at endpoint. Currently a documented stub pending the Protobuf/gRPC exporter.

pub type AlertSink {
  Console(level: logging.LogLevel)
  Webhook(url: String)
  Brain(node: String, name: String)
  Otlp(endpoint: String)
}

Constructors

```
Console(level: logging.LogLevel)
```
```
Webhook(url: String)
```
```
Brain(node: String, name: String)
```
```
Otlp(endpoint: String)
```

BrainStream

</>

Target for the buffered metric stream managed by the connection manager. node is the remote BEAM node (empty string = local node); name is the registered process to deliver ETF payloads to.

pub type BrainStream {
  BrainStream(node: String, name: String)
}

Constructors

```
BrainStream(node: String, name: String)
```

Config

</>

pub type Config {
  Config(
    statistics: List(statistic.Statistic),
    thresholds: List(Threshold),
    custom_statistics: List(probe.Probe),
    custom_thresholds: List(probe.ProbeThreshold),
    alert_sinks: List(AlertSink),
    memory_unit: measurement.MemoryUnit,
    soak_period_ms: Int,
    cool_period_ms: Int,
    default_alert_level: alert.AlertLevel,
    metric_buffer_capacity: Int,
    brain: option.Option(BrainStream),
    metric_spillover_path: option.Option(String),
    poll_jitter: option.Option(Float),
  )
}

Constructors

```
Config(
  statistics: List(statistic.Statistic),
  thresholds: List(Threshold),
  custom_statistics: List(probe.Probe),
  custom_thresholds: List(probe.ProbeThreshold),
  alert_sinks: List(AlertSink),
  memory_unit: measurement.MemoryUnit,
  soak_period_ms: Int,
  cool_period_ms: Int,
  default_alert_level: alert.AlertLevel,
  metric_buffer_capacity: Int,
  brain: option.Option(BrainStream),
  metric_spillover_path: option.Option(String),
  poll_jitter: option.Option(Float),
)
```
Arguments

statistics

Statistics to poll, each with its own interval.

thresholds

Thresholds to evaluate on every matching measurement tick. An empty list means “observe only, never alert”.

custom_statistics

Custom probes to poll alongside the built-in statistics. The pluggable lane for signals pharos has no built-in StatisticKind for.

custom_thresholds

Thresholds evaluated against custom probe samples.

alert_sinks

Where to route firing/resolved alert events.

memory_unit

Unit for all memory threshold comparisons and decoded measurements.

soak_period_ms

Milliseconds a threshold must stay breached before an alert fires. Set to 0 to fire immediately without a soak period.

cool_period_ms

Milliseconds recovery must hold before a firing alert resolves.

default_alert_level

Default severity level attached to firing alerts.

metric_buffer_capacity

Capacity of the in-memory hot buffer (number of recent metrics kept before the oldest are evicted).

brain

Where to stream buffered metrics. None disables the connection manager (metrics are still buffered locally, just not shipped).

metric_spillover_path

On-disk path for the Dets cold-tier spillover file. None keeps metrics RAM-only. Only effective when a Brain stream is also configured: with no connection there is nothing to spill for. When set, metrics spill to disk if the connection is lost and the hot buffer fills, and are replayed (disk first) on reconnect.

poll_jitter

Polling jitter as a fraction of each statistic’s interval, in [0.0, 1.0]. When Some(ratio), each poller starts after a random delay in [0, interval * ratio), permanently phase-shifting its periodic schedule so a fleet of agents never polls (and ships to the Brain) in lockstep. None (the default) disables jitter and leaves polling unchanged.

Threshold

</>

pub type Threshold {
  TotalMemory(above: Float)
  ProcessMemory(above: Float)
  SystemMemory(above: Float)
  BinaryMemory(above: Float)
  EtsMemory(above: Float)
  TotalRunQueue(above: Int)
  CpuRunQueue(above: Int)
  ProcessCount(above: Int)
  AtomCount(above: Int)
  PortCount(above: Int)
  PersistentTermCount(above: Int)
  PersistentTermMemory(above: Float)
  HostMemoryUsed(above: Float)
  HostDiskUsed(above: Float)
  HostCpuUtil(above: Float)
  SchedulerUtilization(above: Float)
  Windowed(
    over: Threshold,
    window_ms: Int,
    mode: alert.WindowMode,
  )
}

Constructors

```
TotalMemory(above: Float)
```
```
ProcessMemory(above: Float)
```
```
SystemMemory(above: Float)
```
```
BinaryMemory(above: Float)
```
```
EtsMemory(above: Float)
```
```
TotalRunQueue(above: Int)
```
```
CpuRunQueue(above: Int)
```
```
ProcessCount(above: Int)
```
```
AtomCount(above: Int)
```
```
PortCount(above: Int)
```
```
PersistentTermCount(above: Int)
```
```
PersistentTermMemory(above: Float)
```
```
HostMemoryUsed(above: Float)
```
```
HostDiskUsed(above: Float)
```
```
HostCpuUtil(above: Float)
```
```
SchedulerUtilization(above: Float)
```
```
Windowed(over: Threshold, window_ms: Int, mode: alert.WindowMode)
```
Sliding-window wrapper: evaluates over metrics aggregated across the last window_ms of samples per mode, instead of per-tick. over supplies the metric and limit, nesting Windowed is not supported.

Values

new

</>

pub fn new() -> Config

Sensible defaults: no statistics, no thresholds, log alerts at Warning, scale memory in Mb, 30 s soak, 60 s cool, default alert level Warning. Pipe through with_* setters to customise.

threshold_id

</>

pub fn threshold_id(threshold: Threshold) -> String

Stable string id derived from a threshold variant. Used to register per-threshold alert managers under a deterministic name so they can be looked up after a restart.

with_alert_sinks

</>

pub fn with_alert_sinks(
  config: Config,
  sinks: List(AlertSink),
) -> Config

Set the alert sinks. Replaces any previously configured list.

with_brain_stream

</>

pub fn with_brain_stream(
  config: Config,
  node: String,
  name: String,
) -> Config

Stream buffered metrics to the registered process name on node (empty node = local node). Enables the connection manager.

with_cool_period

</>

pub fn with_cool_period(
  config: Config,
  milliseconds: Int,
) -> Config

Set the cool-down period (milliseconds recovery must hold before resolving).

with_custom_statistics

</>

pub fn with_custom_statistics(
  config: Config,
  probes: List(probe.Probe),
) -> Config

Set the custom probes to poll. Replaces any previously configured list.

with_custom_thresholds

</>

pub fn with_custom_thresholds(
  config: Config,
  thresholds: List(probe.ProbeThreshold),
) -> Config

Set the custom probe thresholds. Replaces any previously configured list.

with_default_alert_level

</>

pub fn with_default_alert_level(
  config: Config,
  level: alert.AlertLevel,
) -> Config

Set the default alert level attached to firing alerts.

with_memory_unit

</>

pub fn with_memory_unit(
  config: Config,
  unit: measurement.MemoryUnit,
) -> Config

Set the memory unit used for threshold comparisons and decoded measurements.

with_metric_buffer_capacity

</>

pub fn with_metric_buffer_capacity(
  config: Config,
  capacity: Int,
) -> Config

Set the hot-buffer capacity (number of recent metrics retained).

with_metric_spillover

</>

pub fn with_metric_spillover(
  config: Config,
  path: String,
) -> Config

Enable the Dets cold-tier spillover at path. Metrics spill to this file when the Brain connection is lost and the hot buffer fills, and are replayed (disk first) on reconnect. Only effective alongside with_brain_stream.

with_poll_jitter

</>

pub fn with_poll_jitter(config: Config, ratio: Float) -> Config

Jitter polling by up to ratio of each statistic’s interval (clamped to [0.0, 1.0]). Each poller starts after a random delay in [0, interval * ratio), staggering traffic across a fleet so agents never poll in lockstep.

with_soak_period

</>

pub fn with_soak_period(
  config: Config,
  milliseconds: Int,
) -> Config

Set the soak period (milliseconds a threshold must stay breached before firing). Set to 0 to fire immediately.

with_statistics

</>

pub fn with_statistics(
  config: Config,
  statistics: List(statistic.Statistic),
) -> Config

Set the statistics to poll. Replaces any previously configured list.

with_thresholds

</>

pub fn with_thresholds(
  config: Config,
  thresholds: List(Threshold),
) -> Config

Set the thresholds to evaluate. Replaces any previously configured list.

Constructors

Constructors

Constructors

Arguments

Constructors