.NET / C# Integration Guide

dotnet add package TraceKit.AspNetCore

dotnet add package TraceKit.Core

using TraceKit.AspNetCore;

var builder = WebApplication.CreateBuilder(args);

// Add TraceKit
builder.Services.AddTracekit(options =>
{
    options.ApiKey = Environment.GetEnvironmentVariable("TRACEKIT_API_KEY");
    options.ServiceName = "my-service";
    options.Environment = "production";
    options.EnableCodeMonitoring = true;
});

var app = builder.Build();

// Use TraceKit middleware
app.UseTracekit();

app.MapGet("/api/users", (TracekitSDK sdk) =>
{
    var counter = sdk.Counter("http.requests.total");
    counter.Inc();

    return Results.Ok(new { message = "Hello" });
});

app.Run();

// Program.cs -- Add HTTP client instrumentation
builder.Services.AddHttpClient("my-api", client => {
    client.BaseAddress = new Uri("https://api.example.com");
}).AddTracekitInstrumentation();

// Or instrument the default HttpClient
builder.Services.AddHttpClient()
    .AddTracekitInstrumentation();

// Now all HttpClient calls create CLIENT spans automatically!

{
  "Tracekit": {
    "Enabled": true,
    "ApiKey": "ctxio_abc123...",
    "ServiceName": "my-api",
    "Environment": "production",
    "Endpoint": "https://app.tracekit.dev",
    "EnableCodeMonitoring": true
  }
}

// Option 1: Builder API
var sdk = TracekitSDK.CreateBuilder()
    .WithApiKey(Environment.GetEnvironmentVariable("TRACEKIT_API_KEY"))
    .WithServiceName("my-dotnet-app")
    .WithEnableCodeMonitoring(true)  // default: true
    .Build();

// Option 2: ASP.NET Core Dependency Injection
builder.Services.AddTracekit(options => {
    options.ApiKey = Environment.GetEnvironmentVariable("TRACEKIT_API_KEY");
    options.ServiceName = "my-dotnet-app";
    options.EnableCodeMonitoring = true;  // default: true
});

app.MapPost("/api/checkout", (CheckoutRequest request, TracekitSDK sdk) =>
{
    // Capture snapshot with variable state
    sdk.CaptureSnapshot("checkout-start", new()
    {
        ["userId"] = request.UserId,
        ["amount"] = request.Amount,
        ["status"] = "processing"
    });

    // Your business logic here
    var result = ProcessCheckout(request);

    return Results.Ok(result);
});

sdk.CaptureSnapshot("order-checkout", new Dictionary<string, object>
{
    ["orderId"] = order.Id,
    ["total"] = order.Total,
    ["items"] = order.Items.Count,
    ["customer"] = customer.Email,
});

app.MapGet("/api/products/{id}", async (int id, TracekitSDK sdk) =>
{
    using var span = sdk.StartSpan("fetch-product", new()
    {
        ["product.id"] = id
    });

    try
    {
        var product = await GetProductFromDatabase(id);
        span.SetAttribute("product.price", product.Price);
        return Results.Ok(product);
    }
    catch (Exception ex)
    {
        span.RecordException(ex);
        span.SetStatus("error");
        throw;
    }
});

// Option 1: using statement (recommended)
using var sdk = TracekitSDK.Create(config);
// SDK disposes automatically at end of scope

// Option 2: manual disposal
var sdk = TracekitSDK.Create(config);
// ... use sdk
sdk.Dispose(); // Flushes and shuts down

// Option 3: ASP.NET Core (handled by DI container)
// No manual disposal needed -- the DI container
// calls Dispose() when the application shuts down

using TraceKit.Core.LLM;

// Create HttpClient with TraceKit LLM handler
var handler = new LlmDelegatingHandler(new HttpClientHandler());
var httpClient = new HttpClient(handler);

// Use with OpenAI SDK
var openaiClient = new OpenAIClient(
    new ApiKeyCredential(Environment.GetEnvironmentVariable("OPENAI_API_KEY")),
    new OpenAIClientOptions { Transport = new HttpClientPipelineTransport(httpClient) }
);

using TraceKit.Core.LLM;
using Azure.AI.OpenAI;

// Create Azure OpenAI client with TraceKit policy
var client = new AzureOpenAIClient(
    new Uri("https://your-resource.openai.azure.com"),
    new AzureKeyCredential(Environment.GetEnvironmentVariable("AZURE_OPENAI_API_KEY")),
    new AzureOpenAIClientOptions()
);

// Add TraceKit instrumentation
AzureOpenAiInstrumentation.Instrument(client);

var handler = new LlmDelegatingHandler(new LlmConfig
{
    CaptureContent = false,  // Capture prompts/completions (off by default)
    OpenAi = true,           // OpenAI instrumentation
    Anthropic = true,        // Anthropic instrumentation
}, new HttpClientHandler());

TRACEKIT_API_KEY=ctxio_your_generated_api_key_here
TRACEKIT_ENDPOINT=https://app.tracekit.dev
TRACEKIT_SERVICE_NAME=my-dotnet-app
TRACEKIT_ENVIRONMENT=production
TRACEKIT_CODE_MONITORING_ENABLED=true

using TraceKit.AspNetCore;

var builder = WebApplication.CreateBuilder(args);

// Add TraceKit
builder.Services.AddTracekit(options =>
{
    options.ApiKey = Environment.GetEnvironmentVariable("TRACEKIT_API_KEY");
    options.ServiceName = "express-api";
    options.Environment = "production";
    options.Endpoint = "https://app.tracekit.dev";
    options.EnableCodeMonitoring = true;
});

var app = builder.Build();
app.UseTracekit();

// Routes - automatically traced!
app.MapGet("/api/users", (TracekitSDK sdk) =>
{
    var users = new[]
    {
        new { Id = "1", Name = "Alice", Email = "alice@example.com" },
        new { Id = "2", Name = "Bob", Email = "bob@example.com" }
    };
    return Results.Ok(users);
});

// Manual span example
app.MapPost("/api/users", async (UserRequest request, TracekitSDK sdk) =>
{
    using var span = sdk.StartSpan("create-user", new()
    {
        ["user.email"] = request.Email
    });

    try
    {
        // Simulate user creation
        var user = new
        {
            Id = Guid.NewGuid().ToString(),
            Name = request.Name,
            Email = request.Email
        };

        // Simulate async operation
        await Task.Delay(100);

        span.SetAttribute("user.id", user.Id);
        return Results.Created($"/api/users/{user.Id}", user);
    }
    catch (Exception ex)
    {
        span.RecordException(ex);
        span.SetStatus("error");
        return Results.Problem("Failed to create user");
    }
});

app.Run();

record UserRequest(string Name, string Email);
record CheckoutRequest(string UserId, decimal Amount);

var sdk = TracekitSDK.Create(config);

// Create a counter with optional tags
var counter = sdk.Counter("http.requests.total",
    new() { ["service"] = "api" });

// Increment by 1
counter.Inc();

// Add a specific value
counter.Add(5);

// Create a gauge
var gauge = sdk.Gauge("http.connections.active");

// Set to specific value
gauge.Set(42);

// Increment/decrement
gauge.Inc();
gauge.Dec();

// Create a histogram with tags
var histogram = sdk.Histogram("http.request.duration",
    new() { ["unit"] = "ms" });

// Record values
histogram.Record(45.2);
histogram.Record(123.5);

using OpenTelemetry;
using OpenTelemetry.Trace;
using OpenTelemetry.Resources;
using OpenTelemetry.Exporter;

builder.Services.AddOpenTelemetry()
    .ConfigureResource(r => r.AddService("my-service"))
    .WithTracing(tracing => tracing
        .AddAspNetCoreInstrumentation()
        .AddHttpClientInstrumentation()
        .AddOtlpExporter(opt => {
            opt.Endpoint = new Uri("https://api.tracekit.io");
            opt.Headers = "Authorization=Bearer " + apiKey;
        }));

using Tracekit.AspNetCore;

builder.Services.AddTracekit(options => {
    options.ApiKey = builder.Configuration["TRACEKIT_API_KEY"];
    options.ServiceName = "my-service";
});

var app = builder.Build();
app.UseTracekit();