# Custom metrics

A custom metric turns one value in a monitor's response into a tracked series. Uptizm reads the value on every check and compares it with warn and critical bounds. On paid plans it also learns what normal looks like, so it can flag an unusual change before a fixed limit is crossed.

## What to track

Track the few numbers that tell you whether the system is healthy and that a person would act on: queue backlog, failed jobs, error rate, latency, free disk or memory, the age of the oldest waiting job. A good metric moves when something is wrong. Skip constants, ids, timestamps and anything that only grows without meaning (a version, an uptime counter): a flat series has nothing to warn about.

Expose the numbers on one read-only JSON endpoint, protected by a bearer token (`auth_config` on the monitor), and return only counts, durations and percentages. Never secrets, hostnames, paths or user data: Uptizm archives the responses it checks.

## Define a metric

Send `metrics` in `POST /monitors`, or add one later with `POST /monitors/{monitor}/metrics`. One metric per number:

```json
{
  "label": "Queue backlog",
  "key": "queue_pending",
  "type": "numeric",
  "source": "json_path",
  "extraction_path": "$.queue.pending",
  "unit": "count",
  "threshold_direction": "high_bad",
  "warn_bound": 100,
  "critical_bound": 500,
  "anomaly_enabled": true,
  "anomaly_kind": "gauge",
  "anomaly_direction": "high_bad",
  "anomaly_sensitivity": "medium"
}
```

- `label` is the name a person reads (up to 120 characters). `key` names the series: lowercase letters, digits and underscores, starting with a letter, up to 40 characters, unique per monitor. Name it for what it measures (`queue_pending`, not `m1`).
- `source` and `extraction_path` say where the value is: `json_path` (dot notation such as `$.queue.pending` or `items.0.count`, no filters), `regex` (the first capture group, or the whole match when there is none), `xpath` (the response is read as HTML), `header` (a header name, any case; `set-cookie` and the authentication headers are refused) or `http_status` (no path).
- `type` is `numeric` for a number. A JSON `true` or `false` is not a number, so expose 0 or 1. `string` bands text: list the healthy words in `ok_values`, the warning words in `warn_values` and the failing words in `critical_values`, and send `unmatched_band` (usually `ok`) for a word in no list. `POST /monitors` fills `unmatched_band` with `ok` once a list is set; `POST /monitors/{monitor}/metrics` leaves it empty, and a word with no band never counts as calm. `status` accepts only `up`, `down`, `degraded` or `paused`, is shown but never alerts: for a health word use `string`.
- `unit` says what the number is measured in (`count`, `millisecond`, `percent`, `byte` and the others on the endpoint page). It labels the number for people and converts nothing.

A numeric value may carry a trailing unit such as `ms` or `%`. Uptizm drops the suffix and keeps the number as written, so `2 s` is stored as 2, not 2000. A comma, as in `1,200`, is not read as a number. When a check cannot produce the value (a missing path, text where a number is expected) it stores nothing for that check; it never records a zero.

## Warn and critical bounds

`threshold_direction` says which side is bad. `warn_bound` and `critical_bound` say where.

- `high_bad`: a higher value is worse (backlog, latency, error rate). `warn_bound` must be below `critical_bound`.
- `low_bad`: a lower value is worse (free disk, success rate). `warn_bound` must be above `critical_bound`.

Equal bounds answer 422. A value that reaches a bound counts as past it. Bounds are compared with the stored number as it is, in the unit you declared, so return the number in that unit and set the bounds in it too. Without `threshold_direction` a numeric metric is never banded.

A numeric reading lands in a band, `ok`, `warn` or `critical`, when the metric has a direction and at least one bound. An incident opens when `incident_threshold` consecutive checks (default 2, set per monitor) are all past a bound; a check that stored nothing is skipped. Its severity is `warn` or `critical` to match, and it closes once readings have stayed `ok` for `incident_threshold` checks and for 15 minutes.

Set warn where a person should look soon and critical where they should act now. When you do not know a hard limit, leave the bounds out instead of guessing: anomaly detection watches the change.

## Anomaly detection

Bounds catch a limit you know. Anomaly detection catches a change from the metric's own normal, so it works where no limit is known. It runs on paid plans, for numeric metrics that opt in with `anomaly_enabled: true` (off by default), on monitors with `anomaly_detection` on (the default).

- It needs history: at least 60 scheduled checks spanning an hour before it speaks. After that it reports a value outside the usual range for three checks in a row, so one spike is ignored.
- `anomaly_kind` tells it how to read the number. `gauge` (default) is a level that moves up and down, such as queue depth or memory. `counter` is a total that only grows, such as requests served; Uptizm reads its rate and treats a drop as a reset. `count_per_period` is a count that restarts each period, such as errors in the last minute. Pick the kind that matches the number.
- `anomaly_direction` is the unusual side: `high_bad`, `low_bad` or `both` (default). It is separate from `threshold_direction`. The detector reads neither the bounds nor the threshold direction, and it skips a metric while an incident from its bounds is open.
- `anomaly_sensitivity` is `low`, `medium` (default) or `high`. Higher reports smaller moves.

A finding never goes above `warn` and starts no escalation. A metric that was judged and then stops reporting is flagged too. Read findings with `GET /monitors/{monitor}/anomalies`. A slow, steady climb can slip past, so give a metric that matters a bound as well.

## AI analysis

`ai_mode` on the monitor sets what the AI does with a finding. `off` (default) keeps it statistical, with no model. `suggest` has the AI label the finding for a person to accept or dismiss in the inbox. `auto` lets the AI open the incident itself when it is confident. It needs the Pro plan: asking for it on a lower plan answers 422, and a monitor already in `auto` that drops below Pro runs as `suggest`. Which AI features a team has depends on its plan.

When an incident opens on a metric, its analysis reads the metric's `label`, `extraction_path`, bounds (or word lists) and recent readings. A plain label and honest bounds produce a better explanation.

## Check the rule, then create it

1. `POST /monitors/{monitor}/metrics/preview` with the draft returns the value your path extracts and the band it would land in; the band needs a direction and a bound. It stores nothing. Send `sample_body` to test against your own JSON before anything is deployed, or leave it out to read the newest response a check archived (`POST /monitors/{monitor}/test` runs one now).
2. Create the metric, then `GET /monitors/{monitor}/metrics` shows its latest value and band.
3. Tell your human what each number means, why it matters and where you set its bounds.
