Timezone Support in RedBeat

RedBeat is designed to handle timezones correctly, ensuring that tasks run at the expected time regardless of the server's local timezone.

Core Principles

To manage timezones effectively, RedBeat follows these principles:

  1. Internal UTC Storage: The schedule in Redis (redbeat:schedule sorted set) is always stored using UTC timestamps. The score for each task is the number of seconds since the UNIX epoch, which is timezone-agnostic (effectively UTC).

  2. Timezone-Aware Datetimes: All internal datetime objects are timezone-aware. This eliminates ambiguity and ensures that calculations involving time are always correct. When a task is defined with a specific timezone, that information is preserved.

  3. Celery Timezone Configuration: RedBeat respects the CELERY_TIMEZONE setting in your Celery configuration. It's highly recommended to explicitly set this to your desired timezone, typically UTC.

# Recommended Celery settings for timezones
CELERY_ENABLE_UTC = True
CELERY_TIMEZONE = 'UTC'

How it Works

When RedBeat calculates the next run time for a task (due_at), it performs the calculation using timezone-aware datetime objects. The schedule object itself (e.g., crontab, rrule) can be created with timezone information.

Once the next due_at (a timezone-aware datetime) is determined, RedBeat converts it to a UTC-based UNIX timestamp to be used as the score in the Redis sorted set. This normalization ensures that all tasks from all timezones are sorted correctly against each other.

Key Datetime Properties

  • last_run_at: A timezone-aware datetime object representing the last time the task was dispatched.
  • due_at: A property that returns a timezone-aware datetime for the next scheduled run.
  • score: A property that returns the UTC UNIX timestamp for due_at.

By consistently using timezone-aware datetimes internally and storing the final schedule in UTC, RedBeat provides robust and predictable scheduling across different timezones.