TrailScribe 0.1.6

TrailScribe

TrailScribe is a modern, high-performance, and structured logging library for .NET. Instead of writing plain text logs, TrailScribe records your application's journey as a series of structured "trails."

TrailScribe is built with a simple philosophy: logging should be both easy for developers and powerful for machines. It provides a simple API to record rich, structured events that can be easily collected, searched, and analyzed by modern log management platforms.

Features ✨

• 🚀 High-Performance: Asynchronous, low-allocation design to minimize impact on your application's performance.
• ✍️ Structured First: Trails are structured by default, making them easy to query and visualize in tools like Elasticsearch, Datadog, or Splunk.
• 🔧 Fluent Configuration: A clean, expressive API for configuring levels, formatters, and writers.
• 🔌 Extensible: Easily create your own custom writers and formatters to send trails anywhere you need.
• 🎯 Modern .NET: Built on .NET 8.0 to support a wide range of applications.

Getting Started

1. Installation

You can install TrailScribe from NuGet using your preferred method.

.NET CLI

dotnet add package TrailScribe

Visual Studio NuGet Package Manager

1. Open the NuGet Package Manager in Visual Studio.
2. Search for TrailScribe.
3. Select the package and click "Install".

2. Basic Usage

Here's how to create your first Scribe and record a trail:

using TrailScribe;

// 1. Configure a new Scribe using the builder.
Scribe scribe = new();

// 2. Record traces using different TrailMarkers.
scribe.Debug("Application starting up...");
scribe.Error("Failed to write to disk.");

// Example of a trace with structured properties
string user = "Alice";
int cartId = 12345;
scribe.Info("User {0} has checked out with cart {1}", user, cartId);

Expected Console Output

The output will be clean, formatted text, ready to be processed by any log collector.

[Info](10/8/2025 5:53:57 PM): User Alice has checked out with cart 12345

Advanced Configuration

The Scribe class allows you to create more complex logging pipelines.

using (StreamWriter writer = new("path.json"))
{
    Scribe scribe = new()
    {
        // Set the minimum level of traces to be recorded.
        // In this case, 'Debug' traces will be ignored.
        MinimumSeverity = ScribeSeverity.Info,
        // Specify the formatter to use to format the trail.
        Formatter = new ScribeJsonFormatter(),
        // Specify the writer to use to write the trail.
        // In this case, since we are using the JSON formatter,
        // we need to use the JSON writer.
        Writer = new ScribeJsonWriter(writer)
    };
    
    scribe.Debug("This will be ignored");
    scribe.Info("This will be recorded");
}

The resulting output from this advanced configuration will be a JSON object with properties related to each severity that has been recorded, and each of those properties will contain the trail messages. Here is an example of the output from the above configuration:

[{"Severity":"Info","Timestamp":"2025-10-08T18:17:53.3672505Z","Message":"This will be recorded"}]

If pretty-print was enabled on the ScribeJsonWriter object, the output would look like this:

[
  {
    "Severity": "Info",
    "Timestamp": "2025-10-08T18:18:23.3215959Z",
    "Message": "This will be recorded"
  }
]

Extensibility: Creating a Custom Writer

TrailScribe is easy to extend. You can create your own writer by implementing the IScribeWriter interface. This is useful for sending traces to a database, a message queue, or a third-party service.

1. Define the Interface:

   public interface IScribeWriter
   {
       Task WriteAsync(string message);
   }
   

2. Implement Your Writer:

   // A simple writer that writes trails to the debug output window.
   public class DebugOutputWriter : IScribeWriter
   {
       public Task WriteAsync(string message)
       {
           System.Diagnostics.Debug.WriteLine(message);
           return Task.CompletedTask;
       }
   }
   

3. Use it in the Configuration:

   Scribe scribe = new()
   {
       Writer = new DebugOutputWriter()
   };
   

Licensing

TrailScribe is provided free of charge for both personal and commercial use.

This software is proprietary and is not open source. You may not modify, decompile, or redistribute the source code without express written permission. For the full terms and conditions of use, please refer to the LICENSE file included in the NuGet package.

Feedback & Support

We welcome your feedback! For bug reports and feature requests, please open an issue on our GitHub Issues page.