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";

    /// <summary>Structured property name carrying the Script row identifier (<c>Script.ScriptId</c>).</summary>
    public const string ScriptIdProperty = "ScriptId";

    /// <summary>Structured property name carrying the VirtualTag identifier, when the script runs in a virtual-tag context.</summary>
    public const string VirtualTagIdProperty = "VirtualTagId";

    /// <summary>Structured property name carrying the ScriptedAlarm identifier, when the script runs in an alarm context.</summary>
    public const string AlarmIdProperty = "AlarmId";

    /// <summary>Structured property name carrying the Equipment identifier for per-equipment script evaluations.</summary>
    public const string EquipmentIdProperty = "EquipmentId";

    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);
    }

    /// <summary>
    ///     Create a per-evaluation script logger bound with the supplied identity properties.
    ///     <see cref="ScriptIdProperty"/> is always bound; <see cref="VirtualTagIdProperty"/>,
    ///     <see cref="AlarmIdProperty"/>, and <see cref="EquipmentIdProperty"/> are bound only
    ///     when the corresponding argument is non-null. Every event the returned logger emits
    ///     carries these properties so the <see cref="ScriptLogTopicSink"/> can attribute each
    ///     line on the Script-log page.
    /// </summary>
    /// <param name="scriptId">The Script row identifier; always bound. Required.</param>
    /// <param name="virtualTagId">VirtualTag context, when the script runs against a virtual tag.</param>
    /// <param name="alarmId">ScriptedAlarm context, when the script runs an alarm predicate.</param>
    /// <param name="equipmentId">Equipment scope, for per-equipment script evaluations.</param>
    /// <returns>An ILogger instance bound with the supplied identity properties.</returns>
    /// <exception cref="ArgumentException">Thrown when <paramref name="scriptId"/> is null or whitespace.</exception>
    public ILogger Create(
        string scriptId,
        string? virtualTagId = null,
        string? alarmId = null,
        string? equipmentId = null)
    {
        if (string.IsNullOrWhiteSpace(scriptId))
            throw new ArgumentException("Script id is required.", nameof(scriptId));

        var logger = _rootLogger.ForContext(ScriptIdProperty, scriptId);
        if (virtualTagId is not null) logger = logger.ForContext(VirtualTagIdProperty, virtualTagId);
        if (alarmId is not null) logger = logger.ForContext(AlarmIdProperty, alarmId);
        if (equipmentId is not null) logger = logger.ForContext(EquipmentIdProperty, equipmentId);
        return logger;
    }
}