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) →
Getting started › From an API key to an Incident

From an API key to an Incident

Create a Resource, send it an Observation, and read the Rule result and the Incident with API v3 and the Python SDK 2.0.

Preview build. The Python SDK 2.0 is installed from a local wheel for the field test; it is not on PyPI yet. Do not install a prerelease from a package index.

You need a running Uptimer 2.0 with at least one Location (see the Quickstart) and Python 3.9 or later.

1. Create an API key

Open API keys → New key, name it, and copy the token. It is shown once. The key acts as you: it reads and writes what you may in each Workspace.

export UPTIMER_URL=http://localhost:8080/api
export UPTIMER_API_KEY=<the token>
# export UPTIMER_WORKSPACE="<id or name>"  # only when the key reaches more than one Workspace

A key that reaches several Workspaces writes only after you choose one: the examples below stop and list the Workspaces until UPTIMER_WORKSPACE names one. With a single Workspace, leave it unset.

2. Install the SDK wheel

Install the wheel file from the field-test pack into a clean environment:

python3 -m venv uptimer-env
uptimer-env/bin/pip install ./uptimer_python_sdk-2.0.0-py3-none-any.whl

3. Create a Resource and send an Observation

import os
import sys
import time

from uptimer import NotFoundError, UptimerClient


def chosen_workspace(client):
    """The Workspace UPTIMER_WORKSPACE names (its id or name), or the only one this key reaches."""
    want = os.environ.get("UPTIMER_WORKSPACE", "")
    reachable = client.workspaces()
    matching = [w for w in reachable if want in (w.id, w.name)] if want else reachable
    if len(matching) != 1:
        choices = ", ".join(f"{w.id} ({w.name})" for w in reachable)
        problem = f"no single Workspace is called {want!r}" if want else f"this key reaches {len(reachable)} Workspaces"
        sys.exit(f"{problem}; set UPTIMER_WORKSPACE to one of: {choices}")
    return client.workspace(matching[0].id)


client = UptimerClient(api_key=os.environ["UPTIMER_API_KEY"], base_url=os.environ["UPTIMER_URL"])
client.check_compatibility()

ws = chosen_workspace(client)
location = client.locations()[0]

try:
    resource = ws.resources.get("checkout-api")
except NotFoundError:
    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,
        },
    )

signal = resource.signals[0]
ws.resources.observe(resource.key, signal=signal.key, state="problem", labels={"status": "503"})

for _ in range(20):
    rule = ws.resources.get(resource.key).rules[0]
    if rule.open_incident:
        break
    time.sleep(0.5)
print(f"rule {rule.key}: {rule.status} - {rule.explanation}")

incident = ws.incidents.get(rule.open_incident)
print(f"incident {incident.id}: {incident.lifecycle}, {incident.confirmation}, {incident.condition}")
for step in incident.history:
    print(f"  {step.at:%H:%M:%S} {step.kind:<16} {step.explanation}")
uptimer-env/bin/python quickstart.py
rule availability: problem - 1 of 1 location failing
incident sexCVBKlJuaa: open, confirmed, problem
  18:29:32 opened           1 of 1 location failing
  18:29:32 confirmed        1 of 1 location failing

Every id is a public id. You never need a database row number.

The same with curl

H="Authorization: Bearer $UPTIMER_API_KEY"
API=$UPTIMER_URL/v3

# Which Workspace: the only one this key reaches, or the one UPTIMER_WORKSPACE
# names by id or name. See them: curl -s -H "$H" $API/workspaces | jq -r '.result[] | "\(.id)  \(.name)"'
WS=$(curl -s -H "$H" $API/workspaces | jq -er --arg want "${UPTIMER_WORKSPACE:-}" '
  .result as $all | ($all | map("\(.id) (\(.name))") | join(", ")) as $choices
  | if $want != "" then [$all[] | select(.id == $want or .name == $want)]
      | if length == 1 then .[0].id else error("no single Workspace is called \($want); choose one of: \($choices)") end
    elif ($all | length) == 1 then $all[0].id
    else error("this key reaches \($all | length) Workspaces; set UPTIMER_WORKSPACE to one of: \($choices)") end') || unset WS
LOC=$(curl -s -H "$H" $API/locations | jq -r '.result[0].id')

curl -s -H "$H" -X POST $API/workspaces/$WS/resources \
  -d '{"template": "website-check", "key": "orders-api", "name": "Orders API",
       "meta": {"url": "https://orders.example.com/health", "locations": ["'$LOC'"],
                "interval_value": 5, "interval_unit": "MINUTE",
                "failure_mode": "at_least_one", "confirm_after": 0, "recover_after": 0}}'

SIGNAL=$(curl -s -H "$H" $API/workspaces/$WS/resources/orders-api | jq -r '.result.signals[0].key')
curl -s -H "$H" -X POST $API/workspaces/$WS/resources/orders-api/observations \
  -d '{"signal": "'$SIGNAL'", "state": "problem"}'

curl -s -H "$H" $API/workspaces/$WS/resources/orders-api | jq '.result.rules[0]'

Next