RuntimeLens.Abstractions 1.0.1

RuntimeLens.Abstractions

Light-weight contracts, interfaces, and data models for RuntimeLens diagnostics platform. Zero external dependencies.

Target Frameworks

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

Core Interfaces

Data Models

TraceSnapshot

Code Examples

1. Manual Span Profiling

using RuntimeLens.Abstractions;

public class OrderService
{
    private readonly IRuntimeLens _lens;

    public OrderService(IRuntimeLens lens)
    {
        _lens = lens; // Inject telemetry engine
    }

    public async Task ProcessOrderAsync(string orderId, decimal amount)
    {
        // Start root trace scope (automatically tracks duration & memory allocations)
        using var rootSpan = _lens.StartScope("ProcessOrder", category: "Orders");
        
        // Attach diagnostic tags and metrics to the root scope
        rootSpan.AddTag("order.id", orderId);
        rootSpan.RecordMetric("order.amount", (double)amount, unit: "TRY");

        try
        {
            // Start nested child span scope
            using (var dbSpan = _lens.StartScope("SaveToDatabase", category: "Database"))
            {
                dbSpan.AddTag("db.statement", "INSERT INTO Orders ...");
                await Task.Delay(30); // Simulate database operation
            } // Child span disposed & recorded
        }
        catch (Exception ex)
        {
            // Track exception details on root span
            rootSpan.TrackException(ex);
            throw;
        }
    } // Root span disposed, completed & flushed
}

2. Custom Extensibility Plugin (IPlugin)

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

public class HighLatencyAlertPlugin : IPlugin
{
    // Unique identifier for the plugin
    public string Name => "HighLatencyAlertPlugin";

    // Called once when the plugin is registered with the engine
    public ValueTask InitializeAsync(IRuntimeLens runtimeLens, CancellationToken cancellationToken = default)
    {
        // Perform initialization if needed
        return ValueTask.CompletedTask;
    }

    // Executed asynchronously whenever a trace snapshot is captured
    public ValueTask OnTraceCapturedAsync(TraceSnapshot snapshot, CancellationToken cancellationToken = default)
    {
        // Check if operation execution exceeded 1000ms threshold
        if (snapshot.DurationMs > 1000.0)
        {
            // Trigger external notification or logging
            Console.WriteLine($"[ALERT] Slow Operation: {snapshot.OperationName} ({snapshot.DurationMs:F2}ms)");
        }

        return ValueTask.CompletedTask;
    }
}

3. Custom Diagnostic Rule (IDiagnosticRule & IAlertRule)

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

public class MemorySpikeRule : IDiagnosticRule, IAlertRule
{
    public string RuleId => "RL101_MEMORY_SPIKE";
    public string Name => "Memory Spike Rule";

    // Evaluates trace snapshot for diagnostic warnings
    public bool Evaluate(TraceSnapshot snapshot, out string reason)
    {
        const long thresholdBytes = 10 * 1024 * 1024; // 10 MB threshold
        if (snapshot.MemoryAllocatedBytes > thresholdBytes)
        {
            reason = $"[{snapshot.OperationName}] Memory allocation ({snapshot.MemoryAllocatedBytes / 1024 / 1024} MB) exceeded 10 MB threshold.";
            return true;
        }

        reason = string.Empty;
        return false;
    }

    // Evaluates trace snapshot and constructs alert object
    public bool Evaluate(TraceSnapshot snapshot, out DiagnosticAlert? alert)
    {
        if (Evaluate(snapshot, out string reason))
        {
            alert = new DiagnosticAlert
            {
                RuleName = Name,
                Message = reason,
                Severity = AlertSeverity.Warning, // Severity levels: Info, Warning, Critical
                TraceId = snapshot.TraceId
            };
            return true;
        }

        alert = null;
        return false;
    }
}

Learn More

👉 RuntimeLens GitHub Repository