dramaling-vocab-learning/docs/03_development/error-logging-guide.md

# 🔍 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)