DotGenie.SoftwareHealthMonitoring 1.0.1

DotGenie.Monitoring

A comprehensive monitoring and logging library for .NET applications that provides easy integration with monitoring backends, health checks, error logging, and performance tracking.

🚀 Features

• Easy Integration - Add monitoring to any .NET 6+ application with just 3 lines of code
• Error Logging - Automatic exception capture with detailed context
• Performance Monitoring - Request duration tracking and performance metrics
• Health Checks - Built-in health monitoring for databases, APIs, and custom components
• Business Events - Track business-critical events and user actions
• Flexible Configuration - Extensive configuration options with sensible defaults
• Resilient - Built-in retry logic, circuit breaker, and fallback storage
• Generic - Works with any monitoring backend (Node.js, REST APIs, etc.)

📦 Installation

Install the NuGet package:

dotnet add package DotGenie.Monitoring

Or via Package Manager Console:

Install-Package DotGenie.Monitoring

🎯 Quick Start

1. Basic Setup

Add monitoring to your application with minimal configuration:

using DotGenie.Monitoring.Extensions;

var builder = WebApplication.CreateBuilder(args);

// Add monitoring services
builder.Services.AddMonitoring(options =>
{
    options.BaseUrl = "https://your-monitoring-api.com/api/";
    options.ServiceName = "MyWebAPI";
    options.Environment = builder.Environment.EnvironmentName;
});

var app = builder.Build();

// Use monitoring middleware
app.UseMonitoring();

app.Run();

2. Manual Logging

Inject and use the monitoring service anywhere in your application:

[ApiController]
[Route("api/[controller]")]
public class UsersController : ControllerBase
{
    private readonly IMonitoringService _monitoring;

    public UsersController(IMonitoringService monitoring)
    {
        _monitoring = monitoring;
    }

    [HttpPost]
    public async Task<IActionResult> CreateUser(CreateUserRequest request)
    {
        try
        {
            // Your business logic here
            var user = await CreateUserAsync(request);

            // Log business event
            await _monitoring.SendBusinessEventAsync("user-created", new
            {
                UserId = user.Id,
                Email = user.Email,
                RegistrationDate = user.CreatedAt
            });

            return Ok(user);
        }
        catch (ValidationException ex)
        {
            // Log error with category
            await _monitoring.SendErrorAsync("User validation failed", ex, "validation");
            return BadRequest(ex.Message);
        }
    }
}

⚙️ Configuration

Basic Configuration

builder.Services.AddMonitoring(options =>
{
    options.BaseUrl = "https://monitoring-api.com/api/";
    options.ServiceName = "MyService";
    options.Environment = "Production";
    options.Version = "1.2.3";
    
    // Feature toggles
    options.EnableErrorLogging = true;
    options.EnableHealthChecks = true;
    options.EnablePerformanceLogging = true;
    options.EnableBusinessEvents = true;
    
    // Performance settings
    options.RequestTimeout = TimeSpan.FromSeconds(30);
    options.SamplingRate = 1.0; // Log 100% of events
    
    // Paths to ignore
    options.IgnoredPaths.AddRange(new[] { "/swagger", "/metrics" });
});

Advanced Configuration with Fluent API

builder.Services.AddMonitoringBuilder()
    .WithOptions(options =>
    {
        options.BaseUrl = "https://monitoring-api.com/api/";
        options.ServiceName = "MyService";
    })
    .WithErrorLogging("api", "database", "security")
    .WithHealthChecks(TimeSpan.FromMinutes(2))
    .WithPerformanceLogging()
    .WithBusinessEvents()
    .WithSampling(0.1) // Sample 10% of requests
    .WithBatching(batchSize: 25, bufferTimeout: TimeSpan.FromSeconds(15))
    .WithFallbackStorage("/app/monitoring-logs")
    .Build();

Configuration from appsettings.json

{
  "Monitoring": {
    "BaseUrl": "https://monitoring-api.com/api/",
    "ServiceName": "MyWebAPI",
    "Environment": "Production",
    "EnableErrorLogging": true,
    "EnableHealthChecks": true,
    "EnablePerformanceLogging": false,
    "HealthCheckInterval": "00:05:00",
    "SamplingRate": 0.5,
    "IgnoredPaths": ["/health", "/ready", "/metrics"],
    "CustomHeaders": {
      "X-API-Key": "your-api-key",
      "X-Team": "backend"
    }
  }
}

Then bind the configuration:

builder.Services.Configure<MonitoringOptions>(
    builder.Configuration.GetSection("Monitoring"));
builder.Services.AddMonitoring();

📊 Monitoring Types

1. Error Logging

Automatically captures unhandled exceptions and HTTP errors:

// Manual error logging
await _monitoring.SendErrorAsync("Payment processing failed", exception, "payments");

// Automatic error capture via middleware
app.UseMonitoring(); // Catches all unhandled exceptions

2. Performance Monitoring

Track request performance and custom metrics:

// Manual performance logging
var stopwatch = Stopwatch.StartNew();
await ProcessOrderAsync(order);
stopwatch.Stop();

await _monitoring.SendPerformanceMetricAsync(
    "order_processing_time",
    stopwatch.ElapsedMilliseconds,
    "milliseconds",
    new { OrderId = order.Id, ItemCount = order.Items.Count }
);

// Automatic request performance via middleware
app.UseMonitoring(); // Tracks all HTTP request durations

3. Health Checks

Monitor the health of your dependencies:

// Manual health check
var isHealthy = await CheckDatabaseConnectionAsync();
await _monitoring.SendHealthCheckAsync(
    "database",
    isHealthy,
    TimeSpan.FromMilliseconds(150),
    new { ConnectionString = "***", QueryTime = "150ms" }
);

4. Business Events

Track important business activities:

// User registration
await _monitoring.SendBusinessEventAsync("user-registered", new
{
    UserId = user.Id,
    Email = user.Email,
    Source = "web",
    Plan = "premium"
}, "user-management");

// Order completion
await _monitoring.SendBusinessEventAsync("order-completed", new
{
    OrderId = order.Id,
    Amount = order.Total,
    PaymentMethod = order.PaymentMethod,
    ProcessingTime = processingTime
}, "orders");

5. General Logging

Log any information with different severity levels:

// Information
await _monitoring.SendInfoAsync("User login successful", new
{
    UserId = user.Id,
    LoginTime = DateTime.UtcNow,
    IpAddress = httpContext.Connection.RemoteIpAddress
});

// Warning
await _monitoring.SendWarningAsync("High memory usage detected", new
{
    MemoryUsage = "85%",
    Threshold = "80%"
});

// Debug
await _monitoring.SendDebugAsync("Cache miss for user profile", new
{
    UserId = userId,
    CacheKey = cacheKey
});

🔧 Middleware Options

Configure the monitoring middleware with additional options:

app.UseMonitoring(options =>
{
    options.CaptureRequestDetails = true;
    options.CaptureResponseDetails = false;
    options.MaxBodySize = 8192; // 8KB
    options.LogSuccessfulRequests = false;
    options.IncludeSensitiveHeaders = false;
    
    // Exclude specific headers
    options.ExcludedHeaders.Add("X-Internal-Token");
    
    // Exclude specific paths
    options.ExcludedPaths.Add("/internal/status");
    
    // Exclude sensitive query parameters
    options.ExcludedQueryParameters.Add("password");
});

🏥 Resilience Features

Circuit Breaker

Automatically stops sending logs when the monitoring service is down:

builder.Services.AddMonitoring(options =>
{
    options.CircuitBreakerFailureThreshold = 5; // Open after 5 failures
    options.CircuitBreakerRecoveryTimeout = TimeSpan.FromMinutes(2);
});

Fallback Storage

Store logs locally when the monitoring service is unavailable:

builder.Services.AddMonitoring(options =>
{
    options.EnableFallbackStorage = true;
    options.FallbackStorageDirectory = "/app/monitoring-fallback";
    options.FallbackRetryInterval = TimeSpan.FromMinutes(5);
});

Retry Logic

Automatically retry failed requests:

builder.Services.AddMonitoring(options =>
{
    options.MaxRetries = 3;
    options.RequestTimeout = TimeSpan.FromSeconds(30);
});

📈 Performance Optimization

Sampling

Reduce load by sampling a percentage of events:

builder.Services.AddMonitoring(options =>
{
    options.SamplingRate = 0.1; // Log only 10% of events
});

Batching

Send logs in batches for better performance:

builder.Services.AddMonitoring(options =>
{
    options.EnableBatching = true;
    options.BatchSize = 25;
    options.BufferTimeout = TimeSpan.FromSeconds(30);
});

Category Filtering

Enable only specific log categories:

builder.Services.AddMonitoring(options =>
{
    options.EnabledCategories = new List<string>
    {
        "errors",
        "security",
        "business"
    };
});

🔒 Security Considerations

• Sensitive Data: Be careful not to log sensitive information like passwords, API keys, or personal data
• Header Filtering: The library automatically excludes common sensitive headers like Authorization and Cookie
• Body Size Limits: Request/response bodies are limited to prevent large data logging
• Query Parameter Filtering: Sensitive query parameters are automatically excluded

📋 Log Format

All logs follow a standardized JSON format:

{
  "id": "guid",
  "timestamp": "2025-10-28T12:00:00.000Z",
  "type": "error|warning|info|debug|health_check|performance|business_event",
  "category": "database|api|health|application|security|performance|business",
  "service": "MyWebAPI",
  "environment": "Production",
  "version": "1.2.3",
  "message": "User creation failed",
  "details": {
    "userId": 123,
    "error": "Validation failed",
    "requestId": "req-123"
  },
  "metadata": {
    "server": "web-01",
    "processId": 1234,
    "threadId": 5678,
    "httpMethod": "POST",
    "path": "/api/users",
    "statusCode": 400,
    "duration": 150.5,
    "clientIp": "192.168.1.1"
  },
  "correlationId": "corr-456",
  "requestId": "req-123",
  "userId": "user-789"
}

🧪 Testing

The library is designed to be easily testable. Mock the IMonitoringService interface in your tests:

[Test]
public async Task CreateUser_LogsBusinessEvent()
{
    // Arrange
    var mockMonitoring = new Mock<IMonitoringService>();
    var controller = new UsersController(mockMonitoring.Object);

    // Act
    await controller.CreateUser(new CreateUserRequest());

    // Assert
    mockMonitoring.Verify(m => m.SendBusinessEventAsync(
        "user-created",
        It.IsAny<object>(),
        It.IsAny<string>()),
        Times.Once);
}

🔄 Migration from Internal Monitoring

If you're migrating from an internal monitoring solution:

1. Replace direct HTTP calls with IMonitoringService injection
2. Update configuration to use MonitoringOptions
3. Remove custom middleware and use app.UseMonitoring()
4. Standardize log formats using the provided constants and models

📚 API Reference

IMonitoringService Methods

Extension Methods

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

📄 License

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

🆘 Support

• Documentation: Full API documentation available in XML comments
• Issues: Report bugs and request features on GitHub Issues
• Discussions: Ask questions on GitHub Discussions

🗺️ Roadmap

• Add OpenTelemetry integration
• Support for structured logging providers (Serilog, NLog)
• Built-in dashboard for local development
• Kubernetes health check integration
• Metrics aggregation and alerting
• Support for additional .NET framework versions

Made with ❤️ by DotGenie