docs: 新增後端錯誤日誌監控指南
- 完整的錯誤日誌使用教學 - 常見問題排查流程 - 監控工具使用方法 - 實際案例分析 - 快速診斷檢查清單 - 最佳實踐建議 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
parent
e5cb336667
commit
c44d3e170c
|
|
@ -0,0 +1,502 @@
|
|||
# 🔍 DramaLing 後端錯誤日誌監控指南
|
||||
|
||||
## 📋 目錄
|
||||
1. [錯誤日誌系統概覽](#錯誤日誌系統概覽)
|
||||
2. [監控工具使用方法](#監控工具使用方法)
|
||||
3. [常見錯誤類型和排查](#常見錯誤類型和排查)
|
||||
4. [實際使用案例](#實際使用案例)
|
||||
5. [日誌級別說明](#日誌級別說明)
|
||||
6. [快速診斷檢查清單](#快速診斷檢查清單)
|
||||
|
||||
---
|
||||
|
||||
## 🎯 錯誤日誌系統概覽
|
||||
|
||||
DramaLing 後端配備了完整的錯誤日誌系統，幫助開發者快速定位和解決問題。
|
||||
|
||||
### ✅ **已配置的功能**
|
||||
- **全域錯誤處理中介軟體**：捕獲所有未處理的異常
|
||||
- **詳細日誌配置**：Debug 級別記錄
|
||||
- **結構化日誌**：包含請求詳情、堆疊追蹤
|
||||
- **資料庫操作日誌**：SQL 查詢和執行時間
|
||||
- **認證流程日誌**：完整的登入註冊追蹤
|
||||
|
||||
### 🗂️ **相關檔案**
|
||||
- `Middleware/ErrorHandlingMiddleware.cs` - 全域錯誤處理
|
||||
- `appsettings.json` - 日誌配置
|
||||
- `Controllers/AuthController.cs` - 認證日誌
|
||||
- `Program.cs` - 中介軟體註冊
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ 監控工具使用方法
|
||||
|
||||
### **1. 查看即時日誌**
|
||||
```bash
|
||||
# 查看當前後端服務的所有日誌
|
||||
BashOutput(bash_id: "33d454")
|
||||
```
|
||||
|
||||
### **2. 過濾特定錯誤**
|
||||
```bash
|
||||
# 只看錯誤和異常日誌
|
||||
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. 監控特定功能**
|
||||
```bash
|
||||
# 監控 JWT 相關問題
|
||||
BashOutput(bash_id: "33d454", filter: "JWT|Token|Bearer")
|
||||
|
||||
# 監控模型驗證錯誤
|
||||
BashOutput(bash_id: "33d454", filter: "ModelState|Validation")
|
||||
```
|
||||
|
||||
### **4. 找出服務 ID**
|
||||
如果不知道當前的 bash_id，使用：
|
||||
```bash
|
||||
/bashes
|
||||
```
|
||||
然後找到運行 `dotnet run --urls=http://localhost:5000` 的服務 ID。
|
||||
|
||||
---
|
||||
|
||||
## 🚨 常見錯誤類型和排查
|
||||
|
||||
### **1. 認證錯誤**
|
||||
|
||||
#### **問題症狀**：
|
||||
- 用戶無法登入
|
||||
- JWT token 無效
|
||||
- 401 Unauthorized 錯誤
|
||||
|
||||
#### **排查方法**：
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
#### **解決步驟**：
|
||||
1. 檢查 JWT 密鑰配置
|
||||
2. 驗證 token 格式是否正確
|
||||
3. 確認用戶是否存在於資料庫
|
||||
|
||||
### **2. 資料庫錯誤**
|
||||
|
||||
#### **問題症狀**：
|
||||
- 註冊失敗
|
||||
- 資料無法儲存
|
||||
- 500 Internal Server Error
|
||||
|
||||
#### **排查方法**：
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
#### **解決步驟**：
|
||||
1. 檢查資料庫檔案是否存在
|
||||
2. 驗證 SQL 查詢是否正確
|
||||
3. 確認資料庫連線字串
|
||||
|
||||
### **3. 模型驗證錯誤**
|
||||
|
||||
#### **問題症狀**：
|
||||
- 表單驗證失敗
|
||||
- 400 Bad Request
|
||||
- 密碼格式錯誤
|
||||
|
||||
#### **排查方法**：
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
#### **解決步驟**：
|
||||
1. 檢查前端表單驗證
|
||||
2. 確認後端模型註解
|
||||
3. 驗證請求格式
|
||||
|
||||
### **4. 應用程式異常**
|
||||
|
||||
#### **問題症狀**：
|
||||
- 系統崩潰
|
||||
- 未預期的錯誤
|
||||
- 堆疊溢出
|
||||
|
||||
#### **排查方法**：
|
||||
```bash
|
||||
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. 查看完整堆疊追蹤
|
||||
2. 檢查相關程式碼
|
||||
3. 驗證依賴注入配置
|
||||
|
||||
---
|
||||
|
||||
## 📝 實際使用案例
|
||||
|
||||
### **案例 1：用戶註冊失敗排查**
|
||||
|
||||
**問題**：前端註冊表單提交後返回 500 錯誤
|
||||
|
||||
**排查步驟**：
|
||||
|
||||
1. **檢查認證日誌**
|
||||
```bash
|
||||
BashOutput(bash_id: "33d454", filter: "Registration attempt")
|
||||
```
|
||||
|
||||
2. **查看詳細錯誤**
|
||||
```bash
|
||||
BashOutput(bash_id: "33d454", filter: "Error during user registration")
|
||||
```
|
||||
|
||||
3. **檢查資料庫操作**
|
||||
```bash
|
||||
BashOutput(bash_id: "33d454", filter: "INSERT INTO.*user_profiles")
|
||||
```
|
||||
|
||||
**可能的解決方案**：
|
||||
- 資料庫關聯配置錯誤
|
||||
- 模型驗證失敗
|
||||
- 密碼雜湊錯誤
|
||||
|
||||
### **案例 2：JWT Token 驗證失敗**
|
||||
|
||||
**問題**：用戶登入後無法訪問受保護的端點
|
||||
|
||||
**排查步驟**：
|
||||
|
||||
1. **查看 Token 生成**
|
||||
```bash
|
||||
BashOutput(bash_id: "33d454", filter: "User logged in successfully")
|
||||
```
|
||||
|
||||
2. **檢查 Token 驗證**
|
||||
```bash
|
||||
BashOutput(bash_id: "33d454", filter: "Bearer.*authenticated|Token.*validation")
|
||||
```
|
||||
|
||||
3. **查看認證失敗原因**
|
||||
```bash
|
||||
BashOutput(bash_id: "33d454", filter: "Failed to validate the token")
|
||||
```
|
||||
|
||||
**可能的解決方案**：
|
||||
- JWT 密鑰不匹配
|
||||
- Token 格式錯誤
|
||||
- Token 過期
|
||||
|
||||
### **案例 3：API 端點無回應**
|
||||
|
||||
**問題**：API 請求沒有回應或超時
|
||||
|
||||
**排查步驟**：
|
||||
|
||||
1. **檢查請求是否到達**
|
||||
```bash
|
||||
BashOutput(bash_id: "33d454", filter: "Request starting.*POST.*register")
|
||||
```
|
||||
|
||||
2. **查看路由匹配**
|
||||
```bash
|
||||
BashOutput(bash_id: "33d454", filter: "Route matched|Executing endpoint")
|
||||
```
|
||||
|
||||
3. **檢查異常處理**
|
||||
```bash
|
||||
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: 服務健康檢查**
|
||||
```bash
|
||||
curl "http://localhost:5000/health"
|
||||
```
|
||||
**預期結果**：`{"status":"Healthy","timestamp":"..."}`
|
||||
|
||||
### **Step 2: 查看最新錯誤**
|
||||
```bash
|
||||
BashOutput(bash_id: "33d454", filter: "Error|fail|Exception")
|
||||
```
|
||||
**目的**：快速找出最近發生的錯誤
|
||||
|
||||
### **Step 3: 檢查特定功能**
|
||||
根據問題類型選擇：
|
||||
|
||||
```bash
|
||||
# 🔐 認證問題
|
||||
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: 深入分析**
|
||||
```bash
|
||||
# 查看詳細追蹤
|
||||
BashOutput(bash_id: "33d454", filter: "StackTrace|InnerException")
|
||||
|
||||
# 查看完整請求流程
|
||||
BashOutput(bash_id: "33d454", filter: "Request starting.*POST")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 💡 進階技巧
|
||||
|
||||
### **1. 組合過濾器**
|
||||
```bash
|
||||
# 同時監控多個關鍵字
|
||||
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. 即時監控**
|
||||
可以定期檢查日誌來監控系統健康狀況：
|
||||
```bash
|
||||
# 每隔一段時間檢查錯誤
|
||||
BashOutput(bash_id: "33d454", filter: "Error|fail")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 常用監控命令
|
||||
|
||||
### **日常監控**
|
||||
```bash
|
||||
# 檢查服務狀態
|
||||
curl "http://localhost:5000/health"
|
||||
|
||||
# 查看最新日誌
|
||||
BashOutput(bash_id: "33d454")
|
||||
|
||||
# 只看錯誤
|
||||
BashOutput(bash_id: "33d454", filter: "Error|Exception|fail")
|
||||
```
|
||||
|
||||
### **功能測試**
|
||||
```bash
|
||||
# 測試註冊功能
|
||||
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"}'
|
||||
```
|
||||
|
||||
### **問題排查**
|
||||
```bash
|
||||
# 檢查認證問題
|
||||
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. 日誌保存**
|
||||
重要錯誤日誌應該保存下來用於：
|
||||
- 問題追蹤
|
||||
- 性能分析
|
||||
- 系統優化
|
||||
|
||||
---
|
||||
|
||||
## 📞 支援
|
||||
|
||||
如果遇到無法解決的問題：
|
||||
|
||||
1. **收集信息**：保存相關日誌
|
||||
2. **重現問題**：記錄重現步驟
|
||||
3. **檢查環境**：確認配置和依賴
|
||||
4. **尋求協助**：提供完整的錯誤資訊
|
||||
|
||||
---
|
||||
|
||||
**最後更新**：2025-09-16
|
||||
**版本**：v1.0
|
||||
**適用於**：DramaLing .NET Core API Backend
|
||||
|
||||
---
|
||||
|
||||
## 🔗 相關文檔
|
||||
|
||||
- [API 開發指南](./api/README.md)
|
||||
- [資料庫配置](./setup/env-setup.md)
|
||||
- [開發環境設置](./setup/README.md)
|
||||
Loading…
Reference in New Issue