vaka
CI statusLatest releaseGitHub

Install Vaka in a Go service

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 module

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

Requires Go 1.24 or newer. The package name is vaka; import it as vaka "github.com/ErikHellman/vaka/sdks/go".

2. Initialise at the top of main

import vaka "github.com/ErikHellman/vaka/sdks/go"

func main() {
	client, err := vaka.Init(vaka.Config{
		Key:      "vk_your_ingest_key",
		Endpoint: "https://vaka.example.com",
		Release:  version, // e.g. set with -ldflags "-X main.version=1.4.0"
	})
	if err != nil {
		log.Fatal(err)
	}
	defer client.Shutdown(context.Background())
	defer vaka.Recover()
	// ... the rest of the program
}

Key, Endpoint, Release and Environment fall back to VAKA_KEY, VAKA_ENDPOINT, VAKA_RELEASE and VAKA_ENVIRONMENT, so they can come from the environment instead. Without Release the SDK uses the module version or VCS revision from the build info. With an empty key the SDK is a no-op.

Init installs the global OpenTelemetry TracerProvider, LoggerProvider and W3C propagator. If the service already configures OpenTelemetry, set DisableTracing: true and DisableLogs: true and point the existing exporters at Vaka as in opentelemetry.

3. Wire up HTTP and logging

mux := http.NewServeMux()
mux.HandleFunc("GET /carts/{id}", getCart)
log.Fatal(http.ListenAndServe(":8080", vaka.Middleware(mux)))

slog.SetDefault(slog.New(vaka.SlogHandler(slog.NewTextHandler(os.Stderr, nil))))

httpClient := &http.Client{Transport: vaka.Transport(nil)} // outgoing calls join the trace

If the service uses otelhttp or a framework that already creates server spans, use vaka.MiddlewareWithOptions(h, vaka.MiddlewareOptions{DisableSpans: true}).

Log with the *Context methods (slog.ErrorContext(ctx, ...)) so records join the request.

4. Report errors and events

if err := importCatalog(ctx); err != nil {
	vaka.CaptureError(ctx, err)          // includes the Unwrap chain and the trace id
}
vaka.AddBreadcrumb(ctx, "db", "connected", vaka.LevelInfo)
vaka.SetTag(ctx, "region", "eu-north-1")
vaka.Track(ctx, "job_finished", map[string]any{"kind": "import"})
vaka.SetUser(ctx, "user-123")            // opt-in only

go func() {
	defer vaka.Recover()                 // every goroutine you start
	work()
}()

Feature flags (see flags):

flags, err := vaka.EvaluateFlags(ctx, vaka.FlagRequest{DistinctID: userID})
ctx = vaka.WithFlags(ctx, flags)         // errors and events now carry the flag values
if flags.Enabled("new_checkout") { ... }

5. Verify

VAKA_URL=https://vaka.example.com VAKA_KEY=vk_your_ingest_key vaka send-test-event

Then call vaka.CaptureMessage(ctx, "vaka install test", vaka.LevelInfo) from the app and check vaka issues -p your-project (or the MCP tool list_issues). Events appear within a few seconds; spans show up under list_slow_traces. Set Debug: true in Config to log what the SDK sends.