vaka
CI statusLatest releaseGitHub

Install Vaka in a Python application

Project: your-project · Endpoint: https://vaka.example.com · Ingest key: vk_your_ingest_key

These steps are written to be followed by a coding agent. Do them in order and verify at the end.

1. Add the dependency

Add vaka-sdk to the project's dependencies (pyproject.toml, requirements.txt or the lock-file tool the project uses):

pip install vaka-sdk

For a backend service that should also send traces and logs, use the otel extra: vaka-sdk[otel].

2. Initialise once, as early as possible

Put this where the process starts: the top of main, Django's settings.py, or the module that creates the Flask or FastAPI app.

import vaka

vaka.init(
    key="vk_your_ingest_key",
    endpoint="https://vaka.example.com",
    release="2.4.0",              # the app version; read it from your package metadata or CI
    environment="production",
    service="my-service",         # backend services: the service name
)

key, endpoint, release and environment default to VAKA_KEY, VAKA_ENDPOINT, VAKA_RELEASE and VAKA_ENVIRONMENT, so they can come from the deployment environment instead of source code. Without a key the SDK is a no-op.

For the release, prefer the installed version: importlib.metadata.version("your-package"), or the git SHA / build number from CI.

3. Add the framework integration

Pick the one that matches the app:

4. What you get automatically

5. Report errors and events where it matters

try:
    charge(order)
except PaymentError as e:
    vaka.capture_exception(e)         # handled errors you still want to see

vaka.add_breadcrumb("payment started", category="payment", data={"order": order.id})
vaka.set_tag("tenant", tenant.slug)
vaka.set_user(user.id)                # opt-in only: if the privacy policy allows it
vaka.track("order_placed", {"plan": "pro"})

6. Optional: traces and logs

With vaka-sdk[otel], right after vaka.init(...):

import vaka.otel
vaka.otel.setup()

Then add the OpenTelemetry instrumentation packages for the frameworks and clients the app uses, for example opentelemetry-instrumentation-django, -flask, -fastapi, -requests, -httpx, -psycopg or -sqlalchemy, and call their instrument() functions. Spans appear in Vaka's performance views (slow_endpoints, get_trace) and logs in search_logs.

7. Verify

import vaka
vaka.init(key="vk_your_ingest_key", endpoint="https://vaka.example.com", debug=True)
vaka.capture_message("vaka install test", level="info")
vaka.flush()

debug=True prints a [vaka] sent … items (202) line when it works. Then check vaka issues -p your-project (or the MCP tool list_issues): the event appears within a few seconds.