Troubleshooting

Requests. Make a few requests to a normal route such as /hello, then open the matching project in Vigilon. Data should appear within 30-45 seconds. Health checks are left out by default, so calling /health will not verify the setup.

Errors. Call the /data example from Recording errors and look for its RuntimeError in Errors.

Jobs. Run the first example from Background jobs and look for refresh-cache in Jobs.

First, look in your app’s startup logs for VIGILON_API_KEY is not set; Vigilon is off. The telemetry.py helper from the quickstart logs it when the process running your app has no API key, or still has the placeholder value. Your app runs normally in that state, but nothing is sent.

Confirm that the API key belongs to the project you are looking at, and that the environment variables are set in the process that runs your app, not only in your own shell.

Then enable debug logging before calling start_vigilon() or vigilon.register(). Vigilon and the OpenTelemetry libraries it is built on use Python’s standard logging system:

import logging

logging.basicConfig(level=logging.DEBUG)
logging.getLogger("opentelemetry").setLevel(logging.DEBUG)
logging.getLogger("vigilon").setLevel(logging.DEBUG)

Restart the app, send a request, and read the process logs. Look for a failure when Vigilon starts, or for errors when it sends data. An authentication error means the API key was rejected.

If you start your app with the opentelemetry-instrument launcher and another OpenTelemetry distribution is installed in the same environment, the launcher may have picked that one instead of Vigilon. Your app runs normally, but nothing reaches Vigilon, and the startup output can include a warning such as Configuration of vigilon not loaded. Select Vigilon explicitly:

export OTEL_PYTHON_DISTRO="vigilon"
export OTEL_PYTHON_CONFIGURATOR="vigilon"
opentelemetry-instrument python app.py

If outgoing calls and database queries appear but requests to your own routes do not, Vigilon started too late to hook into your web framework. Check these in order:

Import order. start_vigilon() must run before FastAPI, Flask, or Django is imported, including imports made by your own modules.

Django settings. DJANGO_SETTINGS_MODULE must be set before Vigilon starts.

Worker servers. Under Gunicorn, uWSGI, or Celery, Vigilon must start inside each worker. See the Worker processes guide.

Excluded routes. /health, /ready, and /favicon.ico are left out by default, along with anything in VIGILON_EXCLUDED_URLS.

Fix the cause and restart the process. Calling register() a second time does not retry; Vigilon ignores repeat calls.

Sometimes you cannot fix the import order, for example when a framework CLI or a preloading server creates your app before your code runs. In that case, start Vigilon and then connect it to the existing FastAPI or Flask object yourself, before serving requests. Do this only for an app Vigilon has not already hooked into.

For FastAPI, replace app with your existing FastAPI object. FastAPIInstrumentor comes from OpenTelemetry, which is installed with the SDK:

from telemetry import start_vigilon

start_vigilon()

from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor

FastAPIInstrumentor.instrument_app(
    app,
    excluded_urls=r"/health$,/ready$,/favicon\.ico$",
)

For Flask, the equivalent is:

from opentelemetry.instrumentation.flask import FlaskInstrumentor

FlaskInstrumentor().instrument_app(
    app,
    excluded_urls=r"/health$,/ready$,/favicon\.ico$",
)

List every route you want left out in excluded_urls, including the defaults shown here. These calls do not pick up Vigilon’s defaults or VIGILON_EXCLUDED_URLS.

Jobs. Installing Celery or a scheduler is not enough. Each job has to be wrapped with with_job_monitor, and Vigilon has to be running before the job executes. A job that runs before startup still does its work but is not reported.

Errors. Unhandled exceptions are recorded automatically. Exceptions you catch yourself are only recorded if you call record_error(error) inside a request, job, or Lambda invocation.