Python-SDK

Überwachen Sie geplante Jobs aus Ihrem Python-Code mit dem offiziellen SteadyCron-SDK. Umschließen Sie einen Job mit @steadycron.job und werden Sie bei verpassten, fehlgeschlagenen und hängenden Läufen alarmiert — der Monitor wird als Code in YAML oder Terraform deklariert.

Das Python-Paket steadycron ist das offizielle Code-Monitoring-SDK. Umschließen Sie einen geplanten Job mit @steadycron.job, und SteadyCron erkennt, wann er gestartet, erfolgreich war oder fehlgeschlagen ist — und alarmiert Sie, wenn er nicht planmäßig läuft oder startet, aber nie fertig wird.

Das SDK erstellt niemals Monitore. Sie deklarieren den Heartbeat-Monitor als Code — in einem YAML-Manifest oder mit dem Terraform-Provider — und referenzieren ihn aus Ihrer Anwendung über seinen stabilen key. Der Cron-Zeitplan, die Alert-Regeln und die Instrumentierung leben damit im selben Repository.

Installation

pip install steadycron

Keine Laufzeit-Abhängigkeiten — das SDK verwendet ausschließlich die Python-Standardbibliothek.

Schnellstart

import steadycron

steadycron.api_key = "sc_ro_..."  # Nur-Lesen-Schlüssel; oder STEADYCRON_API_KEY setzen

@steadycron.job("nightly-db-backup")   # der Monitor-Key, wie im Code deklariert
def backup():
    run_backup()   # start bei Eintritt, success bei Rückgabe, fail (+ erneutes Auslösen) bei Exception

Die Zeichenkette "nightly-db-backup" ist derselbe key, den Sie auf der steadycron_heartbeat_monitor-Ressource (Terraform) oder als Heartbeat-Job-id (YAML-Manifest) gesetzt haben. Das ist der einzige Vertrag zwischen Ihrem Schedule-as-Code und Ihrer Anwendung.

Kontextmanager

with steadycron.monitor("nightly-db-backup"):
    run_backup()

Manuelle Pings

Für feinere Kontrolle senden Sie die Pings selbst:

m = steadycron.Monitor("nightly-db-backup")
m.ping()                              # Erfolgs-Heartbeat
m.ping(state="start")
m.ping(state="fail", message="disk full")

Authentifizierung

Das SDK verwendet einen Nur-Lesen-API-Schlüssel, um einen Monitor-Key beim Start zu seinem Ping-Token aufzulösen. Erstellen Sie einen unter Einstellungen → API-Schlüssel → Neuer Schlüssel → Scope: Nur-Lesen.

Stellen Sie ihn auf einem dieser Wege bereit:

Umgebungsvariable: STEADYCRON_API_KEY=sc_ro_...
Modul-Attribut: steadycron.api_key = "sc_ro_..."
steadycron.configure(api_key="sc_ro_...")

Konfiguration

import steadycron

steadycron.configure(
    api_key="sc_ro_...",
    environment="production",   # optional — bei jedem Ping mitgesendet
    capture_errors=True,        # Exception-Nachricht in fail-Pings einschließen (Standard: False)
    ping_timeout=5.0,           # Sekunden (Standard: 5)
    resolve_cache_ttl=3600.0,   # Sekunden (Standard: 3600 = 1 Stunde)
)

Einstellung	Standard	Fallback-Umgebungsvariable
`api_key`	`None`	`STEADYCRON_API_KEY`
`api_url`	`https://api.steadycron.com`	`STEADYCRON_API_URL`
`ping_url`	`https://ping.steadycron.com`	`STEADYCRON_PING_URL`
`environment`	`None`	`STEADYCRON_ENVIRONMENT`
`capture_errors`	`False`	—
`ping_timeout`	`5.0` s	—
`resolve_cache_ttl`	`3600.0` s	—

Funktionsweise

Bei der ersten Verwendung ruft das SDK GET /api/monitors/resolve?key=<ihr-key> mit dem Nur-Lesen-API-Schlüssel auf, um das Ping-Token abzurufen. Das Token wird eine Stunde lang zwischengespeichert (konfigurierbar über resolve_cache_ttl).
Alle Pings sind Fire-and-Forget: Ein begrenztes ping_timeout wird angewendet, und jeder Fehler wird über logging.getLogger("steadycron") mit WARNING protokolliert und verworfen. Pings lösen niemals eine Exception aus.
Auflösungsfehler — 404 (unbekannter Key), 409 (mehrdeutiger Key) oder falsche Art — werden sofort beim ersten Aufruf ausgelöst. Sie deuten auf eine Fehlkonfiguration hin.
Bei einer Exception innerhalb des umschlossenen Jobs wird ein fail-Ping gesendet, und die ursprüngliche Exception wird unverändert erneut ausgelöst.

Direkt-/Token-Modus

Wenn Sie die API-Key-Auflösung nicht nutzen können (z. B. in einer abgeschotteten Umgebung), setzen Sie das Ping-Token direkt und überspringen den Resolve-Aufruf:

steadycron.monitors = {"nightly-db-backup": "hRkmWz8oZtlMFzvTAUdnRE"}

Das Token finden Sie im Dashboard unter Job-Detail → Code-Monitoring → Ping-Token anzeigen.

Zuverlässigkeitsgarantie

Ping-Fehler werden nie ausgelöst. Ein Transportfehler, Timeout oder eine Nicht-2xx-Antwort wird protokolliert und verworfen — ein Ausfall des Monitorings legt nie Ihren Job lahm.
Auflösungsfehler werden immer ausgelöst. Ein 404 oder 409 vom Resolve-Endpunkt löst beim ersten Aufruf eine Exception aus; korrigieren Sie den Key oder entfernen Sie den Decorator.
Ursprüngliche Exceptions bleiben unverändert. Decorator und Kontextmanager umhüllen Ihre Exceptions nicht.
Keine Laufzeit-Abhängigkeiten. Das SDK verwendet urllib.request aus der Standardbibliothek.

Weiterführend

Heartbeat-Monitoring — wie verpasste, fehlgeschlagene und hängende Läufe erkannt werden
.NET-SDK — derselbe Code-Monitoring-Workflow für .NET
Terraform-Provider — den Monitor und seinen key als HCL deklarieren
YAML & CLI — den Monitor stattdessen in einem Manifest deklarieren
Ping-Snippets — aus jeder Sprache oder Shell pingen, ohne das SDK