pharos/probe

Custom monitoring probes - the pluggable lane of pharos.

The built-in Statistic / Measurement / Threshold enums cover BEAM and host signals. A Probe opens the same poll → decode → threshold → alert pipeline to any signal a caller can express, without modifying pharos: it bundles how to poll (a Source), the telemetry event it emits, and how to decode that event into named numeric readings (MetricSample). ProbeThresholds compare a single sample field against a limit and feed the same soak/cool alert machinery the BEAM lane uses.

This is what lets a consumer such as logothetes monitor MicroVMs: register a probe whose Source points at an emitter that reads /proc/<pid> and telemetry:executes the readings, plus thresholds over the decoded fields.

Types

Comparison

</>

Comparison applied by a ProbeThreshold to a sample field.

pub type Comparison {
  Above(limit: Float)
  Below(limit: Float)
}

Constructors

```
Above(limit: Float)
```
```
Below(limit: Float)
```

MetricSample

</>

A single probe reading reduced to named numeric scalars (field -> value). Thresholds select a field by name and compare it against a limit.

pub type MetricSample =
  dict.Dict(String, Float)

Probe

opaque </>

A pluggable probe. Construct with new/5.

pub opaque type Probe

ProbeThreshold

</>

A threshold over one field of a probe’s MetricSample.

pub type ProbeThreshold {
  ProbeThreshold(
    probe_id: String,
    field: String,
    comparison: Comparison,
    level: alert.AlertLevel,
  )
}

Constructors

```
ProbeThreshold(
  probe_id: String,
  field: String,
  comparison: Comparison,
  level: alert.AlertLevel,
)
```
Arguments

probe_id

The Probe.id whose sample this threshold reads.

field

Which MetricSample key to compare.

comparison

How to compare the field value against the limit.

level

Severity carried in AlertFiring events for this threshold.

Source

</>

How telemetry_poller drives a probe.

CustomMfa lowers to the poller’s {module, function, args} measurement: the function is invoked every polling cycle and is expected to call telemetry:execute/3 itself with the probe’s event name.

pub type Source {
  CustomMfa(
    module: atom.Atom,
    function: atom.Atom,
    args: List(dynamic.Dynamic),
  )
}

Constructors

CustomMfa(
  module: atom.Atom,
  function: atom.Atom,
  args: List(dynamic.Dynamic),
)

Values

decode

</>

pub fn decode(
  probe: Probe,
  event: measurement.TelemetryEvent,
) -> Result(dict.Dict(String, Float), String)

Decode a raw telemetry event into a MetricSample using the probe’s decoder.

event_name

</>

pub fn event_name(probe: Probe) -> List(atom.Atom)

The telemetry event name the probe emits.

id

</>

pub fn id(probe: Probe) -> String

The probe’s stable identifier.

interval_ms

</>

pub fn interval_ms(probe: Probe) -> Int

The probe’s polling interval in milliseconds.

new

</>

pub fn new(
  id id: String,
  event_name event_name: List(atom.Atom),
  interval_ms interval_ms: Int,
  source source: Source,
  decode decode: fn(measurement.TelemetryEvent) -> Result(
    dict.Dict(String, Float),
    String,
  ),
) -> Probe

Define a probe.

id - stable identifier, referenced by ProbeThreshold.probe_id.
event_name - the telemetry event the source emits (e.g. [atom.create("logothetes"), atom.create("vm"), atom.create("metrics")]).
interval_ms - how often to poll.
source - how the reading is produced.
decode - lift the raw telemetry event into a MetricSample.

source

</>

pub fn source(probe: Probe) -> Source

How the probe is polled.

threshold_id

</>

pub fn threshold_id(threshold: ProbeThreshold) -> String

Stable string id derived from a probe threshold. Used to register the per-threshold alert manager under a deterministic name (mirrors config.threshold_id for the BEAM lane).

Constructors

Constructors

Arguments

Constructors