# dista.metrics

> A module of Dista's API.

Prometheus metrics: counters and a histogram, and the `/metrics` page.

With `DISTA_METRICS_PORT` set, the head and every worker answer HTTP on that
port with Prometheus's text format, which Kubernetes monitoring scrapes as it
is. It's off by default, since in local mode the head and its workers share
a host.

The server is the smallest one that does: the event loop polls its listener,
and each connection is answered on the spot. The request is read for up to
`READ_TIMEOUT_MS` and only its first line matters; every path gets the
metrics. A scrape is a few kilobytes, so answering it blocks the loop for
well under a millisecond, but a client that connects and sends nothing holds
it for the timeout.

## Structs

### `Histogram`

```mojo
struct Histogram
```

A Prometheus histogram of durations.

Implements: `Copyable`, `Movable`

Fields:

- `counts: List[Int]`: Per bucket, how many observations were at most its bound.
- `count: Int`
- `sum: Float64`

#### `__init__`

```mojo
def __init__(out self)
```

#### `observe`

```mojo
def observe(mut self, seconds: Float64)
```

#### `write`

```mojo
def write(self, mut out: String, name: String, help: String)
```

## Functions

### `bucket_bound`

```mojo
def bucket_bound(i: Int) -> Float64
```

Bucket `i`'s upper bound, in seconds.

### `write_metric`

```mojo
def write_metric(mut out: String, kind: String, name: String, help: String, value: Int)
```

One counter or gauge, without labels.

### `write_outcomes`

```mojo
def write_outcomes(mut out: String, name: String, help: String, ok: Int, err: Int)
```

A counter split by outcome, ok and error.

### `metrics_listener`

```mojo
def metrics_listener() -> Optional[Listener]
```

A listener on `DISTA_METRICS_PORT`, on every interface, if it's set.

### `answer_scrape`

```mojo
def answer_scrape(l: Listener, body: String)
```

Accepts one connection on `l` and answers it with `body`. A client that misbehaves only loses its answer.

## Aliases

### `READ_TIMEOUT_MS`

```mojo
comptime READ_TIMEOUT_MS = 200
```

### `BUCKETS`

```mojo
comptime BUCKETS = 6
```

Task duration buckets: 1 ms, 10 ms, 100 ms, 1 s, 10 s and 60 s.