Python quickstart
Add tracing, endpoint health, error groups, and job runs to your Python app. Install the SDK, set a few environment variables, and start Vigilon before your app code.
Set up with an AI agent
Using a coding agent such as Claude Code, Codex or Cursor? Paste this prompt into it from the root of your project. It installs and configures the SDK for you, and leaves the API key for you to add.
Run `curl -fsSL https://vigilon.io/agents/install.md` and follow the instructions in that file to set up Vigilon in this project.Install the SDK
Use Python 3.10 or later and install the SDK in the same virtual environment as your app. The package and Python import are both called vigilon.
pip install vigilon
Configure the environment
Get an ingest API key for your project from Vigilon. Set these environment variables in your shell or deployment settings. Replace the API key, choose a stable service name, and set the environment and version for this deployment.
export VIGILON_API_KEY="[YOUR_API_KEY]"
export VIGILON_SERVICE_NAME="orders-api"
export VIGILON_ENVIRONMENT="production"
export VIGILON_SERVICE_VERSION="1.2.3"
VIGILON_SERVICE_VERSION is optional, but recommended for tracking deployments. Use a release version or commit SHA and update it with each deploy.
Start the SDK
Vigilon hooks into FastAPI, Flask, and Django as they are imported, so it has to start before your app imports them. The pattern is the same for every framework: start Vigilon first, then import and create your app.
Create telemetry.py beside your entrypoint. It reads the environment variables from step 2 and starts the SDK. Without an API key it leaves Vigilon off and logs a warning, so your app, tests, and CI still run before you have a key:
import logging
import os
import vigilon
def start_vigilon():
api_key = os.environ.get("VIGILON_API_KEY")
if not api_key or api_key == "[YOUR_API_KEY]":
# No real key yet: the app runs with Vigilon off (local development, CI, tests).
logging.getLogger(__name__).warning("VIGILON_API_KEY is not set; Vigilon is off")
return None
return vigilon.register(
api_key=api_key,
service_name=os.environ["VIGILON_SERVICE_NAME"],
environment=os.environ["VIGILON_ENVIRONMENT"],
service_version=os.environ.get("VIGILON_SERVICE_VERSION"),
)
Running under Gunicorn, uWSGI, or Celery? Create telemetry.py, then call start_vigilon() from a worker hook instead of your entrypoint. The Worker processes guide shows how.
Otherwise, call start_vigilon() at the top of your entrypoint, above the framework import. Choose your framework:
from telemetry import start_vigilon
start_vigilon()
from fastapi import FastAPI
app = FastAPI()
@app.get("/hello")
async def hello():
return {"message": "Hello from FastAPI"}
FastAPI: save this as main.py. With FastAPI and Uvicorn installed, run uvicorn main:app. Open http://127.0.0.1:8000/hello to send a request.
Run and verify
Start your app with the environment variables set, then make a few requests to a normal route such as /hello. Open the matching project in Vigilon, and data should start coming in within 30-45 seconds.
Use a normal application route, not /health, /ready, or /favicon.ico, which are left out by default. If no data arrives, follow the Troubleshooting guide.