Oakrey.Applications.Trace 2.0.3

Oakrey.Applications.Trace

A .NET library for tracing application activities to files. Exposes a base class and interface for building custom tracers with start/stop control, real-time Rx observables for status and elapsed time, configurable file naming, and thread-safe file writing.

NuGet package ID: Oakrey.Applications.Trace

Main features

• ITracer interface with StartTrace / StopTrace, Tracing state, and TracePath configuration
• TracerBase abstract base class handles all file I/O, timer management, and observable publishing
• IObservable<TracerStatus> (Stopped / Running / Paused) emitted via StatusChanged
• IObservable<TimeSpan> emitted every millisecond via TraceTimeChanged for live elapsed-time binding
• Configurable trace folder path, file naming policy, file increment counter, and format string via ITracerSettings
• File name resolution delegated to Oakrey.Files.FileNameSource (supports naming policies and auto-increment)
• Thread-safe line writing using lock and MemoryPool<byte> to avoid per-write allocations
• Automatic trace-file header and footer written by the framework
• Integrated with Oakrey.Log for internal diagnostic logging and Oakrey.Telemetry for activity tracing
• IDisposable support: stopping an active trace on disposal

Architecture

classDiagram
    class ITracer {
        +IObservable~TracerStatus~ StatusChanged
        +IObservable~TimeSpan~ TraceTimeChanged
        +bool Enabled
        +bool FolderTraceCorrect
        +bool Tracing
        +string TracePath
        +string TraceTime
        +StartTrace()
        +StopTrace()
    }

    class TracerBase {
        #abstract string FileName
        #abstract string SwName
        #abstract string Extension
        #abstract WriteHeader()
        #WriteLine(string)
        #int Incrementor
    }

    class ITracerSettings {
        +string LastTraceFolderPath
        +FileNamingPolicy TraceFileNamingPolicy
        +int LastTraceFileIncrement
        +string Format
    }

    class TracerStatus {
        <<enumeration>>
        Stopped
        Running
        Paused
    }

    ITracer <|.. TracerBase
    TracerBase --> ITracerSettings
    TracerBase --> TracerStatus

Project files

Requirements

• .NET 10 or higher
• Oakrey.Files 3.0.0
• Oakrey.Log 2.0.0
• Oakrey.Telemetry 2.0.1
• System.Reactive 6.1.0

Installation

NuGet Package Manager

1. Open your project in Visual Studio.
2. Navigate to Tools > NuGet Package Manager > Manage NuGet Packages for Solution.
3. Search for Oakrey.Applications.Trace and click Install.

.NET CLI

dotnet add package Oakrey.Applications.Trace

Package Manager Console

Install-Package Oakrey.Applications.Trace

Configuration

Implement ITracerSettings to provide trace configuration. All properties must be persisted by the caller (e.g. in user settings or a configuration file):

public class MyTracerSettings : ITracerSettings
{
    public string LastTraceFolderPath { get; set; } = @"C:\Traces";
    public FileNamingPolicy TraceFileNamingPolicy { get; set; } = FileNamingPolicy.DateTimePrefix;
    public int LastTraceFileIncrement { get; set; } = 0;
    public string Format { get; set; } = "yyyy-MM-dd";
}

Example usage

Extend TracerBase to define the file name, application name, extension, and the custom header written at the top of every trace file:

public class AppTracer : TracerBase, ITracer
{
    public AppTracer(ITracerSettings settings) : base(settings) { }

    protected override string FileName => "AppTrace";
    protected override string SwName => "MyApplication";
    protected override string Extension => "log";

    protected override void WriteHeader()
    {
        WriteLine("=== MyApplication trace ===");
        WriteLine($"Started: {DateTime.Now}");
    }

    // Expose StartTrace publicly (protected in base)
    public new void StartTrace() => base.StartTrace();
}

Subscribe to observables to drive UI or diagnostic output:

AppTracer tracer = new(new MyTracerSettings());

tracer.StatusChanged.Subscribe(status =>
    Console.WriteLine($"Tracer status: {status}"));

tracer.TraceTimeChanged.Subscribe(elapsed =>
    Console.WriteLine($"Elapsed: {elapsed}"));

tracer.StartTrace();
// ... write lines via WriteLine inside the tracer
tracer.StopTrace();

Development notes

• TracerBase acquires a Lock on every WriteLine call. Writers on background threads are safe without additional synchronization.
• The elapsed-time timer fires every 1 ms. Subscribers on the UI thread should observe on the dispatcher scheduler to avoid cross-thread issues.
• Paused is defined in TracerStatus but is not set by TracerBase itself. Custom subclasses can publish it via the inherited status subject.
• Disposal calls StopTrace if tracing is active, ensuring the trace footer is written and the file is closed cleanly.

License

MIT - Copyright (c) Oakrey 2016-present

Contributions are welcome! Feel free to open issues or submit pull requests to improve the package.

License

This project is licensed under the MIT License. See the LICENSE file for details.