up

src/Policy/StellaOps.Policy.Engine/Telemetry/PolicyTimelineEvents.cs

@@ -0,0 +1,471 @@
+using System.Diagnostics;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using Microsoft.Extensions.Logging;
+
+namespace StellaOps.Policy.Engine.Telemetry;
+
+/// <summary>
+/// Provides structured timeline events for policy evaluation and decision flows.
+/// Events are emitted as structured logs with correlation to traces.
+/// </summary>
+public sealed class PolicyTimelineEvents
+{
+    private readonly ILogger<PolicyTimelineEvents> _logger;
+    private readonly TimeProvider _timeProvider;
+
+    public PolicyTimelineEvents(ILogger<PolicyTimelineEvents> logger, TimeProvider timeProvider)
+    {
+        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
+        _timeProvider = timeProvider ?? throw new ArgumentNullException(nameof(timeProvider));
+    }
+
+    #region Evaluation Flow Events
+
+    /// <summary>
+    /// Emits an event when a policy evaluation run starts.
+    /// </summary>
+    public void EmitRunStarted(string runId, string tenant, string policyId, string policyVersion, string mode)
+    {
+        var evt = new TimelineEvent
+        {
+            EventType = TimelineEventType.RunStarted,
+            Timestamp = _timeProvider.GetUtcNow(),
+            RunId = runId,
+            Tenant = tenant,
+            PolicyId = policyId,
+            PolicyVersion = policyVersion,
+            TraceId = Activity.Current?.TraceId.ToString(),
+            SpanId = Activity.Current?.SpanId.ToString(),
+            Data = new Dictionary<string, object?>
+            {
+                ["mode"] = mode,
+            },
+        };
+
+        LogTimelineEvent(evt);
+    }
+
+    /// <summary>
+    /// Emits an event when a policy evaluation run completes.
+    /// </summary>
+    public void EmitRunCompleted(
+        string runId,
+        string tenant,
+        string policyId,
+        string outcome,
+        double durationSeconds,
+        int findingsCount,
+        string? determinismHash = null)
+    {
+        var evt = new TimelineEvent
+        {
+            EventType = TimelineEventType.RunCompleted,
+            Timestamp = _timeProvider.GetUtcNow(),
+            RunId = runId,
+            Tenant = tenant,
+            PolicyId = policyId,
+            TraceId = Activity.Current?.TraceId.ToString(),
+            SpanId = Activity.Current?.SpanId.ToString(),
+            Data = new Dictionary<string, object?>
+            {
+                ["outcome"] = outcome,
+                ["duration_seconds"] = durationSeconds,
+                ["findings_count"] = findingsCount,
+                ["determinism_hash"] = determinismHash,
+            },
+        };
+
+        LogTimelineEvent(evt);
+    }
+
+    /// <summary>
+    /// Emits an event when a batch selection phase starts.
+    /// </summary>
+    public void EmitSelectionStarted(string runId, string tenant, string policyId, int batchNumber)
+    {
+        var evt = new TimelineEvent
+        {
+            EventType = TimelineEventType.SelectionStarted,
+            Timestamp = _timeProvider.GetUtcNow(),
+            RunId = runId,
+            Tenant = tenant,
+            PolicyId = policyId,
+            TraceId = Activity.Current?.TraceId.ToString(),
+            SpanId = Activity.Current?.SpanId.ToString(),
+            Data = new Dictionary<string, object?>
+            {
+                ["batch_number"] = batchNumber,
+            },
+        };
+
+        LogTimelineEvent(evt);
+    }
+
+    /// <summary>
+    /// Emits an event when a batch selection phase completes.
+    /// </summary>
+    public void EmitSelectionCompleted(
+        string runId,
+        string tenant,
+        string policyId,
+        int batchNumber,
+        int tupleCount,
+        double durationSeconds)
+    {
+        var evt = new TimelineEvent
+        {
+            EventType = TimelineEventType.SelectionCompleted,
+            Timestamp = _timeProvider.GetUtcNow(),
+            RunId = runId,
+            Tenant = tenant,
+            PolicyId = policyId,
+            TraceId = Activity.Current?.TraceId.ToString(),
+            SpanId = Activity.Current?.SpanId.ToString(),
+            Data = new Dictionary<string, object?>
+            {
+                ["batch_number"] = batchNumber,
+                ["tuple_count"] = tupleCount,
+                ["duration_seconds"] = durationSeconds,
+            },
+        };
+
+        LogTimelineEvent(evt);
+    }
+
+    /// <summary>
+    /// Emits an event when batch evaluation starts.
+    /// </summary>
+    public void EmitEvaluationStarted(string runId, string tenant, string policyId, int batchNumber, int tupleCount)
+    {
+        var evt = new TimelineEvent
+        {
+            EventType = TimelineEventType.EvaluationStarted,
+            Timestamp = _timeProvider.GetUtcNow(),
+            RunId = runId,
+            Tenant = tenant,
+            PolicyId = policyId,
+            TraceId = Activity.Current?.TraceId.ToString(),
+            SpanId = Activity.Current?.SpanId.ToString(),
+            Data = new Dictionary<string, object?>
+            {
+                ["batch_number"] = batchNumber,
+                ["tuple_count"] = tupleCount,
+            },
+        };
+
+        LogTimelineEvent(evt);
+    }
+
+    /// <summary>
+    /// Emits an event when batch evaluation completes.
+    /// </summary>
+    public void EmitEvaluationCompleted(
+        string runId,
+        string tenant,
+        string policyId,
+        int batchNumber,
+        int rulesEvaluated,
+        int rulesFired,
+        double durationSeconds)
+    {
+        var evt = new TimelineEvent
+        {
+            EventType = TimelineEventType.EvaluationCompleted,
+            Timestamp = _timeProvider.GetUtcNow(),
+            RunId = runId,
+            Tenant = tenant,
+            PolicyId = policyId,
+            TraceId = Activity.Current?.TraceId.ToString(),
+            SpanId = Activity.Current?.SpanId.ToString(),
+            Data = new Dictionary<string, object?>
+            {
+                ["batch_number"] = batchNumber,
+                ["rules_evaluated"] = rulesEvaluated,
+                ["rules_fired"] = rulesFired,
+                ["duration_seconds"] = durationSeconds,
+            },
+        };
+
+        LogTimelineEvent(evt);
+    }
+
+    #endregion
+
+    #region Decision Flow Events
+
+    /// <summary>
+    /// Emits an event when a rule matches during evaluation.
+    /// </summary>
+    public void EmitRuleMatched(
+        string runId,
+        string tenant,
+        string policyId,
+        string ruleId,
+        string findingKey,
+        string? severity = null)
+    {
+        var evt = new TimelineEvent
+        {
+            EventType = TimelineEventType.RuleMatched,
+            Timestamp = _timeProvider.GetUtcNow(),
+            RunId = runId,
+            Tenant = tenant,
+            PolicyId = policyId,
+            TraceId = Activity.Current?.TraceId.ToString(),
+            SpanId = Activity.Current?.SpanId.ToString(),
+            Data = new Dictionary<string, object?>
+            {
+                ["rule_id"] = ruleId,
+                ["finding_key"] = findingKey,
+                ["severity"] = severity,
+            },
+        };
+
+        LogTimelineEvent(evt);
+    }
+
+    /// <summary>
+    /// Emits an event when a VEX override is applied.
+    /// </summary>
+    public void EmitVexOverrideApplied(
+        string runId,
+        string tenant,
+        string policyId,
+        string findingKey,
+        string vendor,
+        string status,
+        string? justification = null)
+    {
+        var evt = new TimelineEvent
+        {
+            EventType = TimelineEventType.VexOverrideApplied,
+            Timestamp = _timeProvider.GetUtcNow(),
+            RunId = runId,
+            Tenant = tenant,
+            PolicyId = policyId,
+            TraceId = Activity.Current?.TraceId.ToString(),
+            SpanId = Activity.Current?.SpanId.ToString(),
+            Data = new Dictionary<string, object?>
+            {
+                ["finding_key"] = findingKey,
+                ["vendor"] = vendor,
+                ["status"] = status,
+                ["justification"] = justification,
+            },
+        };
+
+        LogTimelineEvent(evt);
+    }
+
+    /// <summary>
+    /// Emits an event when a final verdict is determined for a finding.
+    /// </summary>
+    public void EmitVerdictDetermined(
+        string runId,
+        string tenant,
+        string policyId,
+        string findingKey,
+        string verdict,
+        string severity,
+        string? reachabilityState = null,
+        IReadOnlyList<string>? contributingRules = null)
+    {
+        var evt = new TimelineEvent
+        {
+            EventType = TimelineEventType.VerdictDetermined,
+            Timestamp = _timeProvider.GetUtcNow(),
+            RunId = runId,
+            Tenant = tenant,
+            PolicyId = policyId,
+            TraceId = Activity.Current?.TraceId.ToString(),
+            SpanId = Activity.Current?.SpanId.ToString(),
+            Data = new Dictionary<string, object?>
+            {
+                ["finding_key"] = findingKey,
+                ["verdict"] = verdict,
+                ["severity"] = severity,
+                ["reachability_state"] = reachabilityState,
+                ["contributing_rules"] = contributingRules,
+            },
+        };
+
+        LogTimelineEvent(evt);
+    }
+
+    /// <summary>
+    /// Emits an event when materialization of findings starts.
+    /// </summary>
+    public void EmitMaterializationStarted(string runId, string tenant, string policyId, int findingsCount)
+    {
+        var evt = new TimelineEvent
+        {
+            EventType = TimelineEventType.MaterializationStarted,
+            Timestamp = _timeProvider.GetUtcNow(),
+            RunId = runId,
+            Tenant = tenant,
+            PolicyId = policyId,
+            TraceId = Activity.Current?.TraceId.ToString(),
+            SpanId = Activity.Current?.SpanId.ToString(),
+            Data = new Dictionary<string, object?>
+            {
+                ["findings_count"] = findingsCount,
+            },
+        };
+
+        LogTimelineEvent(evt);
+    }
+
+    /// <summary>
+    /// Emits an event when materialization of findings completes.
+    /// </summary>
+    public void EmitMaterializationCompleted(
+        string runId,
+        string tenant,
+        string policyId,
+        int findingsWritten,
+        int findingsUpdated,
+        double durationSeconds)
+    {
+        var evt = new TimelineEvent
+        {
+            EventType = TimelineEventType.MaterializationCompleted,
+            Timestamp = _timeProvider.GetUtcNow(),
+            RunId = runId,
+            Tenant = tenant,
+            PolicyId = policyId,
+            TraceId = Activity.Current?.TraceId.ToString(),
+            SpanId = Activity.Current?.SpanId.ToString(),
+            Data = new Dictionary<string, object?>
+            {
+                ["findings_written"] = findingsWritten,
+                ["findings_updated"] = findingsUpdated,
+                ["duration_seconds"] = durationSeconds,
+            },
+        };
+
+        LogTimelineEvent(evt);
+    }
+
+    #endregion
+
+    #region Error Events
+
+    /// <summary>
+    /// Emits an event when an error occurs during evaluation.
+    /// </summary>
+    public void EmitError(
+        string runId,
+        string tenant,
+        string policyId,
+        string errorCode,
+        string errorMessage,
+        string? phase = null)
+    {
+        var evt = new TimelineEvent
+        {
+            EventType = TimelineEventType.Error,
+            Timestamp = _timeProvider.GetUtcNow(),
+            RunId = runId,
+            Tenant = tenant,
+            PolicyId = policyId,
+            TraceId = Activity.Current?.TraceId.ToString(),
+            SpanId = Activity.Current?.SpanId.ToString(),
+            Data = new Dictionary<string, object?>
+            {
+                ["error_code"] = errorCode,
+                ["error_message"] = errorMessage,
+                ["phase"] = phase,
+            },
+        };
+
+        LogTimelineEvent(evt, LogLevel.Error);
+    }
+
+    /// <summary>
+    /// Emits an event when a determinism violation is detected.
+    /// </summary>
+    public void EmitDeterminismViolation(
+        string runId,
+        string tenant,
+        string policyId,
+        string violationType,
+        string details)
+    {
+        var evt = new TimelineEvent
+        {
+            EventType = TimelineEventType.DeterminismViolation,
+            Timestamp = _timeProvider.GetUtcNow(),
+            RunId = runId,
+            Tenant = tenant,
+            PolicyId = policyId,
+            TraceId = Activity.Current?.TraceId.ToString(),
+            SpanId = Activity.Current?.SpanId.ToString(),
+            Data = new Dictionary<string, object?>
+            {
+                ["violation_type"] = violationType,
+                ["details"] = details,
+            },
+        };
+
+        LogTimelineEvent(evt, LogLevel.Warning);
+    }
+
+    #endregion
+
+    private void LogTimelineEvent(TimelineEvent evt, LogLevel level = LogLevel.Information)
+    {
+        _logger.Log(
+            level,
+            "PolicyTimeline: {EventType} | run={RunId} tenant={Tenant} policy={PolicyId} trace={TraceId} span={SpanId} data={Data}",
+            evt.EventType,
+            evt.RunId,
+            evt.Tenant,
+            evt.PolicyId,
+            evt.TraceId,
+            evt.SpanId,
+            JsonSerializer.Serialize(evt.Data, TimelineEventJsonContext.Default.DictionaryStringObject));
+    }
+}
+
+/// <summary>
+/// Types of timeline events emitted during policy evaluation.
+/// </summary>
+public enum TimelineEventType
+{
+    RunStarted,
+    RunCompleted,
+    SelectionStarted,
+    SelectionCompleted,
+    EvaluationStarted,
+    EvaluationCompleted,
+    RuleMatched,
+    VexOverrideApplied,
+    VerdictDetermined,
+    MaterializationStarted,
+    MaterializationCompleted,
+    Error,
+    DeterminismViolation,
+}
+
+/// <summary>
+/// Represents a timeline event for policy evaluation flows.
+/// </summary>
+public sealed record TimelineEvent
+{
+    public required TimelineEventType EventType { get; init; }
+    public required DateTimeOffset Timestamp { get; init; }
+    public required string RunId { get; init; }
+    public required string Tenant { get; init; }
+    public required string PolicyId { get; init; }
+    public string? PolicyVersion { get; init; }
+    public string? TraceId { get; init; }
+    public string? SpanId { get; init; }
+    public Dictionary<string, object?>? Data { get; init; }
+}
+
+[JsonSerializable(typeof(Dictionary<string, object?>))]
+[JsonSourceGenerationOptions(WriteIndented = false)]
+internal partial class TimelineEventJsonContext : JsonSerializerContext
+{
+}