RuntimeLens 1.0.0

RuntimeLens

RuntimeLens is a high-performance runtime diagnostics and observability platform for .NET applications. It helps developers understand application behavior, track execution bottlenecks, inspect memory allocations, analyze GC spikes, and troubleshoot production issues — all with zero application downtime and minimal configuration.

Why RuntimeLens?

NuGet Packages

Quick Start

Installation

# Core Telemetry & ASP.NET Core Integration
dotnet add package RuntimeLens.AspNetCore

# Embedded Web Dashboard
dotnet add package RuntimeLens.Dashboard

Minimal API Setup (Program.cs)

using RuntimeLens.AspNetCore.Extensions;
using RuntimeLens.Dashboard.Extensions;
using RuntimeLens.Options;

var builder = WebApplication.CreateBuilder(args);

// 1. Register RuntimeLens core telemetry & storage
builder.Services.AddRuntimeLens(options =>
{
    options.EnableDashboard = true;
    options.EnableSqlTracking = true;
    options.EnableHttpTracking = true;
    options.EnableMemoryTracking = true;
    options.EnableGcTracking = true;

    // Storage: InMemory (default) or File (survives restarts)
    options.Storage.Mode = StorageMode.File;
    options.Storage.FilePath = "runtimelens-traces.json";
    options.Storage.MaxSnapshotsInMemory = 5000;

    options.Sampling.Rate = 1.0;                   // 100% sampling
    options.Filters.SlowRequestThresholdMs = 500;   // Slow request alert threshold
    options.Filters.TrackDashboardRequests = false;  // Exclude self-profiling
    options.Filters.IgnoreNamespace("Microsoft");    // Exclude framework namespaces
});

// 2. Register RuntimeLens Dashboard UI
builder.Services.AddRuntimeLensDashboard(options =>
{
    options.RoutePrefix = "/runtimelens";   // Dashboard URL path
    options.DefaultLanguage = "en";         // "tr" for Turkish, "en" for English
    options.DefaultTheme = "dark";          // "dark" or "light"
    options.UseUtcTimestamp = true;          // UTC or local browser time

    // Scoped Basic Authentication (applies ONLY to /runtimelens endpoints)
    options.Authentication.Enabled = false;
    options.Authentication.Username = "admin";
    options.Authentication.Password = "SecretPassword123!";
});

var app = builder.Build();

app.UseRouting();
app.UseRuntimeLens();              // Enable telemetry middleware
app.UseRuntimeLensDashboard();     // Enable dashboard endpoints

app.MapGet("/api/order/{id}", async (int id, IRuntimeLens runtimeLens) =>
{
    using var scope = runtimeLens.StartScope("ProcessOrder", "BusinessLogic");
    scope.AddTag("order.id", id.ToString());

    await Task.Delay(50); // Simulate work
    return Results.Ok(new { OrderId = id, Status = "Processed" });
});

app.Run();

After starting the application, navigate to http://localhost:5000/runtimelens to open the dashboard.

Declarative Method Profiling

Decorate controller actions or services with [ProfileMethod] to automatically profile execution time, memory allocations, and exceptions:

using Microsoft.AspNetCore.Mvc;
using RuntimeLens.AspNetCore.Filters;

[ApiController]
[Route("api/[controller]")]
public class OrdersController : ControllerBase
{
    [HttpGet("{id}")]
    [ProfileMethod("GetOrderById", "API")]
    public IActionResult GetOrder(int id)
    {
        return Ok(new { Id = id, Amount = 250.00 });
    }
}

Manual Profiling & Custom Tags

Add manual spans, custom key-value tags, and metrics anywhere in your codebase:

public class PaymentService
{
    private readonly IRuntimeLens _runtimeLens;

    public PaymentService(IRuntimeLens runtimeLens)
    {
        _runtimeLens = runtimeLens;
    }

    public async Task ProcessPaymentAsync(string orderId, decimal amount)
    {
        using var scope = _runtimeLens.StartScope("ProcessPayment", "PaymentGateway");

        // Tags are rendered as interactive badges in the dashboard
        scope.AddTag("payment.order_id", orderId);
        scope.AddTag("payment.amount", amount.ToString("C"));
        scope.AddTag("gateway.provider", "Stripe");

        // Record custom metrics
        scope.RecordMetric("payment_amount", (double)amount, "USD");

        try
        {
            await Task.Delay(100); // Simulate API call
        }
        catch (Exception ex)
        {
            _runtimeLens.TrackException(ex);
            throw;
        }
    }
}

Automatic Noise Filtering

RuntimeLens includes a built-in 3-tier noise filter (NoiseFilter) that automatically excludes irrelevant requests from trace collection:

Noise filtering is applied at the middleware level (incoming HTTP), the DiagnosticSource listener (outgoing HTTP), and the file storage provider (persistence load).

Diagnostic Alert Rules

RuntimeLens ships with three built-in diagnostic alert rules that evaluate every captured trace:

Alerts are automatically deduplicated by TraceId + RuleName to prevent parent-child span double counting.

Configuration Reference

RuntimeLensOptions

SamplingOptions

StorageOptions

FilterOptions

DashboardOptions

DashboardAuthenticationOptions

Plugin Extensibility

Implement the IPlugin interface to hook into the trace processing lifecycle:

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

public class SlackAlertPlugin : IPlugin
{
    public string Name => "SlackAlertPlugin";

    public ValueTask InitializeAsync(IRuntimeLens runtimeLens, CancellationToken ct = default)
    {
        // Setup logic
        return ValueTask.CompletedTask;
    }

    public async ValueTask OnTraceCapturedAsync(TraceSnapshot snapshot, CancellationToken ct = default)
    {
        if (snapshot.DurationMs > 2000)
        {
            // Send Slack notification for very slow requests
            await SendSlackMessageAsync($"⚠️ Slow request: {snapshot.OperationName} ({snapshot.DurationMs:F0}ms)");
        }
    }
}

Dashboard Features

The embedded dashboard provides a rich diagnostic experience:

• Overview Cards — Total traces, average latency, active alerts, memory allocation summary
• Trace Table — Server-side paged query API (10, 25, 50, 100 per page) with sorting (Date, Duration, Memory)
• Slow Query Filter — 🐢 Slow Only toggle for filtering slow operations
• Auto-Refresh — Configurable polling intervals (5s, 10s, 30s, 60s)
• Trace Detail Modal — Call tree hierarchy, flame graph, tags/metadata badges, thread info, exception details
• Alert Modal — Deduplicated alerts with severity indicators and View Trace → navigation links
• Global Search — Instant filtering by operation name, trace ID, category, tag keys/values, or exception messages
• Dark/Light Theme — User-toggleable theme with smooth transitions
• JSON & CSV Export — One-click download of all captured traces

REST API Endpoints

All endpoints are relative to the configured RoutePrefix (default: /runtimelens):

Trace Query Parameters

License

This project is licensed under the MIT License.