lmxopcua/src/Core/ZB.MOM.WW.OtOpcUa.Core.Scripting/ScriptLoggerFactory.cs

using Serilog;

namespace ZB.MOM.WW.OtOpcUa.Core.Scripting;

/// <summary>
///     Creates per-script Serilog <see cref="ILogger"/> instances with the
///     <c>ScriptName</c> structured property pre-bound. Every log call from a user
///     script carries the owning virtual-tag or alarm name so operators can filter the
///     dedicated <c>scripts-*.log</c> sink by script in the Admin UI.
/// </summary>
/// <remarks>
///     <para>
///         Factory-based — the engine (Stream B / C) constructs exactly one instance
///         from the root script-logger pipeline at startup, then derives a per-script
///         logger for each <see cref="ScriptContext"/> it builds. No per-evaluation
///         allocation in the hot path.
///     </para>
///     <para>
///         The wrapped root logger is responsible for output wiring — typically a
///         rolling file sink to <c>scripts-*.log</c> plus a
///         <see cref="ScriptLogCompanionSink"/> that forwards Error-or-higher events
///         to the main server log at Warning level so operators see script errors
///         in the primary log without drowning it in Info noise.
///     </para>
/// </remarks>
public sealed class ScriptLoggerFactory
{
    /// <summary>Structured property name the enricher binds. Stable for log filtering.</summary>
    public const string ScriptNameProperty = "ScriptName";

    private readonly ILogger _rootLogger;

    /// <summary>Initializes a new instance of the <see cref="ScriptLoggerFactory"/> class.</summary>
    /// <param name="rootLogger">The root logger from which per-script loggers are derived.</param>
    public ScriptLoggerFactory(ILogger rootLogger)
    {
        _rootLogger = rootLogger ?? throw new ArgumentNullException(nameof(rootLogger));
    }

    /// <summary>
    ///     Create a per-script logger. Every event it emits carries
    ///     <c>ScriptName=<paramref name="scriptName"/></c> as a structured property.
    /// </summary>
    /// <param name="scriptName">The name of the script for which to create a logger.</param>
    /// <returns>An ILogger instance bound with the script name.</returns>
    public ILogger Create(string scriptName)
    {
        if (string.IsNullOrWhiteSpace(scriptName))
            throw new ArgumentException("Script name is required.", nameof(scriptName));
        return _rootLogger.ForContext(ScriptNameProperty, scriptName);
    }
}