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 three families:

BEAM VM internals - BeamMemory, BeamRunQueues, BeamSystemCounts, BeamPersistentTerm. Built into telemetry_poller.
Distributed Erlang topology - ClusterNodes. Custom measurement emitting [pharos, cluster, nodes].
Per-process introspection - ProcessInfo. Built into telemetry_poller.
Host (OS) - HostMemory, HostDisk. Scaffolded; the FFI emits placeholder events with status: unimplemented until real host probes land.

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
}

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. Scaffolded.
```
HostDisk
```
[pharos, host, disk] - OS-level disk usage. Scaffolded.

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.