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"
}
labelis the name a person reads (up to 120 characters).keynames 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, notm1).sourceandextraction_pathsay where the value is:json_path(dot notation such as$.queue.pendingoritems.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-cookieand the authentication headers are refused) orhttp_status(no path).typeisnumericfor a number. A JSONtrueorfalseis not a number, so expose 0 or 1.stringbands text: list the healthy words inok_values, the warning words inwarn_valuesand the failing words incritical_values, and sendunmatched_band(usuallyok) for a word in no list.POST /monitorsfillsunmatched_bandwithokonce a list is set;POST /monitors/{monitor}/metricsleaves it empty, and a word with no band never counts as calm.statusaccepts onlyup,down,degradedorpaused, is shown but never alerts: for a health word usestring.unitsays what the number is measured in (count,millisecond,percent,byteand 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_boundmust be belowcritical_bound.low_bad: a lower value is worse (free disk, success rate).warn_boundmust be abovecritical_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_kindtells it how to read the number.gauge(default) is a level that moves up and down, such as queue depth or memory.counteris a total that only grows, such as requests served; Uptizm reads its rate and treats a drop as a reset.count_per_periodis a count that restarts each period, such as errors in the last minute. Pick the kind that matches the number.anomaly_directionis the unusual side:high_bad,low_badorboth(default). It is separate fromthreshold_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_sensitivityislow,medium(default) orhigh. 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 #
POST /monitors/{monitor}/metrics/previewwith 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. Sendsample_bodyto test against your own JSON before anything is deployed, or leave it out to read the newest response a check archived (POST /monitors/{monitor}/testruns one now).- Create the metric, then
GET /monitors/{monitor}/metricsshows its latest value and band. - Tell your human what each number means, why it matters and where you set its bounds.