vaka
CI statusLatest releaseGitHub

Python SDK

Package vaka-sdk on PyPI, imported as vaka (source: sdks/python). Python 3.9+. The core has no dependencies: errors, sessions, breadcrumbs, events and flags go to the ingest API from a background thread. Traces and logs go through the standard OpenTelemetry SDK to Vaka's OTLP endpoint, set up with one call.

Agent-followable install guide: /docs/install/python.

pip install vaka-sdk            # errors, sessions, events, flags
pip install "vaka-sdk[otel]"    # + OpenTelemetry traces and logs

Init

import vaka

vaka.init(
    key="vk_...",                       # default $VAKA_KEY
    endpoint="https://vaka.example.com",  # default $VAKA_ENDPOINT
    release="2.4.0",                    # default $VAKA_RELEASE
    environment="production",           # default $VAKA_ENVIRONMENT or "production"
    service="checkout",                 # default $VAKA_SERVICE or $OTEL_SERVICE_NAME
)

Without a key and endpoint the SDK stays disabled and every call is a no-op.

Option Default Meaning
capture_unhandled True Report uncaught exceptions (sys.excepthook, threading.excepthook)
sessions True One session per process for crash-free rates per release
logging True logging records become breadcrumbs (INFO+) and errors (ERROR+)
breadcrumb_level / event_level logging.INFO / logging.ERROR Thresholds for the above; event_level=None turns off error capture from logs
in_app_include / in_app_exclude empty Module prefixes that are (not) your code. Default: everything outside the standard library and site-packages is in-app
before_send None fn(item) -> item or None to edit or drop anything before it is sent
sample_rate 1.0 Share of errors to send
flags False Load feature flags in the background at init
flag_properties {} Properties sent with every flag evaluation
distinct_id random per process Id used for sessions, events and flag bucketing
flush_interval 5.0 Seconds between batches (errors are sent immediately)
debug False (or $VAKA_DEBUG=1) Log SDK activity to stderr

API

vaka.capture_exception(e)                 # or no argument inside `except`; returns the event id
vaka.capture_exception(e, level="warning", tags={"job": "import"}, fingerprint=["import-timeout"])
vaka.capture_message("cache rebuilt", level="info")
vaka.add_breadcrumb("cart loaded", category="db", data={"rows": 3})
vaka.set_tag("region", "eu-north-1")
vaka.set_context("job", {"id": 42, "queue": "imports"})
vaka.set_user("user-123")                 # opt-in; vaka.set_user(None) clears
vaka.track("order_placed", {"plan": "pro", "items": 3})
vaka.flush(2.0)
vaka.shutdown()                           # also runs at interpreter exit

Exception chains (raise ... from ... and implicit context) are sent outermost first, each with frames crash site first, source context lines and in_app marks. Uncaught exceptions are sent synchronously before the interpreter exits and end the session as crashed. The same exception object is only reported once, so a framework that both raises and logs an error doesn't create two events.

Scopes

Tags, breadcrumbs, user, contexts and flag exposures live on a scope. The framework integrations give every request its own copy; for jobs and tasks use:

with vaka.isolation_scope():
    vaka.set_tag("job", "nightly-import")
    run_import()

@vaka.monitor            # isolation scope + report and re-raise + flush
def handle(event, context): ...

Scopes follow contextvars, so each asyncio task keeps its own. A new thread starts on the global scope; use contextvars.copy_context().run to carry a request scope into one.

Cron jobs (heartbeat monitors)

Report each run of a job to a heartbeat monitor. Vaka alerts when a run is missed, fails or runs too long.

@vaka.monitor("nightly-backup", schedule="0 3 * * *", timezone="Europe/Stockholm")
def backup(): ...

with vaka.monitor("hourly-sync", every="1h"):   # also `async with`
    sync()

vaka.check_in("hourly-sync")                     # a single ok
vaka.check_in("hourly-sync", "error", message="upstream down")

A monitored run reports in_progress, then ok with the duration, or error when an exception escapes (it is captured and re-raised). With a schedule, the monitor is created on first use. Errors captured during the run carry the tag monitor.check_in_id. check_in returns False instead of raising when the check-in fails. Plain @vaka.monitor without a slug still only reports exceptions.

User feedback

Forward what users wrote in your own forms (support, contact, in-app chat). It is sent right away (a blocking call) with the scope's user, tags and flags.

r = vaka.capture_feedback(
    form["message"],
    email=form.get("email"),          # optional contact
    issue="API-12",                   # or event_id=vaka.capture_exception(e)
    ip=request.remote_addr,
    attachments=[("screenshot.png", data)],
)
print(r.short_id)                     # "API-F12"

Keyword arguments: email, name, event_id, issue, user_id, session_id, url, ip, tags, attachments (up to 3 (filename, bytes[, content_type]) PNG, JPEG or WebP images of 5 MB), timeout. It raises vaka.FeedbackError with .status (429: rate limited). In async code call it with await asyncio.to_thread(vaka.capture_feedback, ...).

Link it to a crash with the event id from a capture call, or to an issue by its short id (API-12). Pass the end user's IP address: feedback is rate limited per address (10 an hour by default), so without it all feedback from your server shares one limit. Vaka believes the address only from backends on a private network or listed in VAKA_TRUSTED_PROXIES. Rejected feedback raises an error with the HTTP status; 429 means a limit was hit. See user feedback.

Frameworks

Framework Setup
Django MIDDLEWARE = ["vaka.integrations.django.VakaMiddleware", ...] (first), vaka.init() in settings.py
Flask from vaka.integrations.flask import init_app; init_app(app)
FastAPI, Starlette app.add_middleware(VakaAsgiMiddleware) from vaka.integrations.asgi
Other ASGI apps app = VakaAsgiMiddleware(app)
Other WSGI apps app = VakaWsgiMiddleware(app) from vaka.integrations.wsgi

Each request gets its own scope with the method and URL (no headers, cookies or bodies), the route template as the transaction tag (GET /carts/{cart_id}), and the trace id from an incoming traceparent header, so a backend error links to the browser trace that caused it. Unhandled exceptions are reported with handled: false. Exceptions the framework turns into responses (HTTPException, Http404) are not reported.

Traces and logs (OpenTelemetry)

import vaka, vaka.otel

vaka.init(key="vk_...", endpoint="https://vaka.example.com", release="2.4.0", service="checkout")
vaka.otel.setup()      # traces and logs; setup(logs=False) for traces only

setup() configures a TracerProvider and LoggerProvider with OTLP/HTTP exporters pointed at https://vaka.example.com/ingest/otlp and resource attributes from the Vaka client (service.name, service.version = release, deployment.environment.name), so spans, logs and errors line up per release. Then use any OpenTelemetry instrumentation:

pip install opentelemetry-instrumentation-fastapi opentelemetry-instrumentation-requests
from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor
FastAPIInstrumentor.instrument_app(app)

Already using OpenTelemetry with environment variables or the Collector? Keep that setup (see opentelemetry.md) and use the SDK for errors only.

Feature flags

vaka.load_flags({"plan": "pro"})             # evaluate once for this process
if vaka.is_enabled("new_checkout"): ...
variant = vaka.get_flag("checkout_layout", "control")

On a server, evaluate per person inside the request:

flags = vaka.evaluate_flags(distinct_id=user.id, user_id=user.id, properties={"plan": user.plan})
if flags.get("new_checkout") == "one_page": ...

Every value read with get_flag, is_enabled or Flags.get is recorded on the current scope and sent as flags on errors and events (and on the process session), so flag_health and experiment results can split crash rates and conversions by variant. Flags.peek(key) reads without recording. See flags.md.

Releasing

Maintainers: see releasing/python.md for publishing to PyPI.