從零散文本到關聯可觀測性：Serilog與OpenTelemetry重塑.NET應用調試體驗

作者：架構師老盧 2025-10-14 02:45:00

Serilog + OpenTelemetry不僅僅是更好的日志記錄——它是一種可觀測性，改變了您理解和調試.NET應用程序的方式。

適用于現代.NET應用程序的Serilog和OpenTelemetry架構

當您的.NET應用程序在生產環境凌晨3點拋出一個難以理解的錯誤時，您最不愿意做的事情就是翻閱成千上萬的非結構化日志文件，試圖拼湊出問題所在。傳統的日志記錄感覺就像大海撈針——不同的是，這個"草堆"可能正在著火，而且那根"針"甚至可能不存在。

Serilog和OpenTelemetry登場：這對強力組合將日志記錄從一種必要的麻煩轉變為理解分布式系統的秘密武器。

傳統日志記錄與結構化日志記錄對比

傳統日志記錄的問題

想象一下：您的微服務架構橫跨15個不同的服務，每個服務都像這樣輸出日志：

2025-09-10 14:32:17 INFO: Processing request for user John
2025-09-10 14:32:18 ERROR: Database timeout occurred
2025-09-10 14:32:19 INFO: Retrying operation

現在回答這些問題：

? 哪個用戶觸發了錯誤？

? 原始請求是什么？

? 哪個服務實際失敗了？

? 整個請求花了多長時間？

使用傳統日志記錄，您就像在用不完整的證據進行偵探工作。

為什么Serilog + OpenTelemetry是游戲規則改變者

使用Serilog進行結構化日志記錄

Serilog不是轉儲文本，而是創建機器可以理解的結構化數據：

// 傳統方式（不佳）
_logger.LogInformation($"User {userId} ordered {itemCount} items for ${totalAmount}");

// Serilog結構化方式（佳）
_logger.LogInformation("User {UserId} completed order {OrderId} with {ItemCount} items for {TotalAmount:C}", 
    userId, orderId, itemCount, totalAmount);

這會生成如下所示的JSON：

{
  "timestamp":"2025-09-10T14:32:17.123Z",
"level":"Information",
"messageTemplate":"User {UserId} completed order {OrderId} with {ItemCount} items for {TotalAmount:C}",
"message":"User john.doe completed order ORD-12345 with 3 items for $299.99",
"properties":{
    "UserId":"john.doe",
    "OrderId":"ORD-12345",
    "ItemCount":3,
    "TotalAmount":299.99
}
}

現在您可以查詢："顯示所有超過200美元的訂單"或"查找用戶john.doe的所有錯誤"。

OpenTelemetry：缺失的一環

OpenTelemetry添加了關聯層，連接整個分布式系統中的日志。每條日志都會自動豐富以下信息：

? TraceId：跨所有服務跟蹤單個用戶請求

? SpanId：標識該請求中的特定操作

? 服務上下文：哪個服務、版本和環境

設置這對強力組合

步驟1：安裝所需的NuGet包

dotnet add package Serilog.AspNetCore
dotnet add package Serilog.Sinks.OpenTelemetry
dotnet add package OpenTelemetry.Extensions.Hosting
dotnet add package OpenTelemetry.Instrumentation.AspNetCore
dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol

步驟2：配置您的Program.cs

以下是提供具有完整可觀測性的結構化日志記錄的完整設置：

using Serilog;
using OpenTelemetry.Logs;
using OpenTelemetry.Metrics;
using OpenTelemetry.Trace;

// 首先配置Serilog
Log.Logger = new LoggerConfiguration()
    .MinimumLevel.Information()
    .MinimumLevel.Override("Microsoft.AspNetCore", LogEventLevel.Warning)
    .Enrich.FromLogContext()
    .Enrich.WithProperty("Application", "YourAppName")
    .Enrich.WithProperty("Environment", Environment.GetEnvironmentVariable("ASPNETCORE_ENVIRONMENT"))
    .WriteTo.Console(new JsonFormatter()) // 結構化控制臺輸出
    .WriteTo.OpenTelemetry(options =>
    {
        options.Endpoint = "http://localhost:4317"; // OTLP端點
        options.Protocol = OtlpProtocol.Grpc;
        options.ResourceAttributes = new Dictionary<string, object>
        {
            ["service.name"] = "your-service-name",
            ["service.version"] = "1.0.0"
        };
    })
    .CreateLogger();

var builder = WebApplication.CreateBuilder(args);

// 使用Serilog進行日志記錄
builder.Host.UseSerilog();

// 配置OpenTelemetry
builder.Services.AddOpenTelemetry()
    .WithTracing(tracing => tracing
        .AddAspNetCoreInstrumentation()
        .AddHttpClientInstrumentation()
        .AddEntityFrameworkCoreInstrumentation() // 如果使用EF Core
        .AddOtlpExporter(options =>
        {
            options.Endpoint = new Uri("http://localhost:4317");
        }))
    .WithMetrics(metrics => metrics
        .AddAspNetCoreInstrumentation()
        .AddHttpClientInstrumentation()
        .AddOtlpExporter(options =>
        {
            options.Endpoint = new Uri("http://localhost:4317");
        }));

var app = builder.Build();

// 添加請求日志記錄中間件
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("RequestScheme", httpContext.Request.Scheme);
        diagnosticContext.Set("UserAgent", httpContext.Request.Headers["User-Agent"].FirstOrDefault());
        // 添加自定義業務上下文
        if (httpContext.User.Identity.IsAuthenticated)
        {
            diagnosticContext.Set("UserId", httpContext.User.FindFirst("sub")?.Value);
        }
    };
});

app.Run();

步驟3：設置OpenTelemetry Collector

創建docker-compose.yml以運行本地可觀測性堆棧：

version: '3.8'
services:
# OpenTelemetry Collector
otel-collector:
    image:otel/opentelemetry-collector-contrib:latest
    container_name:otel-collector
    command: ["--config=/etc/otel-collector-config.yaml"]
    volumes:
      -./otel-collector-config.yaml:/etc/otel-collector-config.yaml
    ports:
      -"4317:4317"   # OTLP gRPC接收器
      -"4318:4318"   # OTLP HTTP接收器
      -"8889:8889"   # Prometheus指標
    depends_on:
      -jaeger
      -prometheus

# Jaeger用于追蹤
jaeger:
    image:jaegertracing/all-in-one:latest
    container_name:jaeger
    ports:
      -"16686:16686"
      -"14250:14250"
    environment:
      -COLLECTOR_OTLP_ENABLED=true

# Prometheus用于指標
prometheus:
    image:prom/prometheus:latest
    container_name:prometheus
    ports:
      -"9090:9090"
    volumes:
      -./prometheus.yml:/etc/prometheus/prometheus.yml

# Grafana用于可視化
grafana:
    image:grafana/grafana:latest
    container_name:grafana
    ports:
      -"3000:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin

創建otel-collector-config.yaml：

receivers:
  otlp:
    protocols:
      grpc:
        endpoint:0.0.0.0:4317
      http:
        endpoint:0.0.0.0:4318

processors:
batch:
    timeout:1s
    send_batch_size:1024
resource:
    attributes:
      -key:environment
        value:development
        action:upsert

exporters:
# 將追蹤導出到Jaeger
jaeger:
    endpoint:jaeger:14250
    tls:
      insecure:true

# 將指標導出到Prometheus
prometheus:
    endpoint:"0.0.0.0:8889"

# 將日志導出到控制臺（您可以在此處添加Loki）
logging:
    loglevel:debug

service:
pipelines:
    traces:
      receivers: [otlp]
      processors: [batch, resource]
      exporters: [jaeger]
    metrics:
      receivers: [otlp]
      processors: [batch, resource]
      exporters: [prometheus]
    logs:
      receivers: [otlp]
      processors: [batch, resource]
      exporters: [logging]

啟動堆棧：

docker-compose up -d

高級日志記錄模式

1. 使用作用域的上下文日志記錄

添加強制應用于作用域內所有日志的業務上下文：

public classOrderService
{
    privatereadonly ILogger<OrderService> _logger;

    public async Task ProcessOrderAsync(int orderId, string userId)
    {
        // 創建帶有上下文的日志記錄作用域
        usingvar scope = _logger.BeginScope(new Dictionary<string, object>
        {
            ["OrderId"] = orderId,
            ["UserId"] = userId,
            ["Operation"] = "ProcessOrder"
        });

        _logger.LogInformation("Starting order processing");

        try
        {
            await ValidateOrderAsync(orderId);
            await ChargePaymentAsync(orderId);
            await FulfillOrderAsync(orderId);
            _logger.LogInformation("Order processing completed successfully");
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Order processing failed");
            throw;
        }
    }
}

此作用域內的每條日志都會自動包含OrderId、UserId和Operation。

2. 用于業務上下文的自定義擴展器

創建添加一致業務上下文的擴展器：

public classTenantEnricher : ILogEventEnricher
{
    privatereadonly IHttpContextAccessor _contextAccessor;

    public TenantEnricher(IHttpContextAccessor contextAccessor)
    {
        _contextAccessor = contextAccessor;
    }

    public void Enrich(LogEvent logEvent, ILogEventPropertyFactory propertyFactory)
    {
        var context = _contextAccessor.HttpContext;
        if (context?.User?.Identity?.IsAuthenticated == true)
        {
            var tenantId = context.User.FindFirst("tenant_id")?.Value;
            if (!string.IsNullOrEmpty(tenantId))
            {
                logEvent.AddOrUpdateProperty(propertyFactory.CreateProperty("TenantId", tenantId));
            }
        }
    }
}

// 在Program.cs中注冊
builder.Services.AddSingleton<IHttpContextAccessor, HttpContextAccessor>();
Log.Logger = new LoggerConfiguration()
    .Enrich.With<TenantEnricher>()
    // ... 其他配置
    .CreateLogger();

3. 性能關鍵的日志記錄

對于高吞吐量場景，使用源生成的日志記錄：

public partialclassOrderService
{
    privatereadonly ILogger<OrderService> _logger;

    [LoggerMessage(
        EventId = 1001,
        Level = LogLevel.Information,
        Message = "Processing order {OrderId} for user {UserId} with {ItemCount} items totaling {TotalAmount:C}")]
    public static partial void LogOrderProcessing(ILogger logger, int orderId, string userId, int itemCount, decimal totalAmount);

    [LoggerMessage(
        EventId = 1002,
        Level = LogLevel.Error,
        Message = "Failed to process order {OrderId}: {ErrorReason}")]
    public static partial void LogOrderProcessingError(ILogger logger, Exception exception, int orderId, string errorReason);

    public async Task ProcessOrderAsync(Order order)
    {
        LogOrderProcessing(_logger, order.Id, order.UserId, order.Items.Count, order.TotalAmount);

        try
        {
            // 處理訂單...
        }
        catch (Exception ex)
        {
            LogOrderProcessingError(_logger, ex, order.Id, ex.Message);
            throw;
        }
    }
}

這會生成零分配的日志記錄代碼，以實現最佳性能。

生產環境最佳實踐

1. 安全和敏感數據

切勿記錄敏感信息。使用Serilog的解構策略來清理數據：

public classSensitiveDataPolicy : IDestructuringPolicy
{
    public bool TryDestructure(object value, ILogEventPropertyValueFactory propertyValueFactory, out LogEventPropertyValue result)
    {
        result = null;

        if (valueis CreditCard card)
        {
            result = propertyValueFactory.CreatePropertyValue(new
            {
                Last4Digits = card.Number?.Substring(card.Number.Length - 4),
                ExpiryMonth = card.ExpiryMonth,
                ExpiryYear = card.ExpiryYear
                // 切勿記錄完整號碼或CVV
            });
            returntrue;
        }

        returnfalse;
    }
}

Log.Logger = new LoggerConfiguration()
    .Destructure.With<SensitiveDataPolicy>()
    // ... 其他配置
    .CreateLogger();

2. 特定環境配置

為每個環境使用不同的日志記錄配置：

public static void ConfigureLogging(WebApplicationBuilder builder)
{
    var environment = builder.Environment.EnvironmentName;

    var loggerConfig = new LoggerConfiguration()
        .ReadFrom.Configuration(builder.Configuration);

    if (environment == "Development")
    {
        loggerConfig
            .MinimumLevel.Debug()
            .WriteTo.Console(new JsonFormatter());
    }
    elseif (environment == "Production")
    {
        loggerConfig
            .MinimumLevel.Information()
            .MinimumLevel.Override("Microsoft", LogEventLevel.Warning)
            .WriteTo.OpenTelemetry(options =>
            {
                options.Endpoint = builder.Configuration["OpenTelemetry:Endpoint"];
                options.Headers = GetAuthHeaders(builder.Configuration);
            });
    }

    Log.Logger = loggerConfig.CreateLogger();
}

3. 性能監控

監控日志記錄性能以避免影響應用程序性能：

// 添加用于監控日志記錄性能的指標
publicclassLoggingMetrics
{
    privatereadonly Counter<long> _logEventsCounter;
    privatereadonly Histogram<double> _logProcessingDuration;

    public LoggingMetrics(IMeterFactory meterFactory)
    {
        var meter = meterFactory.Create("MyApp.Logging");
        _logEventsCounter = meter.CreateCounter<long>("log_events_total");
        _logProcessingDuration = meter.CreateHistogram<double>("log_processing_duration_ms");
    }

    public void RecordLogEvent(LogEventLevel level)
    {
        _logEventsCounter.Add(1, new KeyValuePair<string, object>("level", level.ToString()));
    }
}

常見陷阱及如何避免

1. 過度記錄

問題：記錄所有內容會導致噪音和成本增加。
解決方案：使用適當的日志級別并按命名空間配置最低級別：

.MinimumLevel.Information()
.MinimumLevel.Override("Microsoft.AspNetCore", LogEventLevel.Warning)
.MinimumLevel.Override("Microsoft.EntityFrameworkCore", LogEventLevel.Error)

2. 阻塞應用程序線程

問題：同步日志記錄會降低應用程序速度。
解決方案：使用異步接收器和批處理：

.WriteTo.Async(a => a.OpenTelemetry(options =>
{
    options.Endpoint = "http://localhost:4317";
    options.BatchingOptions = new BatchingOptions
    {
        BatchSizeLimit = 1000,
        Period = TimeSpan.FromSeconds(2)
    };
}))

3. 缺失關聯上下文

問題：跨服務邊界的日志未正確關聯。
解決方案：確保HTTP調用中的TraceId傳播：

builder.Services.AddHttpClient<ExternalApiClient>(client =>
{
    client.BaseAddress = new Uri("https://api.external.com");
})
.AddHttpMessageHandler<CorrelationIdHandler>();

publicclassCorrelationIdHandler : DelegatingHandler
{
    protected override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
    {
        var activity = Activity.Current;
        if (activity != null)
        {
            request.Headers.Add("X-Correlation-ID", activity.TraceId.ToString());
        }
        returnawaitbase.SendAsync(request, cancellationToken);
    }
}

監控和告警

在結構化日志上設置告警：

# Prometheus的示例告警規則
groups:
-name:application.alerts
    rules:
      -alert:HighErrorRate
        expr:rate(log_events_total{level="Error"}[5m])>0.1
        for:2m
        labels:
          severity:warning
        annotations:
          summary:"檢測到高錯誤率"
          description:"錯誤率為每秒 {{ $value }} 個錯誤"
      -alert:DatabaseErrors
        expr:increase(log_events_total{level="Error",logger=~".*Repository.*"}[1m])>5
        for:1m
        labels:
          severity:critical
        annotations:
          summary: "檢測到數據庫錯誤激增"

結果：前后對比

方面	之前（傳統）	之后（Serilog + OpenTelemetry）
調試時間	數小時的日志搜索	幾分鐘的結構化查詢
跨服務追蹤	手動關聯	通過TraceId自動關聯
查詢能力	文本搜索/grep	豐富的結構化查詢
告警	日志量閾值	業務邏輯告警
性能影響	可變	可預測且優化
團隊效率	個人偵探工作	協作式可觀測性

入門清單

? 安裝Serilog和OpenTelemetry包

? 配置具有JSON輸出的結構化日志記錄

? 使用Docker設置OpenTelemetry Collector

? 為您的業務領域添加上下文擴展器

? 按環境配置不同的日志級別

? 實現敏感數據過濾

? 設置基本告警規則

? 培訓團隊進行結構化查詢

核心要點

Serilog + OpenTelemetry不僅僅是更好的日志記錄——它是一種可觀測性，改變了您理解和調試.NET應用程序的方式。

當凌晨3點的警報響起時，您將擁有：

? 可以立即查詢的結構化數據

? 跨所有服務的完整關聯

? 講述完整故事的豐富上下文

? 與日志并行的性能指標

責任編輯：武曉燕來源：架構師老盧