pharos/statistic

What pharos can poll, and how often.

A Statistic pairs a StatisticKind (the what) with a per-statistic polling interval (the how often). Use poll/1 to accept the kind’s default interval, or poll_every/2 to override it.

Statistics group into these families:

BEAM VM internals - BeamMemory, BeamRunQueues, BeamSystemCounts, BeamPersistentTerm. Built into telemetry_poller. BeamScheduler (scheduler utilisation) and BeamReductions are custom emitters.
Distributed Erlang topology - ClusterNodes. Custom measurement emitting [pharos, cluster, nodes].
Per-process introspection - ProcessInfo. Built into telemetry_poller.
Host (OS) - HostMemory (/proc/meminfo, Linux), HostDisk(path) and HostCpu (os_mon’s disksup/cpu_sup), and HostNetwork (/proc/net/dev). Host probes degrade to status: unimplemented when the underlying source is unavailable.

Types

Statistic

</>

A polling instruction: a kind to collect plus how often (in milliseconds).

pub type Statistic {
  Statistic(kind: StatisticKind, interval_ms: Int)
}

Constructors

Statistic(kind: StatisticKind, interval_ms: Int)

StatisticKind

</>

What kind of measurement to collect.

pub type StatisticKind {
  BeamMemory
  BeamRunQueues
  BeamSystemCounts
  BeamPersistentTerm
  ProcessInfo(
    name: atom.Atom,
    event: List(atom.Atom),
    keys: List(atom.Atom),
  )
  ClusterNodes
  HostMemory
  HostDisk(path: String)
  HostCpu
  HostNetwork
  BeamScheduler
  BeamReductions
}

Constructors

```
BeamMemory
```
[vm, memory] - all keys from erlang:memory/0.
```
BeamRunQueues
```
[vm, total_run_queue_lengths] - total / cpu / io queue depths.
```
BeamSystemCounts
```
[vm, system_counts] - process / atom / port counts and limits.
```
BeamPersistentTerm
```
[vm, persistent_term] - persistent term count and memory usage.
```
ProcessInfo(
  name: atom.Atom,
  event: List(atom.Atom),
  keys: List(atom.Atom),
)
```
[pharos, process, <name>] - process_info snapshot for a named process. event overrides the emitted event name; keys selects which process_info keys to collect (e.g. memory, message_queue_len).
```
ClusterNodes
```
[pharos, cluster, nodes] - this node’s name plus the list of connected distributed Erlang nodes.
```
HostMemory
```
[pharos, host, memory] - OS-level memory totals, read from /proc/meminfo (Linux).
```
HostDisk(path: String)
```
[pharos, host, disk] - usage of the filesystem containing path, via os_mon’s disksup.
```
HostCpu
```
[pharos, host, cpu] - host CPU utilisation % and load averages, via os_mon’s cpu_sup.
```
HostNetwork
```
[pharos, host, network] - per-second network throughput summed across non-loopback interfaces, from /proc/net/dev.
```
BeamScheduler
```
[pharos, vm, scheduler] - BEAM scheduler utilisation %, from scheduler_wall_time.
```
BeamReductions
```
[pharos, vm, reductions] - BEAM reductions executed in the last interval.

Values

default_interval_ms

</>

pub fn default_interval_ms(kind: StatisticKind) -> Int

Default polling cadence for each kind. Tuned to match the cost and volatility of the underlying signal: cheap, fast-changing things (run queues) poll often; expensive or slow-changing things (cluster topology, disk) poll rarely.

poll

</>

pub fn poll(kind: StatisticKind) -> Statistic

Poll kind at its default cadence.

poll_every

</>

pub fn poll_every(
  kind: StatisticKind,
  interval_ms: Int,
) -> Statistic

Poll kind every interval_ms milliseconds.