ScadaBridge/src/ZB.MOM.WW.ScadaBridge.Commons/Observability/ExecutionLogContext.cs

using Serilog.Context;

namespace ZB.MOM.WW.ScadaBridge.Commons.Observability;

/// <summary>
/// Stamps an execution id onto the Serilog <c>LogContext</c> (ScadaBridge#56), so every line
/// logged inside the scope - through Serilog directly or through a Microsoft
/// <c>ILogger</c> backed by Serilog (<c>UseSerilog</c>) - carries an <c>ExecutionId</c>
/// property once the host enables <c>Enrich.FromLogContext()</c>.
/// </summary>
/// <remarks>
/// <para><b>Why per message.</b> <c>LogContext</c> is an <c>AsyncLocal</c>: it follows one
/// async call chain but does not cross an Akka message hop (the dispatcher does not flow the
/// sender's execution context into the receiver). An actor that serves an execution therefore
/// re-establishes the id from the message itself, for the duration of that one message:
/// <code>
/// protected override bool AroundReceive(Receive receive, object message)
/// {
///     using (ExecutionLogContext.PushFor(message))
///         return base.AroundReceive(receive, message);
/// }
/// </code>
/// Continuations the handler starts (<c>ContinueWith</c>, <c>PipeTo</c>, an adapter call)
/// capture the context at creation, so their lines carry the id too.</para>
/// <para><b>Cost.</b> A message that is not <see cref="IExecutionCorrelated"/>, or names no
/// execution, costs one type test and allocates nothing.</para>
/// <para><b>Nesting.</b> A later push of the same property wins, so a child run started while
/// serving its parent's message logs under its OWN id (the launcher pushes it).</para>
/// </remarks>
public static class ExecutionLogContext
{
    /// <summary>The log-event property carrying the execution id.</summary>
    public const string ExecutionIdProperty = "ExecutionId";

    /// <summary>
    /// The innermost execution id pushed on this async flow, or null. Mirrors the
    /// <see cref="ExecutionIdProperty"/> on the Serilog <c>LogContext</c>, which cannot be read back.
    /// </summary>
    /// <remarks>
    /// ScadaBridge#120: Akka's <c>ILoggingAdapter</c> hands each line to a logger actor on another
    /// thread, where this flow's <c>LogContext</c> is gone. An adapter that captures this value when
    /// the line is logged lets the logger actor re-push it when it writes the line to Serilog.
    /// </remarks>
    public static Guid? Current => CurrentId.Value;

    private static readonly AsyncLocal<Guid?> CurrentId = new();

    /// <summary>Pushes <paramref name="executionId"/> as <see cref="ExecutionIdProperty"/>.</summary>
    /// <param name="executionId">The execution id; null pushes nothing.</param>
    /// <returns>A disposable that pops the property, or null when nothing was pushed.</returns>
    public static IDisposable? Push(Guid? executionId)
    {
        if (executionId is not { } id)
        {
            return null;
        }

        var previous = CurrentId.Value;
        var property = LogContext.PushProperty(ExecutionIdProperty, id);
        CurrentId.Value = id;
        return new Scope(property, previous);
    }

    /// <summary>Pushes the execution a message serves, when it names one.</summary>
    /// <param name="message">Any actor message.</param>
    /// <returns>A disposable that pops the property, or null when the message names no execution.</returns>
    public static IDisposable? PushFor(object? message)
        => message is IExecutionCorrelated correlated ? Push(correlated.CorrelatedExecutionId) : null;

    /// <summary>Pops the pushed property and restores the previous <see cref="Current"/>.</summary>
    private sealed class Scope(IDisposable property, Guid? previous) : IDisposable
    {
        private int _disposed;

        public void Dispose()
        {
            if (Interlocked.Exchange(ref _disposed, 1) != 0)
            {
                return;
            }

            CurrentId.Value = previous;
            property.Dispose();
        }
    }
}