Zaya.Logging 1.0.0

Zaya.Logging

Aspect-style logging for the Zaya ecosystem: mark implementation methods with [Log], create instances through ILoggingWrapper.Wrap<T>, keep service interfaces free of logging concerns.

Packages

Layout mirrors OCR packages: Models/, Services/ (no source files at project root).

Future: Zaya.Logging.Impl.Serilog, etc. (sinks only — proxy stays in Impl).

These Impl packages are host NuGet dependencies, not AppData plugins (unlike Zaya.OCR.Impl.* zips).

See versioning and CHANGELOG. Package major is owned by this repo (ZayaLoggingMajor in Directory.Build.props).

Design rules

• Want to log a step → extract a small service + interface, put [Log] on the implementation method, create via logging.Wrap<T>(...).
• [Log] on interface methods is ignored.
• [Log] on a class applies to all methods of the wrapped interface(s); a method-level [Log] overrides the class attribute.
• Call entry is written when the attribute level is enabled. Use [Log(LogLevel.Trace)] if you only want the call visible at Trace.
• For [Log] methods, exceptions are always logged at Error (when Error is enabled). The method name (± parameters) is written once: on the entry line, or on the error line if the entry was skipped — never duplicated.
• When Trace is enabled on the sink, Wrap also logs every unmarked interface method at Trace (entry only; no forced exception logging).
• Use EmptyLoggingWrapper.Instance when logging is off — Wrap is identity, no null checks.
• Outer Wrap of the root service is done by the host (typically a DI factory). Nested sessions/children are wrapped inside the service via the injected ILoggingWrapper.
• Log level enablement is fixed when the wrapper is created; changing level requires recreating the wrapper/proxies.
• At Wrap time: methods without [Log], or with a disabled level, are not included in the logging plan (empty plan returns the same instance).

Example

using Zaya.Logging.Impl.Microsoft.Services;
using Zaya.Logging.Impl.Services;
using Zaya.Logging.Models;
using Zaya.Logging.Services;

public interface IOcrStep
{
    void Run(string path);
}

public sealed class OcrStep : IOcrStep
{
    [Log(LogLevel.Information, LogParameters = true)]
    public void Run(string path) { }
}

public sealed class Pipeline : IPipeline
{
    private readonly ILoggingWrapper _logging;
    private readonly IOcrStep _step;

    public Pipeline() : this(EmptyLoggingWrapper.Instance) { }

    public Pipeline(ILoggingWrapper logging)
    {
        _logging = logging;
        _step = logging.Wrap<IOcrStep>(new OcrStep());
    }

    [Log(LogLevel.Debug)]
    public void Execute(string path) => _step.Run(path);
}

// Host DI
services.AddSingleton<ILoggingWrapper>(sp =>
{
    var mel = sp.GetRequiredService<ILoggerFactory>().CreateLogger("Zaya");
    return new LoggingWrapper(new MicrosoftExtensionsLogger(mel));
});

services.AddSingleton<IPipeline>(sp =>
{
    var logging = sp.GetRequiredService<ILoggingWrapper>();
    return logging.Wrap<IPipeline>(new Pipeline(logging));
});

Installation (host)

<PackageReference Include="Zaya.Logging" Version="1.0.0" />
<PackageReference Include="Zaya.Logging.Impl" Version="1.0.0.0" />
<PackageReference Include="Zaya.Logging.Impl.Microsoft" Version="1.0.0.0" />

Plugins reference only Zaya.Logging (abstractions).