Documentation Index
Fetch the complete documentation index at: https://docs.tracelit.io/llms.txt
Use this file to discover all available pages before exploring further.
Installation
dotnet add package Tracelit
Quick start
Register Tracelit in Program.cs
var builder = WebApplication.CreateBuilder(args);
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;
});
var app = builder.Build();
app.MapGet("/", () => "Hello, Tracelit!");
app.Run();
You're done
The SDK wires up traces, logs, and metrics automatically. No middleware needed.
Configure and start manually
TracelitClient.Configure(config =>
{
config.ApiKey = Environment.GetEnvironmentVariable("TRACELIT_API_KEY");
config.ServiceName = "my-worker";
config.Environment = "production";
});
TracelitClient.Start();
// ... your application code ...
// At application exit
TracelitClient.Shutdown();
Configuration reference
| Option | Env variable | Default | Description |
|---|
ApiKey | TRACELIT_API_KEY | null | Required. Your Tracelit ingest API key |
ServiceName | TRACELIT_SERVICE_NAME | null | Required. Service name shown in Tracelit |
Environment | TRACELIT_ENVIRONMENT | "production" | Deployment environment tag |
Endpoint | TRACELIT_ENDPOINT | https://ingest.tracelit.app | Override only when self-hosting |
SampleRate | TRACELIT_SAMPLE_RATE | 1.0 | Head-based sampling ratio 0.0–1.0. Errors always export. |
Enabled | TRACELIT_ENABLED | true | Set false to disable all telemetry |
ResourceAttributes | — | {} | Extra Dictionary<string, string> on every span, metric, and log |
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",
};
});
Tracing
Manual spans
Use the 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.ToString());
span?.SetTag("payment.currency", currency);
try
{
var result = ProcessPayment(payment);
span?.SetTag("payment.status", result.Status);
return result;
}
catch (Exception ex)
{
span?.RecordException(ex);
span?.SetStatus(Status.Error.WithDescription(ex.Message));
throw;
}
In ASP.NET Core (DI-injected ActivitySource)
public class OrdersController : ControllerBase
{
private static readonly ActivitySource _source = new("OrdersService");
[HttpPost]
public async Task<IActionResult> CreateOrder([FromBody] CreateOrderRequest req)
{
using var activity = _source.StartActivity("create-order");
activity?.SetTag("order.channel", req.Channel);
var order = await _orderService.CreateAsync(req);
activity?.SetTag("order.id", order.Id);
return Created($"/orders/{order.Id}", order);
}
}
Automatic instrumentation
| Library | What is captured |
|---|
| ASP.NET Core | HTTP request traces, request duration/count/error metrics |
| HttpClient | Outbound HTTP call traces |
| SqlClient | SQL query traces |
| .NET runtime | GC, thread pool, lock contention metrics |
Metrics
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 metrics collection
| Metric | Type | Description |
|---|
http.server.request.duration | Histogram | HTTP request duration |
http.server.active_requests | UpDownCounter | In-flight requests |
http.client.request.duration | Histogram | Outbound HTTP duration |
dotnet.gc.* | Various | GC collections, heap size, pause time |
dotnet.thread_pool.* | Various | Thread pool queue length, worker threads |
process.memory.rss | Gauge | Process working set in MB (polled every 60 s) |
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 via trace_id + span_id.
public class OrdersService
{
private readonly ILogger<OrdersService> _logger;
public OrdersService(ILogger<OrdersService> logger)
{
_logger = logger;
}
public async Task<Order> CreateAsync(CreateOrderRequest req)
{
// This log automatically includes trace_id/span_id from the current Activity
_logger.LogInformation("Processing order for {Channel}", req.Channel);
var order = await _repository.InsertAsync(req);
_logger.LogInformation("Order {OrderId} created in {ElapsedMs}ms",
order.Id, sw.ElapsedMilliseconds);
return order;
}
}
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 — no configuration required.
Disabling in tests
// In test setup or appsettings.Testing.json
config.Enabled = false;
// or: TRACELIT_ENABLED=false
GitHub
Source code and issue tracker: github.com/Tracelit-AI/tracelit-dotnet
