Background jobs
Report each cron tick, queue message, or background task as a Job Run with its own trace. Complete the Python quickstart before running these examples.
Monitor a job
Wrap one execution of a job, such as a cron tick, a queue message, or one loop iteration, with with_job_monitor. Each execution is reported as a Job Run with its own trace, even when the job is triggered from inside a web request. Database queries and outgoing calls made inside the job belong to that run.
For a regular function, add the decorator and call the function as usual. This example runs as a script once you have created telemetry.py. The provider.shutdown() call at the end sends any remaining data before the script exits:
from telemetry import start_vigilon
provider = start_vigilon()
from vigilon import with_job_monitor
@with_job_monitor(name="refresh-cache")
def refresh_cache():
# Replace this with the work for one run.
return {"refreshed": True}
if __name__ == "__main__":
try:
refresh_cache()
finally:
if provider is not None:
provider.shutdown()
Async functions work with the same decorator. In your worker, await the function for each execution. Replace the example body with your job logic:
from vigilon import with_job_monitor
@with_job_monitor(name="sync-users", schedule="0 3 * * *")
async def sync_users():
return {"synced": True}
# Inside your async worker:
# await sync_users()
For part of a function, use a regular with statement. It also works inside an async function around code that uses await. The span it gives you is this run’s record in Vigilon; use set_attribute to attach details such as a batch size. Write a new with statement for each execution instead of sharing one monitor between jobs that run at the same time.
from vigilon import with_job_monitor
with with_job_monitor(name="process-batch") as span:
span.set_attribute("batch.size", 25)
# Process one batch here.
Name and schedule
name is required and should stay the same across runs. Use sync-users, not a different name such as sync-user-42 for every item. Put per-run details in attributes instead, as in the example above.
schedule is an optional cron expression that turns on missed-run detection, described below. It describes when your scheduler is expected to run the job; it does not schedule or execute anything. Keep using your cron service, queue, or task scheduler.
Detect missed runs
Give a job a schedule and Vigilon marks it Overdue on the Jobs page when it stops running. A job is Overdue once the schedule has expected two runs since its last completed run and neither arrived, so a run that starts a little late is not flagged.
Vigilon reads the cron expression in UTC. With 0 3 * * *, a job last completed at 03:00 UTC on Monday is expected again on Tuesday and becomes Overdue at 03:00 UTC on Wednesday if no run has completed by then.
Overdue detection is off, and the job's status reflects its last run only, when no run carried a schedule, when the schedule is not a cron expression Vigilon can read, or when the schedule runs less often than once every seven days.
A job whose last run failed shows as Failing instead of Overdue. A run that is still in progress has not completed yet, so a very long run looks the same as a job that has stopped.
Return values and errors
Return values pass through unchanged. Exceptions that leave the monitored code are recorded and re-raised, so your retry logic still works. If you catch an exception inside the job, call record_error(error) yourself.
Start Vigilon before executing jobs. A job that runs before startup still does its work, but Vigilon does not receive a Job Run for it.