Log、API 與診斷

為什麼要學這個

EMQX 的 Dashboard 把 broker 的狀態可視化，但真正細到「某個 client 為什麼被拒絕」「這條規則為什麼沒命中」的時候，還是要靠 Log 與 Trace。加上 EMQX 對外用 REST API，很多事情你不用開網頁就能自動化。

這章的目標，是讓你知道「出問題時去哪看」：先會讀 Log 層級與 Log Trace，再用 Diagnose 模組裡的工具縮小範圍，最後認識 REST API 的概念與 Health Check 端點。實務上你就是拿這四樣去排下一次的怪。

核心概念

EMQX 的 Log 有兩種輸出流：Console Log（輸出到 console）與 File Log（寫進檔案）。預設層級是 warning。Dashboard 的 Management → Logging 頁可以調整。

Log Trace 是只「挑出」特定 client ID、IP、主題（可含萬用字元）或規則 ID 的即時除錯 Log，適合在正式環境不想被大量 Log 淹沒時使用。

REST API（/api/v5/...）是 EMQX 的 HTTP 管理面，用 API key 做 Basic 驗證。把它與 Dashboard 想成同一套引擎的兩種操作方式。

Diagnose（診斷）模組把 WebSocket Client、Log Trace、Slow Subscriptions、Topic Metrics 等工具放在一起，方便你快速測試與定位。

名詞對照

動手做

1. 看目前 Log 設定

   左側 Management → Logging，切 Console Log 或 File Log 分頁改等級（預設 warning）。變更立即生效。

2. 用 WebSocket Client 測試一筆

   左側 Diagnose → WebSocket Client，建立一個連線，用 subscribe／publish 快速確認某主題的行為。

3. 建一個 Log Trace

   左側 Diagnose → Log Trace → Create，選擇要追蹤的 client ID、IP 或主題，即可開始蒐集。

4. 呼叫 REST API 檢查

   把 API Key 存起來，用 curl 對 /api/v5/nodes 做 GET，驗證你的 API 能回 JSON。

Log 層級與 Logging 設定

EMQX 支援 6 個層級（RFC 5424 的 8 層中取用 6 層），預設是 warning，由弱到強是：debug < info < notice < warning < error < critical。

• debug：細部的變數、函式等除錯資料。
• info：授權拒絕等輕微異常、設定變更成功的結果。
• warning：斷線、連線逾時、驗證失敗等可能需注意。
• error：連不上外部資料庫、訂閱不存在的錯誤等。
• critical：設定錯誤導致元件無法啟動等。

Console 與 File handler 都可在 Logging 頁面調整；檔案型可設定檔案名（預設 log/emqx.log）、最多輪替數（預設 10）、輪替大小（預設啟用）等。

還有 Log Throttling（日誌節流）：在時間窗內把重複事件只記第一筆、其餘記數，可防止日誌爆量。預設啟用，時間窗預設 1 分鐘。

Log Trace 追蹤特定對象

Log Trace 是「針對特定對象」的即時 debug 層級記錄，比開 debug 全量 Log 更適合正式環境。它在 Diagnose → Log Trace。

建立方式：

1. 按 Create，在 Type 選擇 Client ID、Topic（可含萬用字元）、IP Address 或 Rule ID。
2. Client ID 與 IP 需完整輸入；Topic 可用萬用字元。
3. 選取 start／end 時間，按 Create 開始蒐集。

清單可看或下載該 trace 的日誌。整個系統最多可以同時跑 30 個 trace；每個節點的 trace 日誌上限 512MB，滿了就停止追加並在主 Log 提出警示。另外，trace 日誌也能在伺服器端 /data/trace 目錄找到。

規則測試（Test Rule）會自動建立並於結束時刪除 trace，所以除錯規則時也能反向抓 Log。

Diagnose 模組一覽

Dashboard 的 Diagnose 模組是除錯工具的落點，包含：

• WebSocket Client：內建 MQTT 測試工具，可建立連線、subscribe、publish，快速驗證 client 的行為，省去另外搭建工具。
• Topic Metrics（Enterprise）：對特定主題統計接收／送出／捨棄的訊息量與速率。
• Slow Subscriptions（Enterprise）：找出投遞時間超過門檻的訂閱。
• Log Trace：上面講過的針對性日誌追蹤。
• Alerts（Enterprise）：目前與歷史的系統警報。

REST API 概念與 Health Check

EMQX 的 REST API 依 OpenAPI 3.0 規範，所有路徑開頭是 /api/v5。你可以開啟 http://<主機>:18083/api-docs/ 用 Swagger UI 直接試用。

REST API 的驗證用 API Key（Dashboard：System → API Key 建立）。Basic 認證把 API Key 當 username、Secret Key 當 password。Dashboard 使用者帳號無法直接呼叫 API。

curl -X GET http://localhost:18083/api/v5/nodes \
  -u <你的API金鑰>:<你的API密鑰> \
  -H "Content-Type: application/json"

如果要接負載平衡，EMQX 提供了健康檢查端點 GET /api/v5/load_rebalance/availability_check：正常節點回 200，已退出（evacuation）的節點回 503。

記得把 API key、secret、token 這類全都用佔位符，不要寫進本機教學或 log。

故障排除

• 想看的 Log 一直被截斷：Log Throttling 預設會把重複事件只記第一筆。若要噴細節，可把 log level 設成 debug，此時節流會停用。
• Log Trace 找不到對象：確認輸入的 client ID / IP 是精確值。Topic 才支援萬用字元。trace 結束後可去 /data/trace 找檔案。
• REST API 回 401：多半是用 Dashboard 使用者的帳號去呼叫。改用 System → API Key 建立的一組 API Key/Secret。
• Slow Subscriptions / Topic Metrics / Alerts 在左欄消失：這三項都屬 EMQX Enterprise 版，Open Source 5.8.9 的 Diagnose 左欄無法看到。

常見問題

官方來源

• EMQX 5.8 Log 層級與設定（pinned docs 分支）
• EMQX 5.8 Log Trace（pinned docs 分支）
• EMQX 5.8 Diagnose 模組（pinned docs 分支）
• EMQX 5.8 REST API（pinned docs 分支）
• Woow EMQX add-on README（pinned commit）