git.stella-ops.org/src/Signals/__Libraries/StellaOps.Signals.Ebpf/Schema/RuntimeCallEvent.cs

// <copyright file="RuntimeCallEvent.cs" company="StellaOps">
// SPDX-License-Identifier: AGPL-3.0-or-later
// </copyright>

namespace StellaOps.Signals.Ebpf.Schema;

using System.Text.Json.Serialization;

/// <summary>
/// Event emitted when a function call is observed via eBPF.
/// </summary>
/// <remarks>
/// This record is the deserialized form of events from the eBPF ring buffer.
/// The schema is designed for efficient serialization and deterministic ordering.
/// </remarks>
public sealed record RuntimeCallEvent
{
    /// <summary>
    /// Unique event identifier.
    /// </summary>
    public required Guid EventId { get; init; }

    /// <summary>
    /// Container ID where the call was observed.
    /// </summary>
    public required string ContainerId { get; init; }

    /// <summary>
    /// Process ID within the container.
    /// </summary>
    public required int Pid { get; init; }

    /// <summary>
    /// Thread ID.
    /// </summary>
    public required int Tid { get; init; }

    /// <summary>
    /// Timestamp in nanoseconds since boot.
    /// </summary>
    public required ulong TimestampNs { get; init; }

    /// <summary>
    /// Called function symbol name (if resolved).
    /// </summary>
    public string? Symbol { get; init; }

    /// <summary>
    /// Called function address.
    /// </summary>
    public required ulong FunctionAddress { get; init; }

    /// <summary>
    /// Call stack (addresses from bottom to top).
    /// </summary>
    public required IReadOnlyList<ulong> StackTrace { get; init; }

    /// <summary>
    /// Runtime type (native, jvm, node, python, dotnet, go).
    /// </summary>
    public required RuntimeType RuntimeType { get; init; }

    /// <summary>
    /// Library/module containing the function.
    /// </summary>
    public string? Library { get; init; }

    /// <summary>
    /// Package URL if resolvable.
    /// </summary>
    public string? Purl { get; init; }

    /// <summary>
    /// UTC timestamp when this event was received by the collector.
    /// </summary>
    public DateTimeOffset ReceivedAt { get; init; } = DateTimeOffset.UtcNow;
}

/// <summary>
/// Runtime type detected from process characteristics.
/// </summary>
[JsonConverter(typeof(JsonStringEnumConverter))]
public enum RuntimeType
{
    /// <summary>Native binary (ELF/PE/Mach-O).</summary>
    Native = 0,

    /// <summary>Java Virtual Machine.</summary>
    Jvm = 1,

    /// <summary>Node.js / V8.</summary>
    Node = 2,

    /// <summary>Python interpreter.</summary>
    Python = 3,

    /// <summary>.NET runtime (CoreCLR).</summary>
    DotNet = 4,

    /// <summary>Go runtime.</summary>
    Go = 5,

    /// <summary>Ruby interpreter.</summary>
    Ruby = 6,

    /// <summary>Unknown or unidentified runtime.</summary>
    Unknown = 255,
}

/// <summary>
/// Observed call path from runtime signals.
/// </summary>
public sealed record ObservedCallPath
{
    /// <summary>
    /// Symbols in the call path (entry point to vulnerable function).
    /// </summary>
    public required IReadOnlyList<string> Symbols { get; init; }

    /// <summary>
    /// Number of times this path was observed.
    /// </summary>
    public required int ObservationCount { get; init; }

    /// <summary>
    /// Package URL if resolvable.
    /// </summary>
    public string? Purl { get; init; }

    /// <summary>
    /// Runtime type where this path was observed.
    /// </summary>
    public RuntimeType RuntimeType { get; init; } = RuntimeType.Unknown;

    /// <summary>
    /// First observation timestamp.
    /// </summary>
    public DateTimeOffset FirstObservedAt { get; init; }

    /// <summary>
    /// Last observation timestamp.
    /// </summary>
    public DateTimeOffset LastObservedAt { get; init; }
}

/// <summary>
/// Summary of runtime signals collected for a container.
/// </summary>
public sealed record RuntimeSignalSummary
{
    /// <summary>
    /// Container ID.
    /// </summary>
    public required string ContainerId { get; init; }

    /// <summary>
    /// When signal collection started.
    /// </summary>
    public required DateTimeOffset StartedAt { get; init; }

    /// <summary>
    /// When signal collection stopped.
    /// </summary>
    public required DateTimeOffset StoppedAt { get; init; }

    /// <summary>
    /// Total events captured.
    /// </summary>
    public required long TotalEvents { get; init; }

    /// <summary>
    /// Aggregated call paths.
    /// </summary>
    public required IReadOnlyList<ObservedCallPath> CallPaths { get; init; }

    /// <summary>
    /// Unique symbols observed.
    /// </summary>
    public required IReadOnlyList<string> ObservedSymbols { get; init; }

    /// <summary>
    /// Events that were dropped due to rate limiting.
    /// </summary>
    public long DroppedEvents { get; init; }

    /// <summary>
    /// Runtime types detected in this container.
    /// </summary>
    public IReadOnlyList<RuntimeType> DetectedRuntimes { get; init; } = [];
}

/// <summary>
/// Statistics about signal collection.
/// </summary>
public sealed record SignalStatistics
{
    /// <summary>
    /// Total events received.
    /// </summary>
    public required long TotalEvents { get; init; }

    /// <summary>
    /// Events per second (current rate).
    /// </summary>
    public required double EventsPerSecond { get; init; }

    /// <summary>
    /// Unique call paths observed.
    /// </summary>
    public required int UniqueCallPaths { get; init; }

    /// <summary>
    /// Ring buffer utilization percentage.
    /// </summary>
    public required double BufferUtilization { get; init; }

    /// <summary>
    /// Events dropped due to rate limiting.
    /// </summary>
    public required long DroppedEvents { get; init; }

    /// <summary>
    /// CPU overhead percentage from eBPF probes.
    /// </summary>
    public double CpuOverheadPercent { get; init; }

    /// <summary>
    /// Memory usage in bytes for signal collection.
    /// </summary>
    public long MemoryUsageBytes { get; init; }
}