Python SDK 2.0
The Python client for API v3: Resources, Observations, Incidents, maintenance and errors.
Preview build. SDK 2.0 is installed from the local wheel in the field-test pack. It is not on PyPI yet; do not install a prerelease from a package index.
Install
python3 -m venv uptimer-env
uptimer-env/bin/pip install ./uptimer_python_sdk-2.0.0-py3-none-any.whl
The SDK speaks API v3 and needs Uptimer 2.0 or later. client.check_compatibility() raises IncompatibleServerError against a server without API v3.
Usage
from uptimer import UptimerClient
client = UptimerClient(
api_key="your-api-key", # User → API keys
base_url="http://127.0.0.1:8080/api", # your server, plus /api
)
client.check_compatibility()
The key is a person’s key: it reads and writes what that person may in each Workspace. A viewer reads; changing a Workspace is an editor’s or an owner’s; any member may acknowledge an Incident.
Workspaces, Templates, Locations
client.workspaces() # [Workspace(id, name, role)]
client.create_workspace("Field iteration 2") # Workspace(id, name, role="owner"); a full key only; server after 2.0.0-rc2
client.templates() # the Templates this server publishes, with their fields
client.locations() # [Location(id, name)]
ws = client.workspace("<workspace id>")
From 2.0.0-rc11 (SDK field/2.0.0-rc11), a server administrator with a full key
sets up the fleet without the UI (API):
edge = client.create_location("edge-a") # Location; an existing name returns that Location
worker = client.register_worker(name="worker-01", uid="3f6c2a90-0d1e-4b7a-9c55-2f1e8d4b7a10",
location=edge.id, tags=["linux"])
worker.next_step # "uptimer worker-cert --uid 3f6c2a90-… --out ./3f6c2a90-…", run on the control plane
client.workers() # [Worker(id, uid, name, location, tags, active)]
A uid already registered raises ConflictError; anyone else, or a scoped key, ForbiddenError.
Resources
A Resource is addressed by its id or by its key.
resource = ws.resources.create(
template="website-check",
key="checkout-api",
name="Checkout API",
meta={"url": "https://checkout.example.com/health", "locations": [location_id],
"interval_value": 5, "interval_unit": "MINUTE",
"failure_mode": "at_least_one", "confirm_after": 0, "recover_after": 0},
)
ws.resources.list()
ws.resources.get("checkout-api") # with signals, rules and each rule's latest result
ws.resources.update("checkout-api", name="Checkout", meta={"confirm_after": 60})
ws.resources.rebind("srv-0042", "service-triage@4", meta={"provider": "alpha"}) # pushed-data; server after 2.0.0-rc2
ws.resources.rebind("srv-0042", "service-triage@5", reset_history=["load"]) # SDK field/2.0.0-rc10; server from 2.0.0-rc10
resource.rules[i] carries status, explanation, since and
open_incident once the Rule has decided. From 2.0.0-rc15, a Rule’s status and the
Resource’s open_incident.standing are recovering only while a recovery wait runs. An Incident
held because its composite Rule cannot tell keeps its last decision: problem if it was a
confirmed problem, no_data if the hold stopped its recovery, pending if never confirmed. A hold
is not readable from status alone; the Incident page says it.
From the release candidate after 2.0.0-rc7, a Resource carries labels of its own, set without
changing its Template; a value sets a label and None removes it:
ws.resources.update("srv-0042", labels={"env": "prod", "team": None})
ws.resources.list(labels={"env": "prod"}) # also ws.incidents.list(labels={"env": "prod"})
ws.resources.get("srv-0042").labels # {"env": "prod"}
Destinations
From the release candidate after 2.0.0-rc5, a full API key manages where alerts go. A
destination’s URL is written, never read back.
oncall = ws.destinations.create("oncall", type="slack", url="https://hooks.slack.com/services/…")
ws.destinations.list() # id, name, type, channel, enabled, send_on_open, default
ws.destinations.test(oncall.id) # DestinationTest(status="delivered", reason=None)
ws.destinations.update(oncall.id, enabled=False)
ws.destinations.deliveries(oncall.id) # one page: event, status, reason code, incident
A Template route may name a destination {"name": "oncall"}; ws.destinations.delete(id) raises
ValidationError while a live route still uses it.
Observations
ws.resources.observe("checkout-api", signal=resource.signals[0].key,
state="problem", labels={"status": "503"},
reason="upstream answered 503") # kept with the evidence and alert; cut at 200
ws.resources.observations("checkout-api", limit=20) # newest first
state is ok or problem. The same observation_id sent twice is stored
once. An observation_id over 64 characters raises ValidationError with
field == "id" (from 2.0.0-rc14); in observe_batch only that item is
rejected, with error["details"]["field"] == "id". observations() reads the
newest, limit 1–200 (default 50), with no way to page older: the UI’s
Observation log reads earlier days. It is investigation context, not a record
of what a decision read.
From the release candidate after 2.0.0-rc7, ws.resources.observe_batch(items) sends up to 500
Observations, for any Resources, in one request. Each item is what observe sends plus resource;
the answer has one result per item, accepted with its observation id or rejected with the
error a single send would raise. Give each item an id so a retry stores nothing twice.
items = [{"resource": key, "signal": "origin", "state": "ok", "id": f"round-118-{key}"}
for key in fleet_keys]
for start in range(0, len(items), 500):
result = ws.resources.observe_batch(items[start:start + 500])
for item in result.results:
if not item.accepted:
print(items[start + item.index]["resource"], item.error["message"])
Confirmations
From 2.0.0-rc9 (SDK from the field/2.0.0-rc9 local wheel), ConfirmPolicy,
Confirmer and meta write a Signal’s confirm policy,
and Comparison(..., if_unknown=False) one comparison of a composite Rule.
Manifests stay plain dicts; these build their parts. publish raises ValidationError for a
Rule over the Rule limits: more than 16
comparisons, more than 4 levels, or an action that is blank, padded or over 200 characters.
from uptimer import Comparison, Confirmer, ConfirmPolicy, meta
policy = ConfirmPolicy(
by=[Confirmer(probe="tcp", with_={"host": meta("host"), "port": 5432}),
Confirmer(exec="check-replica", with_={"host": meta("host")})],
refuted_if="any_ok", timeout=30)
manifest = {"key": "replica", "version": 1, "name": "Replica", "summary": "A replica.",
"fields": [{"key": "host", "label": "Host", "type": "string"}],
"signals": [{"key": "port", "kind": "event", "confirm": policy.to_api()},
{"key": "deep", "kind": "event", "on_demand": True}],
"rules": [{"key": "down", "action": "Look at the replica.",
"wait": {"confirm_after": 0, "recover_after": 0},
"decision": {"any": [Comparison("port", "status", "eq", "problem").to_api(),
Comparison("deep", "status", "eq", "problem",
if_unknown=False).to_api()]}}]}
template = ws.templates.publish(manifest)
template.confirm_policy("port") # the same ConfirmPolicy, read back
port = {s.key: s for s in ws.resources.get("db-1").signals}["port"]
port.confirmation # SignalConfirmation(status, reason, effective, original), or None
row = ws.resources.observations("db-1", signal="port")[0]
row.state, row.confirmation # the original; ObservationConfirmation with .confirmers
for one in ws.incidents.get(incident_id).history[0].inputs:
one.status, one.confirmation # what the Rule read; EvidenceConfirmation(status, reason, original)
status is pending, confirmed, unconfirmed or not_run; reason is
refuted, problem_confirmed, timeout, confirmer_no_data, limited or
source_no_data. A server before 2.0.0-rc9 reads confirmation=None.
From 2.0.0-rc11 (SDK field/2.0.0-rc11):
Comparison("port", "confirmation", "eq", "refuted").to_api() # "the checker was wrong"
row.confirmation.shared # True where this reading joined another's confirmation
template.valid_seconds("deep") # an on-demand reading's lifetime; 0 is for ever
template.reset_signals("server_down") # the Signals its recovery resets ([] for none)
port.reset # SignalReset(at, rule) while a recovery's reset holds, else None
See Reset Signals on recovery and Compare a confirmation.
Incidents
page = ws.incidents.list(lifecycle="open", limit=50) # newest first
page.next_cursor # None on the last page
ws.incidents.list(resource="checkout-api", rule="availability",
lifecycle="closed", confirmation="unconfirmed")
ws.incidents.list(lifecycle="open", acknowledged=False, rule="availability") # what still needs action # server after 2.0.0-rc2
for incident in ws.incidents.iterate(lifecycle="open"): # every page
...
incident = ws.incidents.get(incident_id) # with ordered history
ws.incidents.acknowledge(incident_id)
ws.resources.incidents("checkout-api") # one Resource's Incidents
An Incident has lifecycle (open, closed), confirmation (confirmed,
unconfirmed), condition (ok, problem, no_data), the rule it was recorded
with, explanation, opened_at, confirmed_at, closed_at, effective_at,
closed_reason (recovered, rule_removed) and acknowledgement. Its history
is oldest first, and stays after its Rule is edited or removed.
Maintenance
ws.resources.set_maintenance("checkout-api", minutes=60) # holds notifications
ws.resources.end_maintenance("checkout-api")
Errors
Every refusal raises a subclass of UptimerApiError with code,
error_type, message, details and the HTTP status:
| Exception | Code | When |
|---|---|---|
BadRequestError | 1400 | the request could not be read |
AuthenticationError | 1401 | no API key, or one the server does not accept |
ForbiddenError | 1403 | your role does not allow this write |
NotFoundError | 1404 | no such thing in this Workspace, or no such Workspace for you |
ConflictError | 1409 | e.g. acknowledging a closed or already acknowledged Incident |
ValidationError | 1422 | a field was refused; .field names it |
ServerError | 1500 | the server failed |
Examples
From an API key to an Incident walks the shortest path. The field-test pack carries the SDK examples: from a key to an Incident, and a fleet from one Template.