vaka
CI statusLatest releaseGitHub

JVM SDK (Java, Kotlin, Scala)

Module: sdks/jvm (library se.hellsoft.vaka:vaka-jvm, Java 11+). Step-by-step setup: install/jvm.md. For Android apps use the Android SDK instead.

The SDK is a thin layer on the standard OpenTelemetry Java SDK: traces and logs go to Vaka's OTLP endpoint, and the SDK adds what OpenTelemetry has no model for: uncaught exception capture, breadcrumbs, release-health sessions, user and tag context, and feature flags. It depends only on OpenTelemetry (with the JDK HttpClient sender, so no OkHttp or Kotlin runtime).

API

Vaka.init(VakaOptions.builder()
    .key("vk_...")                          // or $VAKA_KEY
    .endpoint("https://vaka.example.com")   // or $VAKA_ENDPOINT
    .release("2.4.0")                       // or $VAKA_RELEASE
    .environment("production")              // or $VAKA_ENVIRONMENT
    .serviceName("checkout")                // or $VAKA_SERVICE / $OTEL_SERVICE_NAME
    .inAppPackages("com.example")
    .build());

Vaka.captureException(e);                         // handled exception with cause chain; returns the event id
Vaka.captureMessage("cache rebuilt", Level.INFO);
Vaka.addBreadcrumb("db", "connected");            // or (category, message, level, data)
Vaka.setTag("region", "eu-north-1");              // null removes it
Vaka.setUser("user-123");                         // opt-in; also sets enduser.id on the current span
Vaka.track("job_finished", Map.of("kind", "import"));
Flags flags = Vaka.flags(FlagRequest.forUser("user-123").property("plan", "pro"));
Tracer tracer = Vaka.openTelemetry().getTracer("checkout");
Vaka.flush(Duration.ofSeconds(2));
Vaka.close();                                     // also done by a shutdown hook

All methods are no-ops before init, or when the key or endpoint is empty, and safe from any thread. Kotlin uses the same calls (Vaka.track("signup", mapOf("plan" to "pro"))).

VakaOptions

Builder method Default
key, endpoint $VAKA_KEY, $VAKA_ENDPOINT empty disables the SDK; system properties vaka.key, vaka.endpoint work too
release $VAKA_RELEASE becomes service.version; release health and regressions are per release
environment $VAKA_ENVIRONMENT or production becomes deployment.environment.name
serviceName $VAKA_SERVICE or $OTEL_SERVICE_NAME service.name, and the service tag on errors
inAppPackages none your packages; without them everything except JDK, Kotlin, Spring, Netty, Jetty, Apache, Jackson, OpenTelemetry and similar library frames is in_app
tag(k, v) none tags on every error
captureUncaughtExceptions true default uncaught exception handler, chained to the previous one
sessions true one session per process run, for crash-free rates
openTelemetry true create an OpenTelemetry SDK exporting to Vaka (see below)
registerGlobalOpenTelemetry true register it as GlobalOpenTelemetry
tracesSampleRate 1.0 share of new traces recorded (parent-based)
flushInterval 5 s how often errors, events and sessions are sent
maxQueueSize 1000 items kept while the server is unreachable; oldest dropped
flagsCacheTtl 30 s evaluated flags are reused per identity for this long
shutdownHook true close (end session, flush) on JVM shutdown
debug false log SDK activity to stderr

User feedback

Forward what users wrote in your own forms (support, contact, in-app chat). The call blocks until the server answers and carries the current scope's user, tags and flags.

try {
    FeedbackResult r = Vaka.captureFeedback(Feedback.of(form.message())
        .email(form.email())            // optional contact
        .issue("API-12")                // or .eventId(Vaka.captureException(e))
        .ip(request.getRemoteAddr())
        .attachment("screenshot.png", png));
    return r.shortId;                   // "API-F12"
} catch (FeedbackException e) {
    if (e.status() == 429) { /* rate limited */ }
}

Builder methods: email, name, eventId, issue, userId, sessionId, url, ip, tag, attachment (up to 3 PNG, JPEG or WebP images of 5 MB).

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.

Scopes: users, tags and breadcrumbs per request

There is one global scope. A server should give each request its own VakaScope; it lives on the OpenTelemetry Context, so it follows the request wherever the context is propagated (instrumented executors, Context.taskWrapping, Kotlin coroutines with asContextElement()):

try (Scope ignored = VakaScope.create().setUser(userId).setTag("route", "/carts").makeCurrent()) {
    Vaka.addBreadcrumb("http", "GET /carts/42");
    handle(request);                 // errors here carry this user, tag and breadcrumb
}

Errors carry the global scope merged with the current one (the current scope's values win, and breadcrumbs from both are combined in time order, at most 100).

OpenTelemetry

By default init builds an OpenTelemetrySdk with:

Use it through Vaka.openTelemetry() or GlobalOpenTelemetry, and add any OpenTelemetry instrumentation library on top of it. Errors captured while a span is active carry its trace_id, so they show up on the trace, and the span gets vaka.error_captured: true so the server does not make a second error out of the span's exception event.

Already using OpenTelemetry? With the Java agent, set .openTelemetry(false) and point the agent at Vaka with the environment variables in opentelemetry.md. With your own SDK (Spring Boot, Quarkus, manual), set .openTelemetry(false) and add Vaka's pieces:

SdkTracerProvider.builder()
    .setResource(Resource.getDefault().merge(VakaOpenTelemetry.resource(options)))
    .addSpanProcessor(VakaOpenTelemetry.spanProcessor())
    .addSpanProcessor(BatchSpanProcessor.builder(VakaOpenTelemetry.spanExporter(options)).build());
// and VakaOpenTelemetry.logRecordExporter(options) for logs

Logging

Feature flags

Flags flags = Vaka.flags(FlagRequest.forUser(userId).property("plan", account.plan()));
if (flags.isEnabled("dark_mode")) { ... }
String variant = flags.variant("new_checkout", "control");

flags calls POST /ingest/v1/flags (blocking, 5 s timeout) and caches the result per identity for flagsCacheTtl. It never throws: on failure isLoaded() is false and every flag is off. Reading a flag records the value on the current scope, so errors and events in the same request carry flags and flag health and experiments can split crash rates and conversions by variant.

Behaviour

See sdks/jvm/sample for a runnable example (VAKA_KEY=... VAKA_ENDPOINT=... ./gradlew :sample:run).