VanDerHeijden.Logging.MongoDb 10.1.1

VanDerHeijden.Logging.MongoDb

MongoDB log writer for VanDerHeijden.Logging.

Writes batched log entries to a MongoDB collection using an unordered InsertManyAsync, with structured properties stored as a queryable BSON subdocument.

Installation

dotnet add package VanDerHeijden.Logging.MongoDb

Usage

var mongoClient = new MongoClient("mongodb://localhost:27017");
var collection = mongoClient
    .GetDatabase("myapp")
    .GetCollection<BsonDocument>("logs");

builder.Logging.AddMongoDbLogger(collection, options => options.RetentionDays = 30);

Or from configuration, when an IMongoDatabase is registered in the DI container:

builder.Logging.AddMongoDbLogger();
builder.Services.AddMongoDbLogging(builder.Configuration);

{
  "MongoDb": {
    "Collections": { "Logs": "Logs" },
    "RetentionDays": 30
  }
}

Options

With both enabled a document holds the text twice: once formatted, and once as template plus Properties. Choose what you need:

Properties is always stored, and at least one of Message and MessageTemplate is always stored: an entry whose template is not stored (switched off, or the log call had none) keeps its Message even when StoreMessage is false. With StoreMessage = false and the template stored, the text is not formatted at all: the logging call skips the ToString() of every argument, which makes it several times cheaper for calls that carry objects.

In configuration the keys are MongoDb:StoreMessage, MongoDb:StoreMessageTemplate, MongoDb:BatchSize, MongoDb:MaxIdleMs and MongoDb:QueueCapacity.

The insert rate of the server, not the batch size, limits throughput: on the test machine about 4 000 documents per second with the four indexes, for batch sizes from 100 to 2 000. If the application logs faster than that in bursts, raise QueueCapacity so the burst is buffered instead of dropped: a burst of 100 000 entries with QueueCapacity = 200 000 was stored completely, about 30 seconds later.

Document

logger.LogInformation("Order {OrderId} count {Count} amount {Amount}", orderId, 42, 12.34m) is stored as:

{
  "_id": ObjectId("..."),
  "Timestamp": ISODate("2026-02-22T14:03:12.456Z"),
  "Level": "Information",
  "EventId": 0,
  "Category": "MyApp.Service",
  "Message": "Order 3fa85f64-... count 42 amount 12.34",
  "MessageTemplate": "Order {OrderId} count {Count} amount {Amount}",
  "Properties": { "OrderId": UUID("3fa85f64-..."), "Count": 42, "Amount": NumberDecimal("12.34") },
  "Path": "/api/orders",
  "Method": "POST",
  "ClientIp": "203.0.113.42"
}

EventName, Exception, Referer, UserAgent, SessionId and SessionGuid are added when set; fields that are null are not stored. Timestamp is UTC.

Properties

Property values are captured in ILogger.Log; the BSON document is built afterwards by the background writer, so the logging call stays cheap. The driver never receives a Dictionary<string, object?>, so an unusual argument type cannot make an insert fail. Objects are captured as a shallow clone: top-level members are frozen at log time, nested objects and collections are shared with the original until the batch is written.

Keys are sanitized: every . and a leading $ become _ ({user.name} is stored as user_name).

Query properties directly, e.g. { "Properties.Count": { $gt: 10 } } or { "Properties.Customer.Name": "Alice" }.

Inside an object the JSON types apply: a nested decimal becomes a Double and a nested Guid or DateTime a string. Pass such a value as its own template argument when you need the native BSON type. Nested keys are sanitized too.

Indexes

Created in the background at startup (a failure never blocks or breaks the application):

Changing RetentionDays replaces the Timestamp index with the new TTL.

Reliability

• Inserts are unordered (IsOrdered = false): one rejected document does not stop the rest of the batch.
• A retried batch reuses the documents it already built, so every entry keeps its _id and cannot be stored twice.
• The queue uses DropOldest by default: if MongoDB is unreachable or slower than the application logs, logging never blocks and the oldest buffered entries are discarded.

HTTP fields

The HTTP fields are populated automatically when IHttpContextAccessor is registered:

builder.Services.AddHttpContextAccessor();

Outside an HTTP context they are not stored in the document.

Upgrading

The collection type changed from IMongoCollection<LogEntry> to IMongoCollection<BsonDocument>, and the MongoDB-specific LogEntry class was removed in favour of the shared VanDerHeijden.Logging.LogEntry.

Repository

https://github.com/alphons/VanDerHeijden.Logging