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.