Logging Module Overview

Try in Playground

Enterprise-grade structured logging with automatic PII masking, correlation IDs, environment-aware defaults, AWS X-Ray tracing, CloudWatch metrics, and multiple output targets. Drop-in replacement for ILogger<T>.

Why Use Primus Logging?

Standard logging lacks PII protection and cross-service correlation. Primus Logging provides automatic masking, context enrichment, and flexible targets all with zero changes to your existing ILogger<T> code.

Feature	Standard Logging	Primus Logging
PII Masking	Manual	Automatic
Correlation IDs	DIY	Built-in
Multiple Targets	Complex	Config-only
Structured Output	Varies	Consistent

---

Supported Destinations

Console

Colored, formatted output for development and debugging.

Pretty PrintStructured

Application Insights

Azure Monitor integration for cloud-native observability.

AzureTelemetry

File Output

Async buffered file output with rotation and compression.

AsyncRotationCompress

Serilog Bridge

Forward enriched logs to existing Serilog pipelines.

Bridge100+ Sinks

NLog Bridge

Forward enriched logs to existing NLog configurations.

BridgeDatabase

CloudWatch

AWS CloudWatch Logs, EMF metrics, X-Ray tracing, and audit routing.

AWSMetricsX-Ray

---

Result Object (LogEntry)

Each log entry contains enriched context:

Property	Type	Description
Timestamp	DateTime	When the log was created
Level	LogLevel	Debug, Info, Warning, Error, Critical
Message	string	Formatted message (PII masked)
Category	string	Logger category (class name)
CorrelationId	string	Request correlation ID
ApplicationId	string	Configured application name
Environment	string	Deployment environment
Properties	Dictionary	Structured data fields
Exception	ExceptionInfo?	Exception details if present

PII Masking Result

When PII masking is enabled, sensitive data is automatically replaced:

Original	Masked
user@example.com	u***@***.com
4111111111111111	************1111
123-45-6789	***-**-****

---

Log Levels

Level	Value	Use Case
Debug	0	Detailed diagnostics
Info	1	Operational messages
Warning	2	Unexpected but recoverable
Error	3	Non-fatal errors
Critical	4	Fatal errors

---

Target Options

Target	Configuration	Description
Console	{ "Type": "console", "Pretty": true }	Colored dev output
File	{ "Type": "file", "Path": "logs/app.log" }	File with rotation
Application Insights	{ "Type": "applicationInsights" }	Azure telemetry
Serilog	{ "Type": "serilog" }	Bridge to Serilog
NLog	{ "Type": "nlog" }	Bridge to NLog
CloudWatch	AddCloudWatchTarget(cw => { ... })	AWS CloudWatch Logs + EMF metrics

---

Next Steps

Want to...	See Guide
Log to console (dev)	Console
Send to Azure Monitor	Application Insights
Write to files	File Output
Use with Serilog	Serilog Bridge
Use with NLog	NLog Bridge
Send to AWS CloudWatch	CloudWatch
Advanced features	Advanced

---

Before You Begin — NuGet Feed Setup

PrimusSaaS.Logging is distributed via NuGet. If your organization uses a private feed, you need to register it first:

dotnet nuget add source https://your-feed-url/v3/index.json --name PrimusNuGet

Then install:

dotnet add package PrimusSaaS.Logging --version 1.5.0

Supports: .NET 8, 9, 10

If you're unsure of the feed URL, contact your Primus SaaS admin.

---

Service Registration

There are two extension-method families for registering Primus Logging. Both produce the same result — choose whichever fits your call site.

On ILoggingBuilder (preferred)

// Bind from IConfiguration section
builder.Logging.AddPrimus(builder.Configuration.GetSection("PrimusLogging"));

// Action delegate
builder.Logging.AddPrimus(opts => { opts.ApplicationId = "my-api"; });

// No-args (uses defaults)
builder.Logging.AddPrimus();

// IConfiguration + optional override
builder.Logging.AddPrimus(builder.Configuration.GetSection("PrimusLogging"), opts =>
{
    opts.MinimumLevel = LogLevel.Debug; // override one setting
});

AddPrimusLogging is an alias that forwards to the same registration:

builder.Logging.AddPrimusLogging(opts => { /* ... */ });
builder.Logging.AddPrimusLogging(); // defaults

On IServiceCollection

Use these overloads when you need to register logging from IServiceCollection directly, for example in a library or test host:

// Action delegate
builder.Services.AddPrimusLogging(opts => { opts.ApplicationId = "my-api"; });

// IConfiguration section + optional override
builder.Services.AddPrimusLogging(
    builder.Configuration.GetSection("PrimusLogging"),
    opts => { opts.MinimumLevel = LogLevel.Debug; });

Middleware

After builder.Build(), register the logging middleware:

var app = builder.Build();
app.UsePrimusLogging(); // Adds correlation ID propagation and request logging

tip

Call AddPrimus() / AddPrimusLogging() before builder.Build(). Call UsePrimusLogging() after builder.Build().

---

Common Mistakes to Avoid

Mistake	Fix
Calling app.UsePrimusLogging() before builder.Build()	Always call it after var app = builder.Build()
Skipping builder.Logging.ClearProviders()	This causes duplicate log output from default providers
Setting MinLevel too high in production	Start with 1 (Info) and adjust per environment
Leaving "Pretty": true in Docker/CI	Set "Pretty": false — ANSI colors break plain log aggregators