SDK de Python

Monitoriza tus jobs programados desde tu código Python con el SDK oficial de SteadyCron. Envuelve un job con @steadycron.job y recibe alertas ante ejecuciones perdidas, fallidas o bloqueadas — el monitor se declara como código en YAML o Terraform.

El paquete de Python steadycron es el SDK oficial de monitorización por código. Envuelve un job programado con @steadycron.job y SteadyCron sabrá cuándo comenzó, tuvo éxito o falló — y te alertará si no se ejecuta a tiempo o comienza pero nunca termina.

El SDK nunca crea monitores. Declaras el monitor heartbeat como código — en un manifiesto YAML o con el provider de Terraform — y lo referencias desde tu aplicación por su key estable. El horario cron, las reglas de alerta y la instrumentación viven así en el mismo repositorio.

Instalación

pip install steadycron

Sin dependencias en tiempo de ejecución — el SDK usa únicamente la biblioteca estándar de Python.

Inicio rápido

import steadycron

steadycron.api_key = "sc_ro_..."  # clave de solo lectura; o define STEADYCRON_API_KEY

@steadycron.job("nightly-db-backup")   # el key del monitor, tal como se declaró en código
def backup():
    run_backup()   # start al entrar, success al retornar, fail (+ relanza) ante una excepción

La cadena "nightly-db-backup" es el mismo key que defines en el recurso steadycron_heartbeat_monitor (Terraform) o como id del job heartbeat (manifiesto YAML). Ese es el único contrato entre tu schedule-as-code y tu aplicación.

Gestor de contexto

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

Pings manuales

Para un control más fino, envía los pings tú mismo:

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

Autenticación

El SDK usa una clave API de solo lectura para resolver un key de monitor a su token de ping al iniciar. Crea una en Configuración → Claves API → Nueva clave → Alcance: Solo lectura.

Proporciónala mediante cualquiera de estas opciones:

  • Variable de entorno: STEADYCRON_API_KEY=sc_ro_...
  • Atributo del módulo: steadycron.api_key = "sc_ro_..."
  • steadycron.configure(api_key="sc_ro_...")

Configuración

import steadycron

steadycron.configure(
    api_key="sc_ro_...",
    environment="production",   # opcional — se envía con cada ping
    capture_errors=True,        # incluir el mensaje de excepción en los pings fail (por defecto: False)
    ping_timeout=5.0,           # segundos (por defecto: 5)
    resolve_cache_ttl=3600.0,   # segundos (por defecto: 3600 = 1 hora)
)
AjustePor defectoVariable de entorno
api_keyNoneSTEADYCRON_API_KEY
api_urlhttps://api.steadycron.comSTEADYCRON_API_URL
ping_urlhttps://ping.steadycron.comSTEADYCRON_PING_URL
environmentNoneSTEADYCRON_ENVIRONMENT
capture_errorsFalse—
ping_timeout5.0 s—
resolve_cache_ttl3600.0 s—

Cómo funciona

  1. En el primer uso, el SDK llama a GET /api/monitors/resolve?key=<tu-key> con la clave API de solo lectura para obtener el token de ping. El token se almacena en caché durante una hora (configurable mediante resolve_cache_ttl).
  2. Todos los pings son fire-and-forget: se aplica un ping_timeout acotado, y cualquier error se registra mediante logging.getLogger("steadycron") con nivel WARNING y se descarta. Los pings nunca lanzan excepciones.
  3. Los errores de resolución — 404 (key desconocido), 409 (key ambiguo) o tipo incorrecto — se lanzan inmediatamente en el primer uso. Indican un error de configuración.
  4. Ante una excepción dentro del job envuelto, se envía un ping fail y la excepción original se relanza sin modificar.

Modo directo / token

Si no puedes usar la resolución por clave API (por ejemplo, en un entorno aislado), define el token de ping directamente y omite la llamada de resolución:

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

El token está visible en el dashboard bajo Detalle del job → Monitorización por código → Revelar token de ping.

Garantía de fiabilidad

  • Los fallos de ping nunca se lanzan. Un error de transporte, timeout o respuesta no-2xx se registra y se descarta — una caída de la monitorización nunca derriba tu job.
  • Los errores de resolución siempre se lanzan. Un 404 o 409 del endpoint de resolución lanza una excepción en el primer uso; corrige el key o elimina el decorador.
  • Las excepciones originales pasan sin cambios. El decorador y el gestor de contexto no envuelven tus excepciones.
  • Sin dependencias en tiempo de ejecución. El SDK usa urllib.request de la biblioteca estándar.

Relacionado