vaka
CI statusLatest releaseGitHub

Install Vaka in a .NET application

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. Requires .NET 8 or later.

1. Add the package

ASP.NET Core apps and generic-host workers (Host.CreateApplicationBuilder):

dotnet add package Vaka.AspNetCore

Console, desktop or other apps without a host: dotnet add package Vaka (and Vaka.OpenTelemetry if the app already uses OpenTelemetry).

2. Configure the key and endpoint

Add to appsettings.json (or set VAKA_KEY and VAKA_ENDPOINT environment variables in deployment):

{
  "Vaka": {
    "Key": "vk_your_ingest_key",
    "Endpoint": "https://vaka.example.com"
  }
}

The ingest key is write-only and safe to ship. With no key the SDK does nothing.

3. Initialise at startup

ASP.NET Core or worker (Program.cs), right after the builder is created:

using Vaka.AspNetCore;

var builder = WebApplication.CreateBuilder(args);   // or Host.CreateApplicationBuilder(args)
builder.AddVaka(o => o.Sdk.InAppInclude.Add("MyCompany."));  // your root namespace(s)

Do not also add app.UseVaka(); the middleware is added automatically. If the app already calls builder.Services.AddOpenTelemetry(), either remove its OTLP exporter setup or pass o.OpenTelemetry = false and call .UseVaka() on that OpenTelemetry builder instead (using Vaka.OpenTelemetry;).

Without a host (first line of Main):

using Vaka;

using var vaka = VakaSdk.Init(o =>
{
    o.Key = "vk_your_ingest_key";
    o.Endpoint = "https://vaka.example.com";
    o.InAppInclude.Add("MyCompany.");
});

Keep vaka alive until the program exits: disposing it ends the session and flushes.

4. What you get automatically

5. Report errors, events and flags

using Vaka;

try { await importer.RunAsync(); }
catch (Exception e) { VakaSdk.CaptureException(e); }

VakaSdk.AddBreadcrumb("imported 120 rows", "import");
VakaSdk.SetTag("tenant", tenantId);
VakaSdk.Track("import_finished", new Dictionary<string, object?> { ["rows"] = 120 });
VakaSdk.SetUser(userId);   // opt-in identification only

var flags = await VakaSdk.EvaluateFlagsAsync(distinctId: visitorId);
if (flags.IsEnabled("new_checkout")) { /* ... */ }

Errors logged with logger.LogError(ex, "...") are already reported; don't also call CaptureException for them (it would be deduplicated anyway).

6. Verify

  1. Run the app with VAKA_DEBUG=1 and trigger an error (for example a temporary endpoint that throws). stderr shows [vaka] ingest returned 202.

  2. Check it arrived:

    curl -H "Authorization: Bearer $VAKA_TOKEN" "https://vaka.example.com/api/v1/projects/your-project/issues?since=1h"
    

    or ask an agent with the Vaka MCP server: "list issues in your-project from the last hour". The issue's top frames should be your own code (in_app: true); if not, fix InAppInclude.

  3. Remove the temporary error.