深度技術解析：Serilog 結構化日誌架構指南

SOURCE

• 來源：Medium
• 標題：How Structured Logging With Serilog Can Make Your Life Easier
• 作者：Mori

NAPKIN

純文字日誌如同考古，結構化日誌（Structured Logging）如同鑑識科學。本文探討在 .NET 10 專案中引入 Serilog 的完整生產環境架構，從基本設定到進階的 Context Enricher，最終整合 Seq 查詢與 OpenTelemetry 進行全鏈路追蹤，大幅降低系統故障排除的難度。

ROUND 1: 核心概念 (Core Concepts)

• 結構化日誌的本質：傳統日誌僅產生人類可讀的字串；結構化日誌將屬性（Properties）保存為一等公民的鍵值對（Key-Value Data），直接輸出為 JSON 格式，便於查詢與分析。
• Serilog 的核心管線：MinimumLevel（等級控制）、Enrichers（上下文擴充）、Filters（降噪過濾）、Sinks（輸出目標）。
• 可觀測性演進：從本機 console / file 記錄，走向 Seq 集中式結構化日誌伺服器，並展望 OpenTelemetry 以統一整合 Logs, Traces 與 Metrics。

ROUND 2: 架構與實作 (Architecture & Implementation)

• 套件依賴架構：依賴 Serilog.AspNetCore 及多個 Sinks（Console, File, Seq, OpenTelemetry）與 Enrichers（Environment, Process, Exception 等）。
• 日誌屬性擴充 (Enrichment)：
  • LogContext.PushProperty 用於生命週期範圍（Scope）內的上下文。
  • 自定義 Enricher 用於全域業務屬性（例如：TenantId, TimingBucket, UserAgent）。
  • 自動遮蔽敏感資料：利用 Serilog.Enrichers.SensitiveData 避免密碼或個資外洩。
• 反模式 (Anti-Patterns)：
  • 禁止使用字串插值（String Interpolation, 如 $"User {id}"），破壞了 Message Template 的結構性。
  • 禁止在緊密迴圈（Tight Loops）內進行大量 Log 記錄，應採用聚合方式。

ROUND 3: 查詢與觀測 (Querying & Observability)

• Seq 的進階查詢應用：
  • 找尋特定使用者錯誤：@Message like '%failed%' and UserId = '...'
  • 端點效能平均回應時間：select mean(Elapsed) from stream group by RequestPath
  • 分時統計錯誤率：select count(*) from stream where @Level = 'Error' group by time(1h)
• OpenTelemetry 架構整合：
  • 透過 gRPC 將日誌拋送至 OTLP 端點。
  • Collector 管線可以將日誌轉送至 Loki，指標送至 Prometheus。

DEEP READ: Architectural Deep Dive

前言

對於現代分散式系統而言，排查生產環境問題的難度呈指數級上升。凌晨三點的系統異常不能依賴正則表達式（Regex）去解析龐大的字串牆。本文從首席架構師的視角，拆解 Serilog 在 .NET 10 下的最佳實踐，剖析如何將日誌從「字串」轉換為「關聯式可查詢數據」。

章節詳細總結

1. 傳統 vs 結構化日誌差異

• 傳統方式：_logger.LogError("Order {OrderId} failed for user {Email}", orderId, email);，屬性被鑲嵌在字串中。
• 結構化方式：

_logger.LogError("Order failed for user {Email}", email, 
    new { OrderId = orderId, ErrorCode = "PAYMENT_FAILED", RetryCount = 3 });

輸出結果為機器友好的 JSON，使得後續查詢可以下達類似 SELECT OrderId FROM logs WHERE Email = 'john@example.com' 的精確指令。

2. Serilog Pipeline 生產級配置

架構配置採用 Fluent API，劃分為四大責任區：

• MinimumLevel：覆寫 Microsoft 預設日誌，降低雜訊（設為 Warning）。
• Enrich：注入機器名稱、執行緒 ID、關聯 ID，並使用 WithSensitiveDataMasking 遮蔽 Password, CreditCard。
• Filter：透過條件過濾（例如排除健康檢查的 Info 日誌）。
• WriteTo (Sinks)：
  • Console：開發友好的格式化輸出。
  • File：以 CompactJsonFormatter 落檔，設定 100MB 滾動策略。
  • Seq：傳送至集中式查詢引擎。
  • OpenTelemetry：將日誌透過 gRPC (OTLP) 送往統一收集器。

3. 業務上下文注入 (Custom Enrichers)

架構師往往需要將技術日誌與業務維度結合，實作自定義 ILogEventEnricher：

• TenantEnricher：從 HTTP Header X-Tenant-ID 或 JWT 取出多租戶 ID，注入每筆日誌。
• TimingBucketEnricher：將 Elapsed 時間依據區間分桶（Bucket, 例如 <10ms, 50-100ms），大幅提升 Seq 或 Kibana 在效能分佈圖表上的查詢效率。

4. OTel 與基礎設施整合

# OpenTelemetry Collector Config 範例
receivers: [otlp]
processors: [batch]
exporters: [loki] # 將日誌導出至 Loki

Serilog 無縫橋接 OpenTelemetry，讓 Logs、Metrics、Traces 共用同一個資源屬性（Resource Attributes），如 service.name 和 deployment.environment，實現真正的全鏈路可觀測性。

5. 最佳實踐與防呆機制

• 必須使用 Message Templates：讓 Serilog 可以解析並快取模板。
• 選擇性解構 (Destructuring)：使用 {@Object} 記錄複雜結構，但需注意大型物件的效能開銷。
• 善用 Scope 關聯：使用 _logger.BeginScope 將 OrderId 綁定，內部呼叫鏈上的所有日誌皆自動具備該屬性，不需在每個方法簽章傳遞參數。

總結與結論

在五分鐘內除錯與在五小時內除錯，其核心差異在於日誌的「可搜尋性（Searchability）」。結構化日誌並非進階的奢侈品，而是分散式系統可觀測性的絕對基礎。透過 Serilog、Seq 以及 OpenTelemetry 的強大組合，我們能建立一個可量化、可追蹤、且保護隱私資料的現代化基礎架構日誌體系。架構師應在 Day 1 就將此規範內建至開發框架中，從源頭確保日誌的結構完整性與查詢效能。