Oakrey.Applications.Trace
8.0.0
dotnet add package Oakrey.Applications.Trace --version 8.0.0
NuGet\Install-Package Oakrey.Applications.Trace -Version 8.0.0
<PackageReference Include="Oakrey.Applications.Trace" Version="8.0.0" />
<PackageVersion Include="Oakrey.Applications.Trace" Version="8.0.0" />
<PackageReference Include="Oakrey.Applications.Trace" />
paket add Oakrey.Applications.Trace --version 8.0.0
#r "nuget: Oakrey.Applications.Trace, 8.0.0"
#:package Oakrey.Applications.Trace@8.0.0
#addin nuget:?package=Oakrey.Applications.Trace&version=8.0.0
#tool nuget:?package=Oakrey.Applications.Trace&version=8.0.0
Oakrey.Applications.Trace
A .NET 11 library for building file-based application tracers with observable status and elapsed-time updates.
NuGet package ID: Oakrey.Applications.Trace
Main features
TracerBaseowns trace file creation, UTF-8 writing, elapsed-time measurement, status publication, and cleanup.- Derived tracers provide file naming, software naming, and custom header content.
StatusChangedpublishes the initialStoppedstate and subsequent running/stopped transitions.TraceTimeChangedpublishes monotonic elapsed time every 250 ms while tracing.- Repeated start and stop calls are idempotent.
- Trace files are created only inside an existing configured trace directory.
- Generated file paths are checked to prevent escaping the configured directory.
- Operational logging uses placeholders and never records the full trace directory path.
- Active traces are completed automatically during disposal.
Public contracts
ITracer defines the public application-facing contract. TracerBase.StartTrace remains protected, so a derived tracer exposes it publicly when implementing ITracer.
ITracerSettings provides:
LastTraceFolderPathTraceFileNamingPolicyLastTraceFileIncrementFormat
No public interface signatures are changed by the current implementation.
Requirements and direct dependencies
- .NET 11
Oakrey.Files4.0.0Oakrey.Log.Abstractions3.0.0Oakrey.Telemetry2.0.1System.Reactive6.1.0
Installation
dotnet add package Oakrey.Applications.Trace
Package Manager Console:
Install-Package Oakrey.Applications.Trace
Configuration
using Oakrey.Applications.Trace;
using Oakrey.Files;
public sealed class MyTracerSettings : ITracerSettings
{
public string LastTraceFolderPath { get; set; } = @"C:\Traces";
public FileNamingPolicy TraceFileNamingPolicy { get; set; } =
FileNamingPolicy.DateTimeCompact;
public int LastTraceFileIncrement { get; set; }
public string Format { get; set; } = string.Empty;
}
The configured directory must already exist. Assigning TracePath normalizes it to an absolute path.
Example tracer
using Oakrey.Applications.Trace;
public sealed class AppTracer(ITracerSettings settings)
: TracerBase(settings), ITracer
{
protected override string FileName => "application";
protected override string SwName => "MyApplication";
protected override string Extension => "log";
public new void StartTrace() => base.StartTrace();
public void Write(string message) => WriteLine(message);
protected override void WriteHeader()
{
WriteLine("=== MyApplication trace ===");
}
}
Usage:
using AppTracer tracer = new(new MyTracerSettings());
using IDisposable statusSubscription = tracer.StatusChanged.Subscribe(
status => Console.WriteLine($"Status: {status}"));
tracer.StartTrace();
tracer.Write("Work started");
tracer.StopTrace();
Lifecycle and safety notes
- File output uses
StreamWriterwith UTF-8 without BOM and flushes each completed line. - Elapsed time uses
Stopwatch, so system clock changes do not alter the measured duration. - Timer callbacks and file lifecycle operations are synchronized.
- Rx observer callbacks are synchronous. Elapsed-time notifications originate on the timer thread unless the subscriber changes scheduler.
TracerStatus.Pausedremains part of the enum but is not published byTracerBase.- Calling protected write functionality without an active trace skips the line and records a warning.
- Calling trace operations after disposal throws
ObjectDisposedException. - Subjects, timer, writer, and underlying stream are released even when no trace is active.
- Trace lines are application data and can contain sensitive information; callers are responsible for filtering content before writing.
License
MIT - Copyright (c) Oakrey 2016-present
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net11.0 is compatible. |
-
net11.0
- Oakrey.Files (>= 5.0.0)
- Oakrey.Log.Abstractions (>= 4.0.0)
- Oakrey.Telemetry (>= 3.0.0)
- System.Reactive (>= 7.0.0)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.