dotnet-logging-configuration

.NET 向けロギング構成

概要

このスキルでは、Microsoft のベストプラクティスに従って構造化ロギングを構成します。

• ILogger - カテゴリーベースのロギング用にサービスへ注入します
• ILoggerFactory - 必要に応じてロガーを動的に作成します
• 構造化ロギング - 分析のためにログのプロパティを保持します
• ソースジェネレーター - コンパイル時ロギングによって高いパフォーマンスを実現します
• Serilog 連携 - シンクとエンリッチャーを拡張します

クイックリファレンス

インターフェイス	ライフタイム	使用例
ILogger<T>	シングルトン	標準的なサービスのロギング
ILoggerFactory	シングルトン	ロガーを動的に作成
ILogger	-	非ジェネリック（DI では使用しない）

---

ロギングの構造

/Infrastructure/Logging/
├── LoggerConfiguration.cs
├── LogEvents.cs           # LoggerMessage source generators
├── LogEnrichers/
│   ├── UserContextEnricher.cs
│   └── CorrelationIdEnricher.cs
└── Sinks/
    └── CustomSink.cs

---

テンプレート：ILogger を使用するサービス

// src/{name}.application/Services/OrderService.cs
using Microsoft.Extensions.Logging;

namespace {name}.application.services;

/// <summary>
/// Services should inject ILogger<T> for category-based logging.
/// The category is automatically set to the full type name.
/// </summary>
public sealed class OrderService : IOrderService
{
    private readonly ILogger<OrderService> _logger;
    private readonly IOrderRepository _orderRepository;

    public OrderService(
        ILogger<OrderService> logger,
        IOrderRepository orderRepository)
    {
        _logger = logger;
        _orderRepository = orderRepository;
    }

    public async Task<Result<Order>> ProcessOrderAsync(
        Guid orderId,
        CancellationToken cancellationToken)
    {
        // ═══════════════════════════════════════════════════════════════
        // STRUCTURED LOGGING - Use placeholders, not string interpolation
        // ═══════════════════════════════════════════════════════════════
        _logger.LogInformation(
            "Processing order {OrderId}",
            orderId);

        try
        {
            var order = await _orderRepository.GetByIdAsync(orderId, cancellationToken);

            if (order is null)
            {
                _logger.LogWarning(
                    "Order {OrderId} not found",
                    orderId);

                return Result.Failure<Order>(OrderErrors.NotFound(orderId));
            }

            // Log with multiple properties
            _logger.LogInformation(
                "Order {OrderId} retrieved. Status: {Status}, Total: {Total}",
                orderId,
                order.Status,
                order.Total);

            return Result.Success(order);
        }
        catch (Exception ex)
        {
            // Always log exceptions with the exception parameter first
            _logger.LogError(
                ex,
                "Error processing order {OrderId}",
                orderId);

            throw;
        }
    }
}

---

テンプレート：ILoggerFactory の使用

// src/{name}.infrastructure/Services/DynamicLoggerService.cs
using Microsoft.Extensions.Logging;

namespace {name}.infrastructure.services;

/// <summary>
/// Use ILoggerFactory when you need to create loggers dynamically.
/// Common use cases:
/// - Factory classes that create multiple types
/// - Plugin systems where type isn't known at compile time
/// - Base classes that want child-specific categories
/// </summary>
public sealed class PluginManager
{
    private readonly ILoggerFactory _loggerFactory;

    public PluginManager(ILoggerFactory loggerFactory)
    {
        _loggerFactory = loggerFactory;
    }

    public IPlugin LoadPlugin(string pluginName, Type pluginType)
    {
        // Create a logger with a dynamic category
        var logger = _loggerFactory.CreateLogger(pluginType);

        logger.LogInformation(
            "Loading plugin {PluginName} of type {PluginType}",
            pluginName,
            pluginType.Name);

        // Or with a string category
        var customLogger = _loggerFactory.CreateLogger($"Plugins.{pluginName}");

        customLogger.LogDebug(
            "Plugin {PluginName} initialized",
            pluginName);

        return CreatePlugin(pluginType, customLogger);
    }
}

---

テンプレート：ソースジェネレーターを使用した高パフォーマンスなロギング

// src/{name}.application/Logging/LogEvents.cs
using Microsoft.Extensions.Logging;

namespace {name}.application.logging;

/// <summary>
/// LoggerMessage source generators provide the best logging performance.
/// Benefits:
/// - Zero allocation for disabled log levels
/// - Compile-time validation of message templates
/// - Strongly typed parameters
/// </summary>
public static partial class LogEvents
{
    // ═══════════════════════════════════════════════════════════════
    // INFORMATION LEVEL
    // ═══════════════════════════════════════════════════════════════

    [LoggerMessage(
        EventId = 1000,
        Level = LogLevel.Information,
        Message = "Processing request {RequestName} with ID {RequestId}")]
    public static partial void LogRequestProcessing(
        this ILogger logger,
        string requestName,
        Guid requestId);

    [LoggerMessage(
        EventId = 1001,
        Level = LogLevel.Information,
        Message = "Request {RequestName} completed in {ElapsedMs}ms")]
    public static partial void LogRequestCompleted(
        this ILogger logger,
        string requestName,
        long elapsedMs);

    [LoggerMessage(
        EventId = 1002,
        Level = LogLevel.Information,
        Message = "User {UserId} authenticated successfully")]
    public static partial void LogUserAuthenticated(
        this ILogger logger,
        Guid userId);

    // ═══════════════════════════════════════════════════════════════
    // WARNING LEVEL
    // ═══════════════════════════════════════════════════════════════

    [LoggerMessage(
        EventId = 2000,
        Level = LogLevel.Warning,
        Message = "Slow request detected: {RequestName} took {ElapsedMs}ms")]
    public static partial void LogSlowRequest(
        this ILogger logger,
        string requestName,
        long elapsedMs);

    [LoggerMessage(
        EventId = 2001,
        Level = LogLevel.Warning,
        Message = "Cache miss for key {CacheKey}")]
    public static partial void LogCacheMiss(
        this ILogger logger,
        string cacheKey);

    [LoggerMessage(
        EventId = 2002,
        Level = LogLevel.Warning,
        Message = "Rate limit exceeded for client {ClientId}")]
    public static partial void LogRateLimitExceeded(
        this ILogger logger,
        string clientId);

    // ═══════════════════════════════════════════════════════════════
    // ERROR LEVEL
    // ═══════════════════════════════════════════════════════════════

    [LoggerMessage(
        EventId = 3000,
        Level = LogLevel.Error,
        Message = "Error processing request {RequestName}")]
    public static partial void LogRequestError(
        this ILogger logger,
        Exception exception,
        string requestName);

    [LoggerMessage(
        EventId = 3001,
        Level = LogLevel.Error,
        Message = "Database operation failed for entity {EntityType} with ID {EntityId}")]
    public static partial void LogDatabaseError(
        this ILogger logger,
        Exception exception,
        string entityType,
        Guid entityId);

    [LoggerMessage(
        EventId = 3002,
        Level = LogLevel.Error,
        Message = "External service {ServiceName} returned error: {ErrorCode}")]
    public static partial void LogExternalServiceError(
        this ILogger logger,
        string serviceName,
        string errorCode);

    // ═══════════════════════════════════════════════════════════════
    // DEBUG LEVEL
    // ═══════════════════════════════════════════════════════════════

    [LoggerMessage(
        EventId = 4000,
        Level = LogLevel.Debug,
        Message = "Executing query: {QueryName}")]
    public static partial void LogQueryExecution(
        this ILogger logger,
        string queryName);

    [LoggerMessage(
        EventId = 4001,
        Level = LogLevel.Debug,
        Message = "Cache hit for key {CacheKey}")]
    public static partial void LogCacheHit(
        this ILogger logger,
        string cacheKey);
}

ソース生成ログの使用

// src/{name}.application/Features/Orders/ProcessOrder/ProcessOrderHandler.cs
public sealed class ProcessOrderHandler : ICommandHandler<ProcessOrderCommand, Guid>
{
    private readonly ILogger<ProcessOrderHandler> _logger;

    public async Task<Result<Guid>> Handle(
        ProcessOrderCommand command,
        CancellationToken cancellationToken)
    {
        // Use extension method from LogEvents
        _logger.LogRequestProcessing("ProcessOrder", command.OrderId);

        var stopwatch = Stopwatch.StartNew();

        try
        {
            // ... process order ...

            stopwatch.Stop();
            _logger.LogRequestCompleted("ProcessOrder", stopwatch.ElapsedMilliseconds);

            return Result.Success(command.OrderId);
        }
        catch (Exception ex)
        {
            _logger.LogRequestError(ex, "ProcessOrder");
            throw;
        }
    }
}

---

テンプレート：Serilog の構成

// src/{name}.api/Program.cs
using Serilog;
using Serilog.Events;

var builder = WebApplication.CreateBuilder(args);

// ═══════════════════════════════════════════════════════════════
// SERILOG CONFIGURATION
// ═══════════════════════════════════════════════════════════════
Log.Logger = new LoggerConfiguration()
    .MinimumLevel.Information()
    .MinimumLevel.Override("Microsoft", LogEventLevel.Warning)
    .MinimumLevel.Override("Microsoft.Hosting.Lifetime", LogEventLevel.Information)
    .MinimumLevel.Override("Microsoft.EntityFrameworkCore", LogEventLevel.Warning)
    .Enrich.FromLogContext()
    .Enrich.WithMachineName()
    .Enrich.WithEnvironmentName()
    .Enrich.WithProperty("Application", "MyApp")
    .WriteTo.Console(outputTemplate:
        "[{Timestamp:HH:mm:ss} {Level:u3}] {Message:lj} {Properties:j}{NewLine}{Exception}")
    .WriteTo.File(
        path: "logs/log-.txt",
        rollingInterval: RollingInterval.Day,
        retainedFileCountLimit: 30,
        outputTemplate: "{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} [{Level:u3}] {Message:lj} {Properties:j}{NewLine}{Exception}")
    .CreateLogger();

builder.Host.UseSerilog();

// ... rest of configuration ...

var app = builder.Build();

// Request logging middleware
app.UseSerilogRequestLogging(options =>
{
    options.MessageTemplate = "HTTP {RequestMethod} {RequestPath} responded {StatusCode} in {Elapsed:0.0000}ms";
    options.EnrichDiagnosticContext = (diagnosticContext, httpContext) =>
    {
        diagnosticContext.Set("RequestHost", httpContext.Request.Host.Value);
        diagnosticContext.Set("UserAgent", httpContext.Request.Headers["User-Agent"].ToString());
    };
});

---

テンプレート：appsettings.json のロギング構成

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information",
      "Microsoft.EntityFrameworkCore": "Warning",
      "Microsoft.EntityFrameworkCore.Database.Command": "Warning"
    }
  },
  "Serilog": {
    "Using": ["Serilog.Sinks.Console", "Serilog.Sinks.File", "Serilog.Sinks.Seq"],
    "MinimumLevel": {
      "Default": "Information",
      "Override": {
        "Microsoft": "Warning",
        "Microsoft.EntityFrameworkCore": "Warning",
        "System": "Warning"
      }
    },
    "WriteTo": [
      {
        "Name": "Console",
        "Args": {
          "theme": "Serilog.Sinks.SystemConsole.Themes.AnsiConsoleTheme::Code, Serilog.Sinks.Console"
        }
      },
      {
        "Name": "File",
        "Args": {
          "path": "logs/log-.txt",
          "rollingInterval": "Day",
          "retainedFileCountLimit": 30
        }
      },
      {
        "Name": "Seq",
        "Args": {
          "serverUrl": "http://localhost:5341"
        }
      }
    ],
    "Enrich": ["FromLogContext", "WithMachineName", "WithEnvironmentName"],
    "Properties": {
      "Application": "MyApp"
    }
  }
}

---

テンプレート：相関 ID エンリッチャー

// src/{name}.infrastructure/Logging/CorrelationIdEnricher.cs
using Serilog.Core;
using Serilog.Events;

namespace {name}.infrastructure.logging;

/// <summary>
/// Enriches all logs with a correlation ID for request tracing.
/// </summary>
public sealed class CorrelationIdEnricher : ILogEventEnricher
{
    private readonly IHttpContextAccessor _httpContextAccessor;
    private const string CorrelationIdHeader = "X-Correlation-ID";
    private const string CorrelationIdProperty = "CorrelationId";

    public CorrelationIdEnricher(IHttpContextAccessor httpContextAccessor)
    {
        _httpContextAccessor = httpContextAccessor;
    }

    public void Enrich(LogEvent logEvent, ILogEventPropertyFactory propertyFactory)
    {
        var correlationId = GetCorrelationId();

        var property = propertyFactory.CreateProperty(CorrelationIdProperty, correlationId);
        logEvent.AddPropertyIfAbsent(property);
    }

    private string GetCorrelationId()
    {
        var context = _httpContextAccessor.HttpContext;

        if (context is null)
        {
            return Guid.NewGuid().ToString();
        }

        // Try to get from header first
        if (context.Request.Headers.TryGetValue(CorrelationIdHeader, out var headerValue))
        {
            return headerValue.ToString();
        }

        // Generate and store in context
        if (!context.Items.ContainsKey(CorrelationIdProperty))
        {
            context.Items[CorrelationIdProperty] = Guid.NewGuid().ToString();
        }

        return context.Items[CorrelationIdProperty]!.ToString()!;
    }
}

---

テンプレート：ユーザーコンテキストエンリッチャー

// src/{name}.infrastructure/Logging/UserContextEnricher.cs
using Serilog.Core;
using Serilog.Events;

namespace {name}.infrastructure.logging;

/// <summary>
/// Enriches logs with current user information.
/// </summary>
public sealed class UserContextEnricher : ILogEventEnricher
{
    private readonly IHttpContextAccessor _httpContextAccessor;

    public UserContextEnricher(IHttpContextAccessor httpContextAccessor)
    {
        _httpContextAccessor = httpContextAccessor;
    }

    public void Enrich(LogEvent logEvent, ILogEventPropertyFactory propertyFactory)
    {
        var context = _httpContextAccessor.HttpContext;

        if (context?.User.Identity?.IsAuthenticated != true)
        {
            return;
        }

        var userId = context.User.FindFirst("sub")?.Value
                  ?? context.User.FindFirst(ClaimTypes.NameIdentifier)?.Value;

        if (!string.IsNullOrEmpty(userId))
        {
            var property = propertyFactory.CreateProperty("UserId", userId);
            logEvent.AddPropertyIfAbsent(property);
        }

        var userName = context.User.Identity.Name;
        if (!string.IsNullOrEmpty(userName))
        {
            var property = propertyFactory.CreateProperty("UserName", userName);
            logEvent.AddPropertyIfAbsent(property);
        }
    }
}

---

テンプレート：依存性注入の登録

// src/{name}.infrastructure/DependencyInjection.cs
using Microsoft.Extensions.DependencyInjection;
using Serilog;

namespace {name}.infrastructure;

public static class DependencyInjection
{
    public static IServiceCollection AddInfrastructure(
        this IServiceCollection services,
        IConfiguration configuration)
    {
        // ═══════════════════════════════════════════════════════════════
        // LOGGING CONFIGURATION
        // ═══════════════════════════════════════════════════════════════
        services.AddLogging(loggingBuilder =>
        {
            loggingBuilder.ClearProviders();
            loggingBuilder.AddSerilog(dispose: true);
        });

        // Register enrichers
        services.AddSingleton<CorrelationIdEnricher>();
        services.AddSingleton<UserContextEnricher>();

        return services;
    }
}

---

テンプレート：BeginScope を使用したスコープ付きロギング

// src/{name}.application/Features/Orders/ProcessOrder/ProcessOrderHandler.cs
public sealed class ProcessOrderHandler : ICommandHandler<ProcessOrderCommand, Guid>
{
    private readonly ILogger<ProcessOrderHandler> _logger;

    public async Task<Result<Guid>> Handle(
        ProcessOrderCommand command,
        CancellationToken cancellationToken)
    {
        // ═══════════════════════════════════════════════════════════════
        // SCOPED LOGGING - All logs within scope include these properties
        // ═══════════════════════════════════════════════════════════════
        using (_logger.BeginScope(new Dictionary<string, object>
        {
            ["OrderId"] = command.OrderId,
            ["UserId"] = command.UserId,
            ["Operation"] = "ProcessOrder"
        }))
        {
            _logger.LogInformation("Starting order processing");

            // All logs within this scope automatically include OrderId, UserId, Operation
            await ValidateOrder(command);
            await CalculateTotals(command);
            await ProcessPayment(command);

            _logger.LogInformation("Order processing completed");
        }

        return Result.Success(command.OrderId);
    }
}

---

ログレベルのガイド

レベル	用途
Trace	詳細なデバッグ（本番環境では使用しない）
Debug	開発時のデバッグ
Information	全般的な処理の流れ、重要なイベント
Warning	想定外だが処理されたイベント
Error	対応が必要な失敗
Critical	即時対応が必要なシステム障害

---

重要なルール

1. 必ず ILogger を使用する - トレーサビリティのためにカテゴリーベースのロギングを行います
2. 構造化ロギングを使用する - 文字列補間ではなく、{Property} プレースホルダーを使用します
3. コンテキストを含める - 関連する ID やデータをログに追加します
4. 適切なレベルでログを記録する - 通常の処理の流れに Error を使用しないでください
5. ソースジェネレーターを使用する - 高パフォーマンスが求められるホットパスで使用します
6. 機密データをログに記録しない - パスワード、トークン、PII は含めないでください
7. 相関 ID を含める - サービス間でリクエストを追跡するために使用します
8. 名前空間ごとにレベルを構成する - フレームワークによるノイズを減らします
9. 操作にはスコープを使用する - 関連するログをまとめます
10. 例外は必ず最初の引数として渡す - メッセージ内に含めるのではなく、LogError(ex, "Message") のようにします

---

避けるべきアンチパターン

// ❌ WRONG: String interpolation
_logger.LogInformation($"Processing order {orderId}");

// ✅ CORRECT: Structured logging with placeholders
_logger.LogInformation("Processing order {OrderId}", orderId);

// ❌ WRONG: Logging sensitive data
_logger.LogInformation("User {Email} logged in with password {Password}", email, password);

// ✅ CORRECT: Redact sensitive data
_logger.LogInformation("User {Email} logged in", email);

// ❌ WRONG: Exception in message
_logger.LogError($"Error: {exception.Message}");

// ✅ CORRECT: Exception as first parameter
_logger.LogError(exception, "Error processing request");

// ❌ WRONG: Injecting ILoggerFactory when ILogger<T> suffices
public class OrderService
{
    private readonly ILogger _logger;
    public OrderService(ILoggerFactory factory)
    {
        _logger = factory.CreateLogger<OrderService>();  // Unnecessary!
    }
}

// ✅ CORRECT: Inject ILogger<T> directly
public class OrderService
{
    private readonly ILogger<OrderService> _logger;
    public OrderService(ILogger<OrderService> logger)
    {
        _logger = logger;
    }
}

// ❌ WRONG: Checking log level unnecessarily (with source generators)
if (_logger.IsEnabled(LogLevel.Debug))
{
    _logger.LogDebug("Value: {Value}", expensiveOperation());
}

// ✅ CORRECT: Source generators handle this automatically
_logger.LogQueryExecution("GetOrderById");  // No-op if Debug disabled

---

必要なパッケージ

# Core logging
dotnet add package Microsoft.Extensions.Logging

# Serilog (recommended)
dotnet add package Serilog.AspNetCore
dotnet add package Serilog.Sinks.Console
dotnet add package Serilog.Sinks.File
dotnet add package Serilog.Enrichers.Environment
dotnet add package Serilog.Enrichers.Process

# Optional: Centralized logging
dotnet add package Serilog.Sinks.Seq          # Seq server
dotnet add package Serilog.Sinks.Elasticsearch # Elasticsearch
dotnet add package Serilog.Sinks.ApplicationInsights # Azure

---

関連スキル

• 10-dotnet-pipeline-behaviors - すべてのリクエストに対するロギング動作
• 17-dotnet-health-checks - アプリケーションのモニタリング
• 01-dotnet-clean-architecture - 全体的なアーキテクチャ