RuntimeLens 1.0.1

RuntimeLens

Core telemetry engine, storage providers, diagnostic rules evaluator, background system collectors, and trace exporters for RuntimeLens.

Target Frameworks

• .NET Standard 2.0 | .NET 8.0 | .NET 9.0 | .NET 10.0

Options & Configuration Reference

All settings are configured via RuntimeLensOptions:

1. Feature Flags & Child Options

2. Storage Options (options.Storage)

3. Filter Options (options.Filters)

System Infrastructure

• Collectors: MemoryCollector, GcCollector, ThreadPoolCollector, CpuCollector.
• Diagnostic Rules:
  • RL001_SLOW_REQUEST: Triggers when duration exceeds SlowRequestThresholdMs.
  • RL002_HIGH_MEMORY: Triggers when span memory allocation exceeds 10 MB.
  • RL003_HIGH_GC: Triggers when Gen 1 (>2) or Gen 2 (>0) garbage collections occur during span execution.
• Exporters: JsonExportProvider (JSON stream serializer), CsvExportProvider (14-column CSV stream serializer).

Code Examples

1. Engine Setup with File Persistence

using RuntimeLens;
using RuntimeLens.Options;
using RuntimeLens.Storage;

// Initialize global options
var options = new RuntimeLensOptions
{
    EnableSqlTracking = true,       // Track EF Core / SQL queries
    EnableHttpTracking = true,      // Track incoming/outgoing HTTP calls
    EnableMemoryTracking = true,    // Measure memory allocations
    EnableGcTracking = true         // Track GC collections
};

// Configure persistent file storage
options.Storage.Mode = StorageMode.File;                  // Enable file-based persistence
options.Storage.FilePath = "runtimelens-traces.json";     // JSON storage path
options.Storage.MaxSnapshotsInMemory = 10000;              // Buffer capacity
options.Storage.AutoFlushIntervalMs = 2000;                // Flush every 2 seconds

// Configure noise filtering
options.Filters.SlowRequestThresholdMs = 300.0;           // Slow threshold: 300ms
options.Filters.IgnoreNamespace("Microsoft.EntityFrameworkCore"); // Exclude EF internal namespaces
options.Filters.IgnorePath("/healthz");                    // Exclude healthcheck route

// Instantiate storage provider and core engine
var storage = new FileStorageProvider(options);
using var engine = new RuntimeLensEngine(options, storage);

// Record telemetry span manually
using (var scope = engine.StartScope("ProcessBatchJob", category: "Batch"))
{
    scope.AddTag("job.id", "4092");
    await Task.Delay(150); // Simulate work
} // Scope closed, recorded, and queued for persistence

2. Querying Stored Traces (IStorageProvider)

using RuntimeLens.Abstractions;
using RuntimeLens.Abstractions.Models;

public async Task QueryTracesAsync(IStorageProvider storage)
{
    // Execute paginated search query
    PagedQueryResult<TraceSnapshot> result = await storage.QueryTracesAsync(new TraceQueryOptions
    {
        Query = "ProcessBatchJob",  // Search query term
        OnlySlow = true,            // Filter only slow requests
        SlowThresholdMs = 200.0,    // Slow threshold filter
        SortBy = "Duration",        // Sort options: "Date", "Duration", "Memory"
        SortDescending = true,      // Sort order
        Page = 1,                   // Page index
        PageSize = 10               // Page size limit
    });

    // Iterate paginated items
    Console.WriteLine($"Total Matches: {result.TotalCount}, Total Pages: {result.TotalPages}");
    foreach (var trace in result.Items)
    {
        Console.WriteLine($"Trace {trace.TraceId}: {trace.OperationName} took {trace.DurationMs:F2}ms");
    }
}

3. Programmatic Trace Exporting (JSON & CSV)

using RuntimeLens.Abstractions;
using RuntimeLens.Exporters;

public async Task ExportTracesAsync(IStorageProvider storage)
{
    // Fetch top 100 trace snapshots
    IReadOnlyList<TraceSnapshot> traces = await storage.GetTracesAsync(limit: 100);

    // 1. Export snapshots to JSON stream
    var jsonExporter = new JsonExportProvider();
    using (var jsonFile = File.Create("export.json"))
    {
        await jsonExporter.ExportAsync(traces, jsonFile); // Writes formatted JSON array
    }

    // 2. Export snapshots to CSV stream
    var csvExporter = new CsvExportProvider();
    using (var csvFile = File.Create("export.csv"))
    {
        await csvExporter.ExportAsync(traces, csvFile); // Writes 14-column CSV file
    }
}

Learn More

👉 RuntimeLens GitHub Repository