SDK Python

Le paquet Python steadycron est le SDK officiel de surveillance par code. Encapsulez une tâche planifiée avec @steadycron.job et SteadyCron saura quand elle a démarré, réussi ou échoué — et vous alertera si elle ne s’exécute pas à l’heure prévue ou démarre sans jamais se terminer.

Le SDK ne crée jamais de monitors. Vous déclarez le monitor heartbeat en code — dans un manifeste YAML ou avec le provider Terraform — puis le référencez depuis votre application par son key stable. Le planning cron, les règles d’alerte et l’instrumentation vivent ainsi dans le même dépôt.

Installation

pip install steadycron

Aucune dépendance d’exécution — le SDK utilise uniquement la bibliothèque standard de Python.

Démarrage rapide

import steadycron

steadycron.api_key = "sc_ro_..."  # clé en lecture seule ; ou définissez STEADYCRON_API_KEY

@steadycron.job("nightly-db-backup")   # le key du monitor, tel que déclaré en code
def backup():
    run_backup()   # start à l'entrée, success au retour, fail (+ relève l'exception) en cas d'erreur

La chaîne "nightly-db-backup" est le même key que celui défini sur la ressource steadycron_heartbeat_monitor (Terraform) ou comme id de la tâche heartbeat (manifeste YAML). C’est le seul contrat entre votre schedule-as-code et votre application.

Gestionnaire de contexte

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

Pings manuels

Pour un contrôle plus fin, envoyez les pings vous-même :

m = steadycron.Monitor("nightly-db-backup")
m.ping()                              # heartbeat de succès
m.ping(state="start")
m.ping(state="fail", message="disk full")

Authentification

Le SDK utilise une clé API en lecture seule pour résoudre un key de monitor en jeton de ping au démarrage. Créez-en une dans Paramètres → Clés API → Nouvelle clé → Portée : Lecture seule.

Fournissez-la via l’une de ces méthodes :

• Variable d’environnement : STEADYCRON_API_KEY=sc_ro_...
• Attribut du module : steadycron.api_key = "sc_ro_..."
• steadycron.configure(api_key="sc_ro_...")

Configuration

import steadycron

steadycron.configure(
    api_key="sc_ro_...",
    environment="production",   # optionnel — envoyé à chaque ping
    capture_errors=True,        # inclure le message d'exception dans les pings fail (défaut : False)
    ping_timeout=5.0,           # secondes (défaut : 5)
    resolve_cache_ttl=3600.0,   # secondes (défaut : 3600 = 1 heure)
)

Paramètre	Défaut	Variable d’environnement
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	—

Fonctionnement

1. À la première utilisation, le SDK appelle GET /api/monitors/resolve?key=<votre-key> avec la clé API en lecture seule pour récupérer le jeton de ping. Le jeton est mis en cache pendant une heure (configurable via resolve_cache_ttl).
2. Tous les pings sont fire-and-forget : un ping_timeout borné est appliqué, et toute erreur est journalisée via logging.getLogger("steadycron") en WARNING puis abandonnée. Les pings ne lèvent jamais d’exception.
3. Les erreurs de résolution — 404 (key inconnu), 409 (key ambigu) ou type incorrect — sont levées immédiatement à la première utilisation. Elles indiquent une erreur de configuration.
4. En cas d’exception dans la tâche encapsulée, un ping fail est envoyé et l’exception d’origine est relevée inchangée.

Mode direct / jeton

Si vous ne pouvez pas utiliser la résolution par clé API (par exemple dans un environnement isolé), définissez le jeton de ping directement et court-circuitez l’appel de résolution :

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

Le jeton est visible dans le tableau de bord sous Détail de la tâche → Surveillance par code → Révéler le jeton de ping.

Garanties de fiabilité

• Les échecs de ping ne sont jamais levés. Une erreur de transport, un timeout ou une réponse non-2xx est journalisée puis abandonnée — une panne de surveillance n’interrompt jamais votre tâche.
• Les erreurs de résolution sont toujours levées. Un 404 ou 409 du point de résolution lève une exception à la première utilisation ; corrigez le key ou retirez le décorateur.
• Les exceptions d’origine passent inchangées. Le décorateur et le gestionnaire de contexte n’enveloppent pas vos exceptions.
• Aucune dépendance d’exécution. Le SDK utilise urllib.request de la bibliothèque standard.

Voir aussi

• Surveillance heartbeat — comment les exécutions manquées, échouées et bloquées sont détectées
• SDK .NET — le même workflow de surveillance par code pour .NET
• Provider Terraform — déclarer le monitor et son key en HCL
• YAML & CLI — déclarer le monitor dans un manifeste à la place
• Extraits de ping — pinguer depuis n’importe quel langage ou shell, sans le SDK