Traceability

💝 Support this project

If you find this project useful, consider supporting its development:

🤖 Get help with AI

Have questions about the API, implementation, or documentation? Ask DeepWiki, an AI agent that can help you understand and use Traceability.

---

NuGet package for automatic correlation-id management in .NET applications, with support for .NET Standard 2.0+ (core), .NET 8 (ASP.NET Core), and .NET Framework 4.8+ (ASP.NET Framework).

📖 Quick Start | User Manual | Complete Documentation | Examples

Indexed Documentation (Devin DeepWiki): DeepWiki for whitebeardit/traceability

Motivation

In distributed architectures and microservices, tracking a request across multiple services is essential for debugging, monitoring, and performance analysis. The correlation-id is a unique identifier that allows you to track a request from its origin to all subsequent calls.

When to use this library?

Use Traceability when you need:

1. Traceability in Microservices: Track a request across multiple services
2. Simplified Debugging: Quickly identify all logs related to a request
3. Performance Analysis: Measure total processing time across multiple services
4. Monitoring and Observability: Correlate metrics, traces, and logs from different services

Features

• ✅ Zero-code/Zero-config: Works automatically - just install the package!
• ✅ Automatic correlation-id management using AsyncLocal<string>
• ✅ Log correlation with distributed tracing via Activity.Current (when OpenTelemetry is configured externally)
• ✅ W3C Trace Context propagation (traceparent header) when trace context is available (best-effort)
• ✅ Portable core via .NET Standard 2.0 (works with .NET 6, 7, 8, and compatible frameworks)
• ✅ Full support for .NET 8.0 (ASP.NET Core with automatic middleware registration)
• ✅ Full support for .NET Framework 4.8+ (ASP.NET Web API and Traditional ASP.NET with automatic HttpModule registration)
• ✅ Zero-code for .NET Framework 4.8: Automatic registration via PreApplicationStartMethod
• ✅ Zero-config for .NET 8.0: Automatic middleware and HttpClient registration
• ✅ Middleware for ASP.NET Core (.NET 8)
• ✅ HttpModule and MessageHandler for ASP.NET (.NET Framework 4.8)
• ✅ Automatic integration with HttpClient
• ✅ Support for Serilog and Microsoft.Extensions.Logging
• ✅ Integration with Polly for resilience policies
• ✅ Automatic propagation in chained HTTP calls

Migration

• v3 migration (breaking): see docs/migration.md

Installation

dotnet add package WhiteBeard.Traceability

Quick Start

ASP.NET Core (.NET 8) - Zero Configuration

1. Install the package:

dotnet add package WhiteBeard.Traceability

2. Configure in Program.cs (just one line!):

using Traceability.Extensions; var builder = WebApplication.CreateBuilder(args); // Zero configuration - everything is automatic! // Source comes from TRACEABILITY_SERVICENAME or assembly name // Middleware is registered automatically // HttpClient is configured automatically builder.Services.AddTraceability(); builder.Services.AddControllers(); var app = builder.Build(); app.MapControllers(); app.Run();

With explicit Source (optional):

builder.Services.AddTraceability("MyService");

3. Use in a Controller:

using Microsoft.AspNetCore.Mvc; using Traceability; [ApiController] [Route("api/[controller]")] public class ValuesController : ControllerBase { [HttpGet] public IActionResult Get() { // Correlation-id is automatically available var correlationId = CorrelationContext.Current; return Ok(new { CorrelationId = correlationId }); } }

Result:

• ✅ Correlation-id automatically generated on each request (if not provided via X-Correlation-Id)
• ✅ Trace context can be propagated in HTTP calls (via traceparent) when OpenTelemetry is configured externally
• ✅ Automatically included in logs
• ✅ Returned in the X-Correlation-Id response header
• ✅ Compatible with OpenTelemetry-compatible observability tools (when OpenTelemetry is configured in the application)

ASP.NET Framework 4.8 - Zero Code

1. Install the package:

Install-Package WhiteBeard.Traceability

2. That's it! No code needed!

The library automatically:

• ✅ Registers CorrelationIdHttpModule via PreApplicationStartMethod
• ✅ Manages correlation-id automatically

Optional: Configure Serilog

// Global.asax.cs using Traceability.Extensions; using Serilog; protected void Application_Start() { Log.Logger = new LoggerConfiguration() .WithTraceability("MyService") .WriteTo.Console( outputTemplate: "[{Timestamp:HH:mm:ss} {Level:u3}] {Source} {CorrelationId} {Message:lj}{NewLine}{Exception}") .CreateLogger(); GlobalConfiguration.Configure(config => { config.MapHttpAttributeRoutes(); }); }

3. Use in a Controller:

using System.Web.Http; using Traceability; public class ValuesController : ApiController { [HttpGet] [Route("api/values")] public IHttpActionResult Get() { // Correlation-id is automatically available var correlationId = CorrelationContext.Current; return Ok(new { CorrelationId = correlationId }); } }

Result:

• ✅ Correlation-id automatically generated for each request
• ✅ Trace context can be propagated in HTTP calls (via traceparent) when OpenTelemetry is configured externally
• ✅ Automatically included in logs (if Serilog is configured)
• ✅ Returned in the X-Correlation-Id response header

Environment Variables

To reduce verbosity, you can use environment variables:

Linux/Mac:

export TRACEABILITY_SERVICENAME="UserService" export LOG_LEVEL="Information"

Windows PowerShell:

$env:TRACEABILITY_SERVICENAME="UserService" $env:LOG_LEVEL="Information"

With the environment variable defined, you can use:

// Source comes automatically from TRACEABILITY_SERVICENAME builder.Services.AddTraceability();

Documentation

• User Manual - Progressive guide for beginners
• Quick Start - Get started in minutes
• Installation - Installation guide
• Configuration - Detailed configuration options
• API Reference - Complete API documentation
• Examples - Practical examples
• Troubleshooting - Common problem solutions
• Advanced Topics - Advanced features

Quick Examples

With Logging

// Program.cs builder.Services.AddTraceability("MyService"); builder.Logging.AddConsole(options => options.IncludeScopes = true); // In Controller _logger.LogInformation("Processing request"); // Output: => CorrelationId: a1b2c3d4e5f6789012345678901234ab

With HttpClient

// Program.cs builder.Services.AddTraceability("MyService"); builder.Services.AddHttpClient("ExternalApi", client => { client.BaseAddress = new Uri("https://api.example.com/"); }); // In Controller var client = _httpClientFactory.CreateClient("ExternalApi"); // Correlation-id is automatically added to the header

Supported Frameworks

The package uses multi-targeting to provide the best experience for each platform:

• .NET Standard 2.0: Portable core library (CorrelationContext, HttpClient integration, Logging enrichers, Configuration)
  • Compatible with .NET 6, 7, 8, .NET Framework 4.6.1+, and other .NET Standard 2.0 implementations
  • Provides core functionality without framework-specific dependencies
• .NET 8.0: Full ASP.NET Core integration
  • Automatic middleware registration
  • Dependency injection extensions
  • HttpContext integration
• .NET Framework 4.8+: Full ASP.NET Framework integration
  • Automatic HttpModule registration via PreApplicationStartMethod
  • Web API and MVC support
  • System.Web integration

Note: The package automatically selects the appropriate implementation based on your target framework. Core functionality (correlation-id management, HttpClient propagation, logging) is available on all platforms via the .NET Standard 2.0 target.

Contributing

Contributions are welcome! Please open an issue or pull request.

For developers who want to contribute:

• CI/CD and Releases - Versioning and publishing process
• Technical Documentation - Complete architecture and technical guide

License

MIT