Uptimer v2.0.0-preview documentation — it describes the release candidate, and v1.8.0 remains the current release. Commands here pull the preview image :2.0.0-rc15@sha256:945bd3a8fd42800445826df5d0968fd4c86d1d2a2e69f0fb41d897c66b0b0235. The Python SDK for this preview is a local wheel, not a PyPI release. Go to the current release (v1.8.0) →
Reference › Python SDK 2.0

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:

ExceptionCodeWhen
BadRequestError1400the request could not be read
AuthenticationError1401no API key, or one the server does not accept
ForbiddenError1403your role does not allow this write
NotFoundError1404no such thing in this Workspace, or no such Workspace for you
ConflictError1409e.g. acknowledging a closed or already acknowledged Incident
ValidationError1422a field was refused; .field names it
ServerError1500the 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.