Background jobs

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 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 used for last-run and stale-job detection. 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.

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.