Skip to main content

CronRadar for Celery

Auto-discovery for Celery periodic tasks. Add setup_cronradar(app) to your Celery app — every task with a Beat schedule is registered with CronRadar, watched for missed runs, and alerted on if it fails.

Built on top of the cronradar base SDK.

Install

pip install cronradar-celery
# or
poetry add cronradar-celery
# or
uv add cronradar-celery

Python 3.8+ supported. Celery 5.2.2+.

Setup

The SDK reads its API key from the CRONRADAR_API_KEY environment variable.

export CRONRADAR_API_KEY=ck_app_xxxxxxxxxxxxxxxxxxxx

Or pass it explicitly to setup_cronradar(...):

setup_cronradar(app, api_key='ck_app_xxxxxxxxxxxxxxxxxxxx')

Get the API key from the CronRadar dashboard at app.cronradar.com under your application's settings. API keys have the form ck_app_<random>.

Create a separate CronRadar application and API key for production, staging, and development. Store the key in the deployment platform's secret manager; never commit it, print it, or reuse a production key outside production.

Call setup on each Celery app at worker / Beat startup. Repeated setup on the same app is safe, and callbacks remain connected for the worker's lifetime. Tasks from apps that have not been configured and CronRadar's own reconciliation task are ignored.

The API key is process-wide. Use separate worker processes for deployments that report to different CronRadar applications or accounts.

Quickstart

Call setup_cronradar(app) once on your Celery app:

from celery import Celery
from cronradar_celery import setup_cronradar, skip_monitor

app = Celery('myapp', broker='redis://localhost:6379/0')

# Configure your Beat schedule as usual
app.conf.beat_schedule = {
    'send-daily-report': {
        'task': 'tasks.send_daily_report',
        'schedule': '0 8 * * *',  # 8am daily
    },
}

# Hook CronRadar in
setup_cronradar(app)

@app.task
def send_daily_report():
    generate_report()

That's it. On worker / Beat startup, the integration:

  • Walks every entry in app.conf.beat_schedule
  • Pre-syncs each scheduled task to CronRadar (so they appear in the dashboard immediately)
  • Translates crontab(...), schedule(timedelta(...)), and string schedules into standard 5-field POSIX cron
  • Connects to Celery's task_prerun, task_success, and task_failure signals to record start / complete / fail per execution

Decorators

Opt out per task

Decorate a Celery task with @skip_monitor to exclude it from auto-monitoring.

Order matters: @app.task must come first (outermost), @skip_monitor second. Celery resolves the outer decorator at registration time; reversing the order breaks task discovery.

from cronradar_celery import skip_monitor

@app.task
@skip_monitor
def internal_cleanup():
    # not monitored — internal/maintenance tasks you don't need alerts for
    pass

Custom monitor keys

Monitor keys default to the Celery task name (lowercased, dots → dashes). Override the task name itself if you need a different key:

@app.task(name='critical-payment-processor')
def process_payments():
    # registered in CronRadar as "critical-payment-processor"
    pass

The integration uses task.name as the monitor key.

Reference

setup_cronradar(app, api_key=None)

Wires the integration to a Celery app. Call it at application startup; repeated calls for the same app do not duplicate callbacks or discovery.

Parameter Type Required Notes
app celery.Celery yes The Celery app instance.
api_key str optional API key. Falls back to CRONRADAR_API_KEY env var if omitted.

What it does:

  1. Reads app.conf.beat_schedule and pre-syncs each entry to CronRadar.
  2. Connects signal handlers (task_prerun, task_success, task_failure) for lifecycle tracking.

Idempotent — safe to call multiple times if you have multiple Celery apps.

Grace period is configured per-monitor on CronRadar (default 60 seconds; set via the dashboard).

Decorators

Decorator Purpose
@skip_monitor Exclude this task from monitoring even if it has a Beat schedule.

@skip_monitor must be placed after @app.task:

@app.task
@skip_monitor
def internal_cleanup():
    return 'done'

Schedule translation

The integration accepts these schedule types in beat_schedule:

Beat schedule Translated to CronRadar
'0 8 * * *' (string) 0 8 * * * (passthrough)
crontab(hour=8, minute=0) 0 8 * * *
crontab(hour=8, minute=0, day_of_week='mon-fri') 0 8 * * 1-5
schedule(run_every=timedelta(hours=1)) 0 * * * *

If a schedule isn't translatable to standard cron (e.g., solar(...) schedules, sub-minute intervals), the integration logs a warning and that task is not monitored. Other tasks continue normally.

Configuration

Environment variable Required Default Purpose
CRONRADAR_API_KEY yes — API key from the CronRadar dashboard. Format ck_app_xxxxx.
CRONRADAR_BASE_URL no https://cron.life Override the ingestion endpoint.
CRONRADAR_TIMEOUT no 5.0 HTTP request timeout in seconds.
CRONRADAR_LOG_ERRORS no 1 Set to 0 to suppress stderr warnings on network failure.

Error handling

The integration upholds the same hard guarantees as the base SDK:

  1. Never raises to user code. Network errors, timeouts, 4xx/5xx responses — all caught and logged. A failing CronRadar API must not break a Celery task.
  2. Never alters task execution. The integration uses Celery signals; it never modifies task state, results, or retry behavior. If your task raises, Celery's normal retry/error policy runs unchanged.

What this looks like at runtime:

Situation SDK behavior Celery behavior
CronRadar API unreachable Logs once; returns Task runs and is marked SUCCESS/FAILURE normally
Sync on startup fails for one task Logs; continues Other tasks sync; worker starts
Per-task ping fails Logs; returns Task state unchanged
User task raises Records fail_job with exception message Celery applies retry/error policy
Beat schedule not translatable Warns; that task is not monitored Beat still triggers it normally

Troubleshooting

Tasks aren't showing up in the CronRadar dashboard

  1. Confirm setup_cronradar(app) is called once — typically right after app = Celery(...) and after app.conf.beat_schedule = {...} is set.
  2. Confirm tasks are in app.conf.beat_schedule. Tasks invoked via task.delay(...) are not periodic and are not auto-monitored. Use the base cronradar SDK to instrument those manually.
  3. Check CRONRADAR_API_KEY — see "401 Unauthorized" in stderr if it's missing or wrong.
  4. Verify Beat is actually running. Without Beat, no schedule fires, and CronRadar will eventually alert "monitor never executed."

@skip_monitor doesn't seem to apply

Decorator order. The outer decorator must be @app.task:

# correct
@app.task
@skip_monitor
def my_task():
    return 'done'

# wrong — Celery never registers this as a task
@skip_monitor
@app.task
def my_task():
    return 'done'

Some tasks log "schedule not translatable"

You're using a solar(...) schedule, a sub-minute interval, or a custom Beat schedule class. CronRadar monitors at minute resolution; these can't be expressed in standard cron. Either coarsen the schedule, or wrap the task body manually with the base SDK.

My task is @app.task(name='my.dotted.name') — what's the monitor key?

The monitor key matches Celery's task name, normalized to lowercase with dots replaced by dashes: my.dotted.name becomes my-dotted-name. Override with @monitor(key='explicit-key') to make it whatever you want.

How do I migrate from setup_cronradar(app, mode='all')?

Earlier versions accepted a mode argument with values like 'all' and 'opt-in'. The current model is MonitorAll (always) plus @skip_monitor to opt out. Migration:

  1. Drop the mode argument from setup_cronradar() calls.
  2. Add @skip_monitor to any task that was previously not covered under mode='opt-in'.

The mode argument is removed in this version; passing it raises TypeError, which is intentional — agents reading old snippets get a clear signal to update.

Verification

  1. Deploy or restart both the Celery worker and Beat after calling setup_cronradar(app).
  2. Confirm the periodic task appears in the intended CronRadar application with its Beat schedule.
  3. Run the task through Celery and confirm a terminal success or failed result; discovery alone is not activation.
  4. Use CronRadar's guided reliability drill to verify notification delivery without changing the production task.

To test authentication and outbound HTTPS without printing the key:

curl --fail-with-body --silent --show-error --user "$CRONRADAR_API_KEY:" "https://cron.life/api/v1/sync/status"

Migration

If upgrading from selective or mode='all' setup, remove the mode argument and call setup_cronradar(app) once. All Beat-scheduled tasks are monitored by default; keep @skip_monitor only on intentional opt-outs. Deploy, confirm one reconciled registry and terminal run, then remove any old manual heartbeats that use the same task key.

License

© 2026 CronRadar · Proprietary — see LICENSE.

Metadata

Release files for cronradar-celery 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cronradar-celery 0.1.1
File Size Uploaded Provenance Actions
cronradar_celery-0.1.1.tar.gz 18.1 kB Without provenance Details for cronradar_celery-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for cronradar-celery 0.1.1
File Interpreter ABI Platform Actions
cronradar_celery-0.1.1-py3-none-any.whl Python 3 none any Details for cronradar_celery-0.1.1-py3-none-any.whl

Total release size: 30.5 kB

Release files / cronradar_celery-0.1.1.tar.gz

Download URL cronradar_celery-0.1.1.tar.gz
Size 18.1 kB
Tags Source
SHA-256 checksum
How to use checksums
a152bd12fffc2122871986055305c15e9e5c0f35a41baeea1ad6410fd1b8e153
BLAKE2b-256 checksum
How to use checksums
7aceddc6aa4e5c45dc9e2ff37137fb83a0cd93a11fb8b3677ad3ccf75167ae89
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.9.6

Release files / cronradar_celery-0.1.1-py3-none-any.whl

Download URL cronradar_celery-0.1.1-py3-none-any.whl
Size 12.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
22dd4556c2bd2e40cb74095e583ba704a8f95cb7f69da0bd0c7085e797a3590c
BLAKE2b-256 checksum
How to use checksums
32df75a5b1be806901c1d86481881e127ce8331a6e2dd1d1eb1b2cb5e51b9b92
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.9.6

Security for cronradar-celery 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page