Skip to content
Uptizm
Sign in
Menu
View as Markdown

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:

{
  "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.

Type to search the guides, resources and endpoints.