13 KiB

Raw Permalink Blame History

🔍 DramaLing 後端錯誤日誌監控指南

📋 目錄

錯誤日誌系統概覽
監控工具使用方法
常見錯誤類型和排查
實際使用案例
日誌級別說明
快速診斷檢查清單

🎯 錯誤日誌系統概覽

DramaLing 後端配備了完整的錯誤日誌系統，幫助開發者快速定位和解決問題。

✅ 已配置的功能

全域錯誤處理中介軟體：捕獲所有未處理的異常
詳細日誌配置：Debug 級別記錄
結構化日誌：包含請求詳情、堆疊追蹤
資料庫操作日誌：SQL 查詢和執行時間
認證流程日誌：完整的登入註冊追蹤

🗂️ 相關檔案

Middleware/ErrorHandlingMiddleware.cs - 全域錯誤處理
appsettings.json - 日誌配置
Controllers/AuthController.cs - 認證日誌
Program.cs - 中介軟體註冊

🛠️ 監控工具使用方法

1. 查看即時日誌

# 查看當前後端服務的所有日誌
BashOutput(bash_id: "33d454")

2. 過濾特定錯誤

# 只看錯誤和異常日誌
BashOutput(bash_id: "33d454", filter: "Error|Exception|fail")

# 只看認證相關日誌
BashOutput(bash_id: "33d454", filter: "Registration|Login|Auth")

# 只看資料庫錯誤
BashOutput(bash_id: "33d454", filter: "Database|DbCommand|Entity")

3. 監控特定功能

# 監控 JWT 相關問題
BashOutput(bash_id: "33d454", filter: "JWT|Token|Bearer")

# 監控模型驗證錯誤
BashOutput(bash_id: "33d454", filter: "ModelState|Validation")

4. 找出服務 ID

如果不知道當前的 bash_id，使用：

/bashes

然後找到運行 dotnet run --urls=http://localhost:5000 的服務 ID。

🚨 常見錯誤類型和排查

1. 認證錯誤

問題症狀：

用戶無法登入
JWT token 無效
401 Unauthorized 錯誤

排查方法：

BashOutput(bash_id: "33d454", filter: "Login attempt|Authentication|JWT|Bearer")

典型日誌：

info: Login attempt for email: user@example.com
warn: Bearer was not authenticated. Failure message: IDX10503: Signature validation failed
info: User logged in successfully: 4111625f-e44c-4878-8fd0-4377eed45f04

解決步驟：

檢查 JWT 密鑰配置
驗證 token 格式是否正確
確認用戶是否存在於資料庫

2. 資料庫錯誤

問題症狀：

註冊失敗
資料無法儲存
500 Internal Server Error

排查方法：

BashOutput(bash_id: "33d454", filter: "DbCommand|Database|EntityFramework")

典型日誌：

dbug: Executed DbCommand (2ms) [Parameters=[@__request_Email_0='test@example.com']]
      SELECT EXISTS (SELECT 1 FROM "user_profiles" WHERE "u"."email" = @__request_Email_0)
info: Database ensured created

解決步驟：

檢查資料庫檔案是否存在
驗證 SQL 查詢是否正確
確認資料庫連線字串

3. 模型驗證錯誤

問題症狀：

表單驗證失敗
400 Bad Request
密碼格式錯誤

排查方法：

BashOutput(bash_id: "33d454", filter: "ModelState|Validation|BadRequest")

典型日誌：

warn: Invalid model state for registration: {"Password": ["Password must be at least 8 characters"]}
dbug: The request has model state errors, returning an error response

解決步驟：

檢查前端表單驗證
確認後端模型註解
驗證請求格式

4. 應用程式異常

問題症狀：

系統崩潰
未預期的錯誤
堆疊溢出

排查方法：

BashOutput(bash_id: "33d454", filter: "Exception|fail:|error:")

典型日誌：

fail: Error during user registration
      System.InvalidOperationException: Unable to determine the relationship...
         at Microsoft.EntityFrameworkCore.Infrastructure.ModelValidator...

解決步驟：

查看完整堆疊追蹤
檢查相關程式碼
驗證依賴注入配置

📝 實際使用案例

案例 1：用戶註冊失敗排查

問題：前端註冊表單提交後返回 500 錯誤

排查步驟：

檢查認證日誌

BashOutput(bash_id: "33d454", filter: "Registration attempt")

查看詳細錯誤

BashOutput(bash_id: "33d454", filter: "Error during user registration")

檢查資料庫操作

BashOutput(bash_id: "33d454", filter: "INSERT INTO.*user_profiles")

可能的解決方案：

資料庫關聯配置錯誤
模型驗證失敗
密碼雜湊錯誤

案例 2：JWT Token 驗證失敗

問題：用戶登入後無法訪問受保護的端點

排查步驟：

查看 Token 生成

BashOutput(bash_id: "33d454", filter: "User logged in successfully")

檢查 Token 驗證

BashOutput(bash_id: "33d454", filter: "Bearer.*authenticated|Token.*validation")

查看認證失敗原因

BashOutput(bash_id: "33d454", filter: "Failed to validate the token")

可能的解決方案：

JWT 密鑰不匹配
Token 格式錯誤
Token 過期

案例 3：API 端點無回應

問題：API 請求沒有回應或超時

排查步驟：

檢查請求是否到達

BashOutput(bash_id: "33d454", filter: "Request starting.*POST.*register")

查看路由匹配

BashOutput(bash_id: "33d454", filter: "Route matched|Executing endpoint")

檢查異常處理

BashOutput(bash_id: "33d454", filter: "An unhandled exception occurred")

可能的解決方案：

路由配置錯誤
控制器異常
中介軟體問題

📊 日誌級別說明

Debug

目的：詳細的開發調試信息
內容：執行流程、參數值、內部狀態

例子：

dbug: Creating DbConnection.
dbug: Executed DbCommand (2ms) [Parameters=[@p0='value']]

Information

目的：重要的業務事件記錄
內容：正常操作、成功事件

例子：

info: User registered successfully: 4111625f-e44c-4878-8fd0-4377eed45f04
info: Application started. Press Ctrl+C to shut down.

Warning

目的：潛在問題警告
內容：不影響功能但需要注意的情況

例子：

warn: Failed to determine the https port for redirect.
warn: Invalid model state for registration

Error

目的：錯誤和異常記錄
內容：需要立即處理的問題

例子：

fail: Error during user registration
info: An unhandled exception occurred during request execution

🎯 快速診斷檢查清單

當遇到問題時，按以下順序檢查：

Step 1: 服務健康檢查

curl "http://localhost:5000/health"

預期結果：{"status":"Healthy","timestamp":"..."}

Step 2: 查看最新錯誤

BashOutput(bash_id: "33d454", filter: "Error|fail|Exception")

目的：快速找出最近發生的錯誤

Step 3: 檢查特定功能

根據問題類型選擇：

# 🔐 認證問題
BashOutput(bash_id: "33d454", filter: "Auth|Login|Register|JWT")

# 🗄️ 資料庫問題
BashOutput(bash_id: "33d454", filter: "Database|DbCommand|Entity")

# 📝 模型驗證問題
BashOutput(bash_id: "33d454", filter: "ModelState|Validation")

# 🌐 API 路由問題
BashOutput(bash_id: "33d454", filter: "Route|Endpoint")

Step 4: 深入分析

# 查看詳細追蹤
BashOutput(bash_id: "33d454", filter: "StackTrace|InnerException")

# 查看完整請求流程
BashOutput(bash_id: "33d454", filter: "Request starting.*POST")

💡 進階技巧

1. 組合過濾器

# 同時監控多個關鍵字
BashOutput(bash_id: "33d454", filter: "Error.*Auth|Exception.*User")

# 排除某些日誌
BashOutput(bash_id: "33d454", filter: "Error(?!.*Entity)")

2. 時間範圍分析

日誌包含精確時間戳，可以：

對比問題發生時間
追蹤請求處理時長
分析系統性能

3. 關聯分析

使用 TraceId 和 RequestId 追蹤單一請求的完整生命週期：

=> TraceId:8270820e8be6f0bdb0cc7ed6c8623004 => RequestId:0HNFL7QLPM33V:00000001

4. 即時監控

可以定期檢查日誌來監控系統健康狀況：

# 每隔一段時間檢查錯誤
BashOutput(bash_id: "33d454", filter: "Error|fail")

🔧 常用監控命令

日常監控

# 檢查服務狀態
curl "http://localhost:5000/health"

# 查看最新日誌
BashOutput(bash_id: "33d454")

# 只看錯誤
BashOutput(bash_id: "33d454", filter: "Error|Exception|fail")

功能測試

# 測試註冊功能
curl -X POST "http://localhost:5000/api/auth/register" \
  -H "Content-Type: application/json" \
  -d '{"username": "test", "email": "test@example.com", "password": "testpass123"}'

# 測試登入功能
curl -X POST "http://localhost:5000/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com", "password": "testpass123"}'

問題排查

# 檢查認證問題
BashOutput(bash_id: "33d454", filter: "Auth|Login|Register|JWT")

# 檢查資料庫問題
BashOutput(bash_id: "33d454", filter: "Database|DbCommand|SQL")

# 檢查 API 路由問題
BashOutput(bash_id: "33d454", filter: "Route|Endpoint|Controller")

📚 日誌範例解讀

成功註冊的日誌

info: Registration attempt for user: logtest, Email: logtest@example.com
dbug: Executed DbCommand (0ms) [Parameters=[@__request_Email_0='logtest@example.com']]
      SELECT EXISTS (SELECT 1 FROM "user_profiles" WHERE "u"."email" = @__request_Email_0)
dbug: Executed DbCommand (1ms) [Parameters=[@p0='4111625f-e44c-4878-8fd0-4377eed45f04', ...]]
      INSERT INTO "user_profiles" (Id, username, email, password_hash, ...)
info: User registered successfully: 4111625f-e44c-4878-8fd0-4377eed45f04

驗證錯誤的日誌

warn: Invalid model state for registration: {"Password": ["Password must be at least 8 characters"]}
dbug: The request has model state errors, returning an error response.
info: Executing BadRequestObjectResult, writing value of type 'ValidationProblemDetails'

系統異常的日誌

fail: Error during user registration
      System.InvalidOperationException: Unable to determine the relationship...
         at Microsoft.EntityFrameworkCore.Infrastructure.ModelValidator...
info: An unhandled exception occurred during request execution. Request: POST /api/auth/register

🎯 故障排除流程圖

問題發生
    ↓
檢查服務是否運行 (/health)
    ↓
查看最新錯誤日誌 (Error|Exception)
    ↓
根據錯誤類型選擇：
    ├─ 認證問題 → 檢查 Auth 日誌
    ├─ 資料庫問題 → 檢查 DbCommand 日誌
    ├─ 驗證問題 → 檢查 ModelState 日誌
    └─ 系統異常 → 檢查 StackTrace 日誌
    ↓
分析具體錯誤原因
    ↓
實施修復方案
    ↓
重新測試驗證

🚀 最佳實踐

1. 定期監控

每次部署後檢查日誌
定期查看錯誤趨勢
監控關鍵業務流程

2. 錯誤分類

緊急：系統崩潰、資料庫連線失敗
重要：認證失敗、API 異常
一般：驗證錯誤、業務邏輯問題

3. 日誌保存

重要錯誤日誌應該保存下來用於：

問題追蹤
性能分析
系統優化

📞 支援

如果遇到無法解決的問題：

收集信息：保存相關日誌
重現問題：記錄重現步驟
檢查環境：確認配置和依賴
尋求協助：提供完整的錯誤資訊

最後更新：2025-09-16 版本：v1.0 適用於：DramaLing .NET Core API Backend

13 KiB Raw Permalink Blame History Unescape Escape

🔍 DramaLing 後端錯誤日誌監控指南

📋 目錄

🎯 錯誤日誌系統概覽

✅ 已配置的功能

🗂️ 相關檔案

🛠️ 監控工具使用方法

1. 查看即時日誌

2. 過濾特定錯誤

3. 監控特定功能

4. 找出服務 ID

🚨 常見錯誤類型和排查

1. 認證錯誤

問題症狀：

排查方法：

典型日誌：

解決步驟：

2. 資料庫錯誤

問題症狀：

排查方法：

典型日誌：

解決步驟：

3. 模型驗證錯誤

問題症狀：

排查方法：

典型日誌：

解決步驟：

4. 應用程式異常

問題症狀：

排查方法：

典型日誌：

解決步驟：

📝 實際使用案例

案例 1：用戶註冊失敗排查

案例 2：JWT Token 驗證失敗

案例 3：API 端點無回應

📊 日誌級別說明

Debug

Information

Warning

Error

🎯 快速診斷檢查清單

Step 1: 服務健康檢查

Step 2: 查看最新錯誤

Step 3: 檢查特定功能

Step 4: 深入分析

💡 進階技巧

1. 組合過濾器

2. 時間範圍分析

3. 關聯分析

4. 即時監控

🔧 常用監控命令

日常監控

功能測試

問題排查

📚 日誌範例解讀

成功註冊的日誌

驗證錯誤的日誌

系統異常的日誌

🎯 故障排除流程圖

🚀 最佳實踐

1. 定期監控

2. 錯誤分類

3. 日誌保存

📞 支援

🔗 相關文檔

13 KiB

Raw Permalink Blame History