Tracelit 0.1.8

Tracelit .NET SDK

Official .NET SDK for Tracelit — drop-in OpenTelemetry instrumentation for ASP.NET Core and .NET worker apps. Sends traces, metrics, and logs to the Tracelit ingest API via OTLP/HTTP.

Requirements: .NET 8+

Installation

dotnet add package Tracelit

Setup

ASP.NET Core (recommended)

In Program.cs:

builder.Services.AddTracelit(config =>
{
    config.ApiKey      = Environment.GetEnvironmentVariable("TRACELIT_API_KEY");
    config.ServiceName = "payments-api";
    config.Environment = Environment.GetEnvironmentVariable("ASPNETCORE_ENVIRONMENT") ?? "production";
    config.SampleRate  = 1.0;
});

That is all. The SDK wires up traces, logs, and metrics automatically.

Console / Worker apps (non-DI)

TracelitClient.Configure(config =>
{
    config.ApiKey      = Environment.GetEnvironmentVariable("TRACELIT_API_KEY");
    config.ServiceName = "my-worker";
    config.Environment = "production";
});
TracelitClient.Start();

// At application exit
TracelitClient.Shutdown();

Configuration reference

Custom resource attributes

builder.Services.AddTracelit(config =>
{
    config.ApiKey      = Environment.GetEnvironmentVariable("TRACELIT_API_KEY");
    config.ServiceName = "orders-api";
    config.ResourceAttributes = new()
    {
        ["deployment.region"] = "us-east-1",
        ["team"]              = "platform",
    };
});

Manual trace instrumentation

ASP.NET Core (DI)

Inject System.Diagnostics.ActivitySource via the service name or use the static façade:

// Static façade (works in both DI and non-DI apps after Start() is called)
using var span = TracelitClient.Tracer.StartActiveSpan("process_payment");
span?.SetTag("payment.id", payment.Id.ToString());
span?.SetTag("payment.amount", amount);

var result = ProcessPayment(payment);

span?.SetTag("payment.status", result.Status);

Manual metrics instrumentation

Counter

var counter = TracelitClient.Metrics.Counter(
    "orders.placed",
    description: "Total orders placed",
    unit: "{orders}");

counter.Add(1,
    new KeyValuePair<string, object?>("currency", "USD"),
    new KeyValuePair<string, object?>("channel", "web"));

Histogram

var histogram = TracelitClient.Metrics.Histogram(
    "external.api.duration",
    description: "External API call duration",
    unit: "ms");

var sw = Stopwatch.StartNew();
await CallExternalApiAsync();
histogram.Record(sw.Elapsed.TotalMilliseconds,
    new KeyValuePair<string, object?>("service", "stripe"));

Gauge

var gauge = TracelitClient.Metrics.Gauge(
    "job_queue.depth",
    () => (double)JobQueue.PendingCount,
    description: "Number of pending background jobs",
    unit: "{jobs}");

Automatic instrumentation

The SDK instruments the following automatically with no code changes:

Automatic metrics collection

Log forwarding

When using AddTracelit(), all ILogger output is forwarded to the Tracelit logs table via OTLP. Log records are automatically correlated to the active span (trace_id + span_id).

// This log automatically includes trace_id/span_id from the current activity
_logger.LogInformation("Order {OrderId} processed in {ElapsedMs}ms", orderId, elapsed);

Sampling and error guarantee

config.SampleRate = 0.1; // keep 10% of traces

Error spans are always exported, even when the parent trace falls outside the sample ratio. The SDK uses a custom ErrorAlwaysOnSampler + ErrorSpanProcessor pair to guarantee this with no extra configuration.

Disabling in tests

// In test setup or appsettings.Testing.json
config.Enabled = false;
// or: TRACELIT_ENABLED=false

Changelog

See the release history on the Tracelit docs.