OzaLog 3.2.0

.NET 8.0 This package targets .NET 8.0. The package is compatible with this framework or higher. .NET Standard 2.0 This package targets .NET Standard 2.0. The package is compatible with this framework or higher.
There is a newer version of this package available.
See the version list below for details. 
dotnet add package OzaLog --version 3.2.0
                    


                    

                
NuGet\Install-Package OzaLog -Version 3.2.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="OzaLog" Version="3.2.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
<PackageVersion Include="OzaLog" Version="3.2.0" />
                    


                            Directory.Packages.props
                        

                    

                
<PackageReference Include="OzaLog" />
                    


                            Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package. 
paket add OzaLog --version 3.2.0
                    


                    

                
#r "nuget: OzaLog, 3.2.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
#:package OzaLog@3.2.0
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package. 
#addin nuget:?package=OzaLog&version=3.2.0
                    


                            Install as a Cake Addin
                        

                    

                
#tool nuget:?package=OzaLog&version=3.2.0
                    


                            Install as a Cake Tool

OzaLog

nuget github

English | 繁體中文

Disclaimer: OzaLog is not related to NLog (jkowalski's package). This is a separate, independent library.

Migrating from Ozakboy.NLOG v2.x? See Migration Guide. The previous package has been deprecated and renamed to OzaLog.

Changelog: English · 繁體中文

A lean, lightweight .NET local file logging library with the simplest possible static API. No DI, no LoggerFactory, zero NuGet dependencies on net8+. Designed for high-throughput multi-threaded scenarios such as cryptocurrency tick streams.

Why OzaLog

  • Simplest possible API — LOG.Info_Log("hello") works without any setup
  • Single purpose — local file logging only, no abstractions
  • Zero dependencies — net8+ targets have no NuGet dependencies
  • HFT-tuned hot path — persistent FileStream pool with LRU eviction, cached timestamp, struct-based queue, drop-oldest backpressure
  • Faster than NLog and Serilog in HFT-style multi-thread scenarios (see Benchmarks below)

What OzaLog is NOT

  • ❌ Not a Microsoft.Extensions.Logging provider — does not integrate with ILogger<T> DI
  • ❌ Not a structured logger — no {Property} placeholder capture
  • ❌ Not a multi-target logger — file output only (no Console / Database / remote sinks)
  • ❌ Not configurable via XML / appsettings.json — programmatic configuration only

If any of the above is a hard requirement, use NLog or Serilog instead.

Supported Frameworks

  • .NET 8.0 / 9.0 / 10.0 (LTS + current)
  • .NET Standard 2.0 / 2.1 (legacy compatibility)

Dropped in OzaLog v3.0: .NET Framework 4.6.2, .NET 6.0, .NET 7.0 (all EOL).

Installation

dotnet add package OzaLog

Or via Package Manager Console:

Install-Package OzaLog

Quick Start

using OzaLog;

LOG.Info_Log("Hello, World!");
LOG.Error_Log("Something went wrong");
LOG.CustomName_Log("BTC", "tick: 67890.12");

That's it — no Configure call required (defaults work). For advanced configuration:

LOG.Configure(o =>
{
    o.KeepDays = -7;                          // keep last 7 days of logs
    o.SetFileSizeInMB(50);                    // split files at 50 MB
    o.EnableAsyncLogging = true;              // default true
    o.EnableConsoleOutput = true;             // also write to console
    o.MaxOpenFileStreams = 100;               // LRU upper bound
    o.DiskFlushIntervalMs = 100;              // periodic flush
    o.EnableGlobalExceptionCapture = false;   // opt-in: auto-log unhandled exceptions
    o.OnDropped = () => Interlocked.Increment(ref _dropCount);
    o.ConfigureAsync(a =>
    {
        a.MaxBatchSize = 1000;
        a.MaxQueueSize = 100_000;
        a.FlushIntervalMs = 100;
    });
});

Log File Layout

{AppRoot}/
└── logs/
    └── 20260509/                 # yyyyMMdd date folder
        └── LogFiles/             # type subfolder (configurable)
            ├── Info_Log.txt
            ├── Error_Log.txt
            ├── BTC_Log.txt       # CustomName logs go here
            └── ETH_Log.txt

Use options.LogPath to change the root, and options.TypeDirectories.*Path to give each level its own folder.

Logging Methods

Every level has the same 5 overloads:

LOG.Info_Log(string message);
LOG.Info_Log(string message, bool writeTxt);
LOG.Info_Log(string message, string[] args, bool writeTxt = true, bool immediateFlush = false);
LOG.Info_Log<T>(T obj, bool writeTxt = true, bool immediateFlush = false) where T : class;
LOG.Info_Log<T>(string message, T obj, bool writeTxt = true, bool immediateFlush = false) where T : class;

Available levels: Trace_Log / Debug_Log / Info_Log / Warn_Log / Error_Log / Fatal_Log.

For custom log buckets:

LOG.CustomName_Log("BTC", "tick: 67890.12");        // → BTC_Log.txt
LOG.CustomName_Log("API", "external call");         // → API_Log.txt

Exception Logging

try { /* code */ }
catch (Exception ex)
{
    LOG.Error_Log(ex);                            // serialized as JSON
    LOG.Error_Log("operation context", ex);       // with custom message
}

Exception details (Type, Message, StackTrace, InnerException, Data dictionary, additional properties) are automatically captured.

Global Exception Capture (opt-in)

LOG.Configure(o => o.EnableGlobalExceptionCapture = true);

Subscribes to AppDomain.UnhandledException and TaskScheduler.UnobservedTaskException and logs them as Fatal with synchronous flush to ensure crash logs land on disk.

Note: This does not cover WPF/WinForms UI thread exceptions or ASP.NET Core middleware exceptions — those need to be hooked separately by the application.

Benchmarks

Measured against ZLogger 2.5.10, ZeroLog 2.6.1, Serilog 4.2.0 + Sinks.File 6.0.0 on .NET 10.0.7 (AMD Ryzen 9 9950X3D, BenchmarkDotNet 0.14):

S1 — Single short message

Method Mean Allocated
OzaLog 65.96 ns 151 B
ZLogger 219.53 ns 278 B
ZeroLog 12.19 ns 0 B
Serilog 168.87 ns 160 B

S3 — HFT 8 thread × 50 products × 2000 logs = 800 K writes

Method Mean Allocated
OzaLog 3,047 μs 3.94 MB
ZLogger 4,996 μs 5.21 KB
ZeroLog 649 μs 3.35 KB
Serilog 11,092 μs 8.27 MB

Verdict: OzaLog is faster than ZLogger and Serilog in both scenarios. ZeroLog wins on raw speed (it uses source generators for true zero-allocation), but OzaLog's static API is simpler.

→ Run benchmarks yourself: dotnet run -c Release --project OzaLog.Benchmarks

License

MIT License

Support

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 is compatible.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 is compatible. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

  • .NETStandard 2.0

  • .NETStandard 2.1

  • net10.0

    • No dependencies.

  • net8.0

    • No dependencies.

  • net9.0

    • No dependencies.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
3.3.0 92 9/13/2026
3.2.0 86 9/11/2026
3.1.0 157 5/14/2026
3.0.1 131 5/9/2026
3.0.0 139 5/8/2026

v3.2.0 — Three fixes that change what actually lands in your log files. No API changes, no default value changes. Released as a minor version, not a patch, because the content of your logs changes: read the notes below before upgrading if anything downstream reads these files.

FIXED:
- Error / Fatal entries (and any call with immediateFlush: true) were written TWICE. AsyncLogHandler.Enqueue queued the item for the dispatcher and also wrote it synchronously on the caller thread, so each entry appeared as two identical lines. If you have been counting errors from your logs, your numbers were inflated — between 1x and 2x the real count, not a clean doubling, because the queued copy could still be discarded by drop-oldest backpressure when the queue was saturated. Recalibrate any error-rate alert thresholds. These entries are now written only once, on the caller thread, with the immediate-flush guarantee unchanged; as a side benefit they no longer pass through the queue and can never be dropped. Trace / Debug / Info / Warn / CustomName were not affected.
- Synchronous mode (EnableAsyncLogging = false) produced 0-byte log files. The synchronous path wrote into a StreamWriter with AutoFlush = false and nothing ever flushed it — the dispatcher, the periodic disk-flush timer and the ProcessExit hook are all started by the async pipeline, which synchronous mode never reaches, so the content was lost when the process exited. If you have been using synchronous mode, your log files have been empty all along. Synchronous mode now flushes after every entry (no forced fsync), stays thread-safe, and produces formatting identical to asynchronous mode.
- Curly braces in a message were doubled in the file output: serialized exceptions landed as {{ "Type": ... }} instead of { "Type": ... }, so the JSON could not be parsed. LOG.Log escaped every { and } up front for AppendFormat, but the no-arguments path appends the message directly and never unescapes it. BREAKING FOR LOG PARSERS: exception and object payloads are now emitted as valid, directly parsable JSON. If you built parsing or regex around the doubled braces, adjust it. Messages that mix literal braces with {0} placeholders now also format correctly — previously the whole message was emitted raw with the placeholder unsubstituted.

TECHNICAL:
- Brace escaping moved from the caller thread into the formatter, and now happens only on the AppendFormat path. Valid format items ({0}, {1,-8}, {2:F4}) are preserved; everything else is escaped, including out-of-range indexes that used to throw FormatException. Applies to both text and JSON output formats.
- Removed the Microsoft.SourceLink.GitHub package reference. SourceLink has shipped in the SDK since .NET 8; PublishRepositoryUrl + EmbedUntrackedSources produce an identical nuspec repository element and identical source-link mappings in the PDBs on all five target frameworks, netstandard2.0 and 2.1 included. This clears the NU1902 vulnerability advisory on its transitive Microsoft.Build.Tasks.Git dependency. Build-only change; consumers are unaffected.
- Added XML documentation for the 16 remaining public members of LogConfiguration. The library now builds with 0 warnings on all five target frameworks.
- New regression tests (BraceEscapingTests) covering literal braces with and without format arguments, both output formats, and exception payloads verified by actually parsing them with System.Text.Json. DuplicateWriteTests, SyncModeWriteTests and AutoFlushLevelTests still pass; 73 tests green.

KNOWN LIMITATION:
- Synchronous mode still has no retention cleanup (KeepDays does not take effect without the async pipeline). Clean old date directories yourself, or use asynchronous mode.

Full changelog: https://github.com/ozakboy/OzaLog/blob/main/docs/en/changelog.md
Async pipeline details: https://github.com/ozakboy/OzaLog/blob/main/docs/en/async-pipeline.md
Website: https://ozakboy.github.io/OzaLog/