vaka
CI statusLatest releaseGitHub

Go SDK

Module github.com/ErikHellman/vaka/sdks/go (source: sdks/go, package vaka). A thin layer on the standard OpenTelemetry Go SDK: Init installs OpenTelemetry tracer and logger providers that export OTLP/HTTP to Vaka (opentelemetry.md), and adds what OpenTelemetry does not do: panic and error capture with stack traces, breadcrumbs, release health sessions, user context, analytics events and feature flags, sent to the ingest API. Go 1.24+.

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

go get github.com/ErikHellman/vaka/sdks/go@latest

Config

Field Default Meaning
Key $VAKA_KEY Ingest key; empty disables the SDK
Endpoint $VAKA_ENDPOINT Server URL
Release $VAKA_RELEASE, then the module version or VCS revision from the build info App version (service.version)
Environment $VAKA_ENVIRONMENT or production deployment.environment.name
ServiceName $OTEL_SERVICE_NAME, then the executable name service.name
DisableTracing / DisableLogs false Don't install the global OpenTelemetry TracerProvider / LoggerProvider (use your own)
TracesSampler parent-based, always on OpenTelemetry sampler
DisableSessions false One session per process for crash-free rates
InAppInclude main module path Package path prefixes that count as your code
FlushInterval 5 s Batch interval
BeforeSend nil Change or drop (return nil) any item
Debug false Log SDK activity to stderr

API

client, err := vaka.Init(cfg)                  // defer client.Shutdown(ctx): ends the session, flushes
defer vaka.Recover()                           // report a panic, mark the session crashed, re-panic

vaka.CaptureError(ctx, err)                    // Unwrap chain, stack, breadcrumbs, trace id from ctx
vaka.CaptureMessage(ctx, "text", vaka.LevelWarning)
vaka.CaptureError(ctx, err, vaka.WithTags(map[string]string{"job": "import"}), vaka.WithFingerprint("import"))

ctx = vaka.WithScope(ctx)                      // per-request scope: user, tags, flags, breadcrumbs
vaka.AddBreadcrumb(ctx, "db", "connected", vaka.LevelInfo)
vaka.SetTag(ctx, "region", "eu-north-1")
vaka.SetUser(ctx, "user-123")                  // opt-in
vaka.Track(ctx, "job_finished", map[string]any{"kind": "import"})

flags, err := vaka.EvaluateFlags(ctx, vaka.FlagRequest{DistinctID: userID, Properties: map[string]any{"plan": "pro"}})
ctx = vaka.WithFlags(ctx, flags)               // exposure: flag values go on errors and events
if flags.Variant("new_checkout", "control") == "one_page" { ... }

vaka.Go(ctx, func(ctx context.Context) { ... }) // goroutine that reports its panic

Without WithScope, these use the client's global scope. Calls on a disabled (no key) or nil client are no-ops.

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.

cfg := &vaka.MonitorConfig{Schedule: vaka.MonitorSchedule{Cron: "0 3 * * *", Timezone: "Europe/Stockholm"}}
err := vaka.WithMonitor(ctx, "nightly-backup", cfg, func(ctx context.Context) error {
	return backup(ctx)
})

_ = vaka.SendCheckIn(ctx, "hourly-sync", vaka.CheckIn{}) // a single ok

WithMonitor reports in_progress, then ok with the duration, or error when fn returns an error (captured, then returned) or panics (reported, then re-panicked). Pass a config to create the monitor on first use, or nil. Errors captured with the ctx passed to fn carry the tag monitor.check_in_id. Check-in failures from WithMonitor go to stderr; SendCheckIn returns them.

User feedback

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

r, err := vaka.CaptureFeedback(r.Context(), vaka.Feedback{
	Message: form.Message,
	Email:   form.Email,         // optional contact
	Issue:   "API-12",           // or EventID: the id CaptureError returned
	IP:      clientIP(r),
	Attachments: []vaka.Attachment{{Filename: "screenshot.png", Data: png}},
})
var fe *vaka.FeedbackError
if errors.As(err, &fe) && fe.StatusCode == 429 { /* rate limited */ }
// r.ShortID == "API-F12"

Fields: Message (required), Email, Name, EventID, Issue, UserID, SessionID, URL, IP, Tags, Attachments (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.

HTTP, logs and traces

Errors the SDK sends itself mark the active span and log record with vaka.error_captured: true, so the server does not create a second error from the OTLP data.

Panics

Go cannot catch panics globally, so add defer vaka.Recover() at the top of main and of each goroutine you start (or start them with vaka.Go). Recover sends synchronously (up to 2 s) and re-panics, so the program still exits the same way. Frames are resolved in-process, crash site first; paths below your module root are sent as repository paths (cart/checkout.go) so source links and suspect commits work. No debug file upload is needed.

See sdks/go/examples/demo for a runnable example.