Use an existing OpenTelemetry setup

Record caught errors

Your framework instrumentation already records exceptions that escape a request. An exception that your code catches and turns into an error response is different: Vigilon sees a failed request with no error type, message, or stack trace, or no failure at all. To attach it, record the exception on the active span and set that span’s status to error. A small helper makes it one call:

from opentelemetry import trace
from opentelemetry.trace import Status, StatusCode


def record_error(error: BaseException) -> None:
    """Attach a caught exception to the current request or job run."""
    span = trace.get_current_span()
    if span.is_recording():
        span.record_exception(error)
        span.set_status(Status(StatusCode.ERROR, str(error) or type(error).__name__))

Call it inside the catch block, before you return the response. It does not throw or change the response; your code still controls that. It works the same way inside a job run, and outside a request or job it does nothing. In any other language, make the same two calls on the active span.

Report background jobs

Background jobs are not picked up from instrumentation alone. Vigilon reports one execution of a job, such as a cron tick, a queue message, or one loop iteration, as a job run when it receives a span like this:

This helper covers all of it. It starts the root span, records a failure and raises it again so your retry logic still works, and copies the job attributes onto child spans:

from contextlib import contextmanager
from typing import Optional

from opentelemetry import trace
from opentelemetry.context import Context
from opentelemetry.sdk.trace import SpanProcessor
from opentelemetry.trace import SpanKind

JOB_ATTRIBUTES = ("job.name", "job.schedule")


@contextmanager
def job_run(name: str, schedule: Optional[str] = None):
    """Report one execution of a background job as a Vigilon job run."""
    attributes = {"job.name": name}
    if schedule:
        attributes["job.schedule"] = schedule
    tracer = trace.get_tracer("vigilon.jobs")
    # context=Context() makes this the root of a new trace. An exception that
    # leaves the block is recorded on the span, marks it ERROR, and is re-raised.
    with tracer.start_as_current_span(
        f"job {name}", context=Context(), kind=SpanKind.INTERNAL, attributes=attributes
    ) as span:
        yield span


class JobAttributesSpanProcessor(SpanProcessor):
    """Copies the job attributes onto every span started inside a job run."""

    def on_start(self, span, parent_context=None):
        parent = trace.get_current_span(parent_context)
        parent_attributes = getattr(parent, "attributes", None) or {}
        for key in JOB_ATTRIBUTES:
            if key in parent_attributes:
                span.set_attribute(key, parent_attributes[key])

Wrap one execution of the job: with job_run("sync-users", schedule="0 3 * * *"): in Python, or await jobRun({ name: "sync-users", schedule: "0 3 * * *" }, () => syncUsers()) in JavaScript. Register the span processor once, where you set up tracing. In Python, call trace.get_tracer_provider().add_span_processor(JobAttributesSpanProcessor()). In JavaScript, add it to the spanProcessors list of your NodeSDK or tracer provider, ahead of the exporting processors. The zero-code register preload has no place for it. Short jobs are still reported, but a job that runs for more than a few seconds and makes database or outgoing calls may not be, so use a tracing setup file if you have jobs like that.