Skip to main content

Documentation Index

Fetch the complete documentation index at: https://opensre.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
Scheduled Deliveries

OpenSRE can deliver recurring reports to messaging providers on a cron schedule. This enables daily reliability digests, weekly alert audits, synthetic test summaries, and custom investigations — all delivered automatically without manual CLI invocations.

​
Quick Start

# Add a daily summary to Telegram at 09:00 IST on weekdays
opensre cron add --kind daily_summary --cron "0 9 * * 1-5" \
  --tz Asia/Kolkata --provider telegram --chat-id <chat_id>

# List configured tasks
opensre cron list

# Run a task immediately (for debugging)
opensre cron run <task_id>

# Start the scheduler daemon
opensre cron start

​
CLI Commands

​
opensre cron add

Create a new scheduled delivery task.
OptionRequiredDescription
--kindYesTask kind: daily_summary, weekly_audit, incident_window_replay, synthetic_run, custom_investigation
--cronYesCron expression (5 fields: minute hour day month day_of_week)
--tzNoIANA timezone (default: UTC). Examples: Europe/London, US/Eastern, Asia/Kolkata
--providerYesMessaging provider: telegram, slack, discord
--chat-idYesTarget chat/channel ID for the provider
--windowNoLookback window in hours (default: 24)

​
opensre cron list

Display all configured scheduled tasks in a table.

​
opensre cron remove <task_id>

Delete a scheduled task by its ID.

​
opensre cron run <task_id>

Execute a task immediately (ad-hoc one-shot). Useful for debugging delivery without waiting for the next cron tick.

​
opensre cron logs <task_id>

Show execution history for a task (newest first). Displays start time, status, message ID, and any errors.

​
opensre cron start

Start the blocking scheduler daemon. Loads all enabled tasks and fires them according to their cron schedules. Blocks until SIGINT or SIGTERM.

​
Cron Syntax

Standard 5-field cron expressions: 
┌───────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌───────────── day of month (1-31)
│ │ │ ┌───────────── month (1-12)
│ │ │ │ ┌───────────── day of week (0-6, Mon-Sun)
│ │ │ │ │
* * * * *
Examples:
  • 0 9 * * 1-5 — weekdays at 09:00
  • 0 8 * * 1 — Mondays at 08:00
  • */30 * * * * — every 30 minutes
  • 0 0 1 * * — first day of each month at midnight
Cron expressions are validated at cron add time using APScheduler’s CronTrigger. Invalid expressions are rejected immediately.

​
Timezone Behavior

  • All fire times are internally converted to UTC for dedup consistency
  • The --tz option accepts any IANA timezone (e.g., Europe/London, US/Eastern)
  • DST transitions are handled correctly — the UTC-normalized dedup key ensures no duplicate or missed deliveries across clock changes

​
Dedup Semantics

The scheduler uses a SQLite-backed claim store with a UNIQUE(task_id, fire_time) constraint:
  1. When a cron tick fires, EVENT_JOB_SUBMITTED captures scheduled_run_times[0] and the job uses that UTC-normalized fire_time for the claim key
  2. The executor attempts an INSERT OR IGNORE into the claim table
  3. If the insert succeeds (rowcount = 1), this instance won the claim and delivers
  4. If the insert is ignored (rowcount = 0), another instance already claimed it — skip
This ensures exactly-once delivery even when multiple scheduler instances run concurrently (e.g., on a laptop and a hosted process).

​
Credential Resolution

Credentials are resolved lazily at delivery time in this priority order:
  1. Integration store — ~/.config/opensre/integrations.json (configured via opensre integrations)
  2. Environment variables — TELEGRAM_BOT_TOKEN, SLACK_BOT_TOKEN, DISCORD_BOT_TOKEN
  3. Task params — credentials stored in the task definition (not recommended)
This means you don’t need to pass credentials at cron add time — they’re picked up from your existing integration configuration.

​
Task Kinds

KindBehavior
daily_summaryRuns the investigation pipeline with a daily summary source. Falls back to “no incidents” on empty result, or “pipeline unavailable” on failure.
weekly_auditRuns the pipeline with a weekly audit source. Same fallback behavior.
incident_window_replayReplays the investigation pipeline over the configured window. Raises on failure (operator should know).
synthetic_runRuns the pipeline with a synthetic source. Raises on failure.
custom_investigationRuns a custom investigation with user-provided params. Credential keys are stripped before forwarding to the pipeline.

​
Persistence

  • Task definitions are stored in ~/.config/opensre/scheduler_tasks.json (JSON + filelock)
  • Execution history is stored in ~/.config/opensre/scheduler.db (SQLite with WAL mode)
  • Both survive process restarts — opensre cron list and opensre cron logs read from disk

​
REPL

The /cron slash command in the interactive shell forwards to the CLI: 
/cron list
/cron add --kind daily_summary --cron "0 9 * * *" --provider telegram --chat-id <id>
/cron run <task_id>