.NET SDK
NuGet packages (source: sdks/dotnet), for .NET 8 and later:
| Package | What it does |
|---|---|
Vaka |
Core: unhandled exception capture, errors with breadcrumbs, a session per process, analytics events, feature flags, ILogger provider. No dependencies besides Microsoft.Extensions.Logging.Abstractions. |
Vaka.OpenTelemetry |
Points OpenTelemetry .NET traces and logs at Vaka's OTLP/HTTP ingest, with release and environment as resource attributes. |
Vaka.AspNetCore |
builder.AddVaka() for ASP.NET Core and generic-host workers: everything above, plus per-request scopes, request exceptions, and ASP.NET Core + HttpClient tracing. |
Tracing and logs go through the standard OpenTelemetry SDK (opentelemetry.md); the Vaka packages add what OpenTelemetry does not have: crash reporting with grouped issues, breadcrumbs, release health sessions and feature flags.
Agent-followable install guide: /docs/install/dotnet.
ASP.NET Core
dotnet add package Vaka.AspNetCore
var builder = WebApplication.CreateBuilder(args);
builder.AddVaka(); // reads Vaka:Key, Vaka:Endpoint, … or VAKA_* env vars
var app = builder.Build();
appsettings.json (or Vaka__Key / VAKA_KEY environment variables):
{ "Vaka": { "Key": "vk_...", "Endpoint": "https://vaka.example.com" } }
AddVaka initialises the SDK at once (so startup crashes are reported), adds the ILogger
provider, adds the request middleware at the start of the pipeline, sends OpenTelemetry traces
(ASP.NET Core and HttpClient instrumentation) and logs to Vaka, and flushes on shutdown.
VakaAspNetCoreOptions |
Default | Meaning |
|---|---|---|
Sdk |
from config | The VakaOptions below |
Logging.MinimumBreadcrumbLevel |
Information |
Log entries from this level become breadcrumbs |
Logging.MinimumEventLevel |
Error |
Log entries from this level become Vaka errors (None turns it off) |
OpenTelemetry |
true |
Configure OpenTelemetry tracing and logs for Vaka |
ConfigureTracing |
none | Extra tracing setup, e.g. t => t.AddSource("MyApp") |
AutoMiddleware |
true |
Add the request middleware automatically (else call app.UseVaka() first in the pipeline) |
CaptureUser |
false |
Send the authenticated user's id with errors (opt-in) |
CaptureQueryString |
false |
Include the query string in the request URL |
Each request gets its own scope: breadcrumbs from that request only, the URL (without query
string), method and route (GET /carts/{id}) as transaction, and the trace id. Unhandled request
exceptions are reported as handled: false, once, whether or not UseExceptionHandler is used.
Release defaults to the entry assembly's informational version (without the +commit suffix);
environment to the host environment name in lower case.
Other apps (console, workers, desktop)
using Vaka;
using var vaka = VakaSdk.Init(o =>
{
o.Key = "vk_...";
o.Endpoint = "https://vaka.example.com";
o.Release = "2.4.0"; // default: entry assembly version
});
Keep the handle alive until exit: disposing it ends the session and flushes. Generic-host workers
can use builder.AddVaka() from Vaka.AspNetCore instead.
Options (VakaOptions)
| Option | Default | Meaning |
|---|---|---|
Key |
$VAKA_KEY |
Ingest key; empty disables the SDK |
Endpoint |
$VAKA_ENDPOINT |
Server URL |
Release |
$VAKA_RELEASE, else entry assembly version |
App version |
Environment |
$VAKA_ENVIRONMENT, $ASPNETCORE_ENVIRONMENT, $DOTNET_ENVIRONMENT, else production |
|
ServiceName |
$OTEL_SERVICE_NAME, else entry assembly name |
service tag and OpenTelemetry service.name |
CaptureUnhandledExceptions |
true |
AppDomain.UnhandledException → fatal error, session crashed |
CaptureUnobservedTaskExceptions |
true |
TaskScheduler.UnobservedTaskException → error |
AutoSessions |
true |
One session per process, for crash-free rates |
InAppInclude |
empty | Namespace prefixes that are your code, e.g. "MyCompany." |
InAppExclude |
System., Microsoft., common libraries |
Never your code |
MaxBreadcrumbs |
100 | |
FlushInterval |
5 s | Batch interval (errors are sent at once) |
ShutdownTimeout |
2 s | Wait for queued data on exit and crashes |
BeforeSend |
none | Change or drop (null) any item before it is queued |
Debug |
$VAKA_DEBUG set |
Log SDK activity to stderr |
API
VakaSdk.CaptureException(ex); // inner exceptions become the cause chain
VakaSdk.CaptureException(ex, VakaLevel.Warning, configure: s => s.SetTag("job", "import"));
VakaSdk.CaptureMessage("cache rebuilt", VakaLevel.Info);
VakaSdk.AddBreadcrumb("connected", "db", VakaLevel.Info, new Dictionary<string, object?> { ["host"] = "pg1" });
VakaSdk.SetTag("region", "eu-north-1");
VakaSdk.SetUser("user-123"); // opt-in identification
VakaSdk.Track("job_finished", new Dictionary<string, object?> { ["kind"] = "import" });
using (VakaSdk.PushScope()) // child scope, flows with async calls
{
VakaSdk.ConfigureScope(s => { s.Transaction = "nightly import"; s.SetTag("batch", "42"); });
// ...
}
VakaSdk.Flush(TimeSpan.FromSeconds(2));
ILogger: without Vaka.AspNetCore, add logging.AddProvider(new VakaLoggerProvider()).
Information and above become breadcrumbs; Error and Critical become Vaka errors with the logged
exception's stack trace. The same exception is never reported twice (it is marked when captured).
User feedback
Forward what users wrote in your own forms (support, contact, in-app chat). It is sent right away with the current scope's user, URL, tags and flags.
app.MapPost("/support", async (SupportForm form, HttpContext http) =>
{
var r = await VakaSdk.CaptureFeedbackAsync(new VakaFeedback(form.Message)
{
Email = form.Email, // optional contact
Issue = "API-12", // or EventId = VakaSdk.CaptureException(e)
IpAddress = http.Connection.RemoteIpAddress?.ToString(),
Attachments = { new VakaFeedbackAttachment("screenshot.png", png) },
});
return Results.Ok(new { ticket = r.ShortId }); // "API-F12"
});
Properties: Email, Name, EventId, Issue, UserId, SessionId, Url, IpAddress,
Tags, Attachments (up to 3 PNG, JPEG or WebP images of 5 MB). It throws
VakaFeedbackException with StatusCode (429: rate limited).
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.
Feature flags
// Per person (e.g. in a request): evaluates, and records the values on the current scope,
// so errors, events and health split by variant.
var flags = await VakaSdk.EvaluateFlagsAsync(distinctId: visitorId, userId: null,
properties: new Dictionary<string, object?> { ["plan"] = "pro" });
if (flags.GetVariant("new_checkout") == "one_page") { /* ... */ }
// Per process (CLI tools, desktop apps): load once, then read synchronously.
await VakaSdk.LoadFlagsAsync();
if (VakaSdk.IsFlagEnabled("dark_mode")) { /* ... */ }
See flags.md for targeting, rollouts and experiments.
OpenTelemetry without ASP.NET Core
using Vaka.OpenTelemetry;
services.AddOpenTelemetry()
.UseVaka() // resource + OTLP traces and logs to Vaka
.WithTracing(t => t.AddSource("MyApp"));
// or piece by piece:
Sdk.CreateTracerProviderBuilder()
.SetResourceBuilder(ResourceBuilder.CreateDefault().AddVaka())
.AddSource("MyApp")
.AddVakaExporter()
.Build();
The OTLP endpoint is {Endpoint}/ingest/otlp/v1/traces (and /v1/logs) with the x-vaka-key
header. Errors the SDK reports inside an activity carry its trace_id, and the activity gets the
attribute vaka.error_captured = true so the server doesn't create a second error from the
span's exception event; error log records the ILogger provider reported are marked the same way.
Stack traces
Frames come from System.Diagnostics.StackTrace, crash site first, with file and line when the
portable PDB is next to the assembly (the default for dotnet build and dotnet publish; keep
<DebugType>portable</DebugType> or embedded in Release). Async state machine frames are shown
as the method that was written (Cart.LoadAsync, not <LoadAsync>d__4.MoveNext). No debug file
upload is needed.
Releasing the packages
See releasing/dotnet.md.