Muscula.Csharp.Extensions.Logging 2.0.0

Muscula.Csharp.Extensions.Logging

Overview

Muscula.Csharp.Extensions.Logging is a .NET logging provider that integrates with Muscula - a comprehensive error logging and monitoring service for web applications and services. This package provides structured logging capabilities with built-in error tracking and analytics.

Features

• Structured Logging: Support for logging structured data along with messages
• Automatic Error Tracking: Seamlessly captures and reports exceptions
• Performance Optimized: Asynchronous message batching for minimal performance impact
• Severity Levels: Support for multiple log severity levels (Debug, Info, Warning, Error, Fatal)
• Stack Trace Parsing: Automatic parsing and formatting of exception stack traces
• Thread-Safe: Concurrent message queue processing

Installation

Install the package via NuGet:

dotnet add package Muscula.Csharp.Extensions.Logging

Or via Package Manager:

Install-Package Muscula.Csharp.Extensions.Logging

Quick Start

Basic Configuration

Configure Muscula logging in your Program.cs or Startup.cs:

services.AddLogging(builder => builder.AddMuscula(
    settingsBuilder =>
    {
        settingsBuilder.UseLogId("YOUR_MUSCULA_LOG_ID");
        return settingsBuilder.Build();
    }));

Using the Logger

Inject ILogger<T> into your classes:

public class MyService
{
    private readonly ILogger<MyService> _logger;

    public MyService(ILogger<MyService> logger)
    {
        _logger = logger;
    }

    public void DoWork()
    {
        _logger.LogInformation("Starting work");
        
        try
        {
            // Your code here
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Error occurred during work");
        }
    }
}

Structured Logging

For more detailed logging with structured data:

public class OrderService
{
    private readonly IMusculaStructuralLogger _structuralLogger;

    public OrderService(IMusculaStructuralLogger structuralLogger)
    {
        _structuralLogger = structuralLogger;
    }

    public void ProcessOrder(Order order)
    {
        _structuralLogger.LogStructural(
            Severity.Info,
            message: "Processing order",
            structuralData: new { OrderId = order.Id, Amount = order.Total },
            className: nameof(OrderService)
        );
    }
}

Configuration Options

The MusculaSettingsBuilder provides various configuration options:

services.AddLogging(builder => builder.AddMuscula(
    settingsBuilder =>
    {
        settingsBuilder
            .UseLogId("YOUR_LOG_ID")
            .UseUrl("https://custom.endpoint.com") // Optional
            .UseEnvironment("production")          // Optional
            .UseRelease("1.4.2")                   // Optional
            .UseMaxBatchSize(50)                   // Optional, default 50
            .UseMaxLingerMs(1000)                  // Optional, default 1000
            .UseChannelCapacity(10_000)            // Optional, default 10000
            .UseConsumerCount(1);                  // Optional, default 1
        return settingsBuilder.Build();
    }));

Delivery tuning

The shipper buffers logs in a bounded in-memory channel and a single background consumer ships them in batches. The consumer stays fully blocked (zero CPU) while there is nothing to send, and wakes the instant a log is enqueued.

Changelog

1.2.0

• Idle CPU eliminated. The background sender is now fully event-driven: a bounded System.Threading.Channels.Channel feeds a single consumer that blocks on the channel and consumes no CPU while idle, instead of the previous timer/polling loop. On an idle host the SDK's CPU contribution is effectively 0 (measured < 1 mvCPU), so Azure Container Apps replicas can return to the billed idle rate.
• Batching now uses a per-batch linger window (MaxLingerMs) that only exists while logs are pending - no permanent heartbeat.
• Bounded channel with drop-on-overflow (ChannelCapacity) so a log burst can never block callers or exhaust memory; dropped logs are counted in MusculaProvider.DroppedCount.
• Reused HttpClient over a pooled SocketsHttpHandler; send retries now use exponential backoff with jitter.
• Deterministic flush on host shutdown via a registered IHostedService; buffered logs are drained (bounded timeout) so shutdown does not lose logs.
• New tuning knobs: MaxBatchSize, MaxLingerMs, ChannelCapacity, ConsumerCount.
• The public API is unchanged: builder.Logging.AddMuscula(s => s.UseLogId(id).Build()) still works as before.

Requirements

• .NET 10.0 or higher
• Active Muscula account with valid Log ID

Support

For issues and questions:

• Visit Muscula Documentation
• Create an issue in the GitHub repository

License

This project is licensed under the MIT License - see the LICENSE file for details.