TrueWatch Workshop：使用 TrueWatch 監控 MySQL：端到端設定（逐步教學）

參考：完整的 MySQL 整合詳情與欄位定義請參閱 TrueWatch MySQL 整合文件。

您將達成的目標

依照本逐步指南操作，您將能夠：

• 安裝並設定 TrueWatch DataKit 以連接 MySQL
• 建立安全、最小權限的監控使用者
• （可選）啟用並收集 MySQL 一般／慢查詢日誌
• 在 TrueWatch 中建立實用的 MySQL 監控儀表板

適合對象：希望快速取得企業級 MySQL 監控的後端工程師、SRE 與 DBA。

事前準備

• 可連線的 MySQL 5.7+ / 8.0+ 執行個體（雲端 RDS 亦可）
• 建議使用 MySQL 8.0，以取得完整的 performance_schema 涵蓋範圍
• 具備建立使用者與授予權限的權限
• 能夠部署 TrueWatch DataKit（Docker 或主機安裝）

架構總覽

MySQL  ← (monitoring user, performance_schema)
  ↑
DataKit (container or host) → ships Metrics / Logs / Slow Queries to TrueWatch

需要 eBPF／主機層級的遙測資料？建議採用主機安裝。若僅需監控資料庫，使用容器即可。

步驟 1：驗證並啟用 performance_schema

許多資料庫指標皆來自 MySQL 的 performance_schema。請先確認其是否已啟用：

SHOW VARIABLES LIKE 'performance_schema';

若顯示 Value = OFF，請依您的環境啟用它：

• 在 my.cnf 中：

[mysqld]
performance_schema=ON

重新啟動 MySQL 並確認其狀態為 ON。

若 performance_schema 被停用或受限，代管服務（例如阿里雲 RDS）可能會限制部分量測項目（例如 mysql_user_status）。詳細的常見問題與解決方法請參閱 TrueWatch MySQL 整合文件。

步驟 2：建立最小權限監控使用者

基於安全性與可觀測性考量，請建立專用的唯讀使用者（請自訂使用者名稱／密碼）：

CREATE USER 'datakit'@'%' IDENTIFIED WITH caching_sha2_password BY 'datakit_password';
GRANT PROCESS ON *.* TO 'datakit'@'%';
GRANT SELECT ON *.* TO 'datakit'@'%';
GRANT SELECT ON performance_schema.* TO 'datakit'@'%';
GRANT SELECT ON mysql.user TO 'datakit'@'%';
GRANT REPLICATION CLIENT ON *.* TO 'datakit'@'%';
FLUSH PRIVILEGES;

這些權限的用途：

• PROCESS：檢視執行中的查詢與連線
• SELECT（含 performance_schema）：讀取效能與統計資料
• REPLICATION CLIENT：讀取複寫狀態（如適用）

步驟 3：安裝並啟動 DataKit（擇一）

以容器或主機方式安裝 DataKit（指令已根據官方指南簡化）：

3A. Docker（快速開始）

#1）在 TrueWatch 主控台 → DataKit → Docker 中，選擇您的 DataWay 並複製產生的指令／權杖。 #2）在目標主機上執行：

docker run -d --name datakit \
  --hostname "$(hostname)" \
  -p 9529:9529 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v $(pwd)/conf.d:/usr/local/datakit/conf.d \
  -e ENV_DATAWAY="https://<your-openway-host>?token=<your_token>" \
  -e ENV_HTTP_LISTEN="0.0.0.0:9529" \
  pubrepo.truewatch.com/truewatch/datakit:1.80.1

#3）將下一步驟中的 mysql.conf 放入掛載的 conf.d/ 目錄（建議放在 conf.d/db/）。DataKit 會自動載入該檔案。

如需更多環境變數與進階選項（代理伺服器、資源限制、日誌記錄等），請參閱官方文件：DataKit 安裝文件。

3B. 主機安裝（建議用於 eBPF／主機指標）

#1）在 TrueWatch 主控台 → DataKit → Linux 中，選擇 DataWay 並複製帶有權杖的指令。

#2）在目標主機上執行（將安裝並啟動 DataKit）：

DK_DATAWAY="https://<your-openway-host>?token=<your_token>" bash -c "$(curl -L https://static.truewatch.com/datakit/install.sh)"

#3）將 mysql.conf 放置於 DataKit 的 conf.d/db/ 目錄下，然後重新啟動服務：

sudo systemctl restart datakit

如需 DK_INSTALL_ONLY、代理伺服器與升級等其他選項，請參閱官方文件：DataKit 安裝文件。

步驟 4：設定 DataKit MySQL 輸入端（inputs.mysql）

在 DataKit 的 conf.d/db 目錄中建立或編輯 mysql.conf：

[[inputs.mysql]]
  host = "db"              # or your MySQL address (FQDN/IP)
  user = "datakit"         # monitoring user
  pass = "datakit_password"
  port = 3306
  interval = "10s"
  innodb = true             # collect key InnoDB metrics
  dbm = true                # enable Database Monitoring (query analysis)
  election = true           # single leader collects when multiple DataKits exist

欄位說明與調校建議請參閱 TrueWatch MySQL 整合文件。

重新啟動（或熱重載）DataKit，指標資料即會開始傳輸。

步驟 5（可選）：收集 MySQL 一般／慢查詢日誌

TrueWatch 可擷取 MySQL 的一般與慢查詢日誌，協助精準定位高延遲的 SQL。

5A. 啟用慢查詢日誌（MySQL）

SET GLOBAL slow_query_log = 'ON';
SET GLOBAL log_queries_not_using_indexes = 'ON';  -- optional: flag queries without indexes
-- Recommended tuning (persist via my.cnf):
SET GLOBAL long_query_time = 1;                   -- seconds threshold for slow query

若要持久保存設定，請將以下內容加入 my.cnf（範例）：

[mysqld]
slow_query_log=ON
long_query_time=1
log_queries_not_using_indexes=ON
log_output=FILE
slow_query_log_file=/var/log/mysql/slow.log

5B. DataKit 日誌收集（通常搭配主機安裝使用）

加入至 conf.d/mysql.conf（或建立新的區段）：

[inputs.mysql.log]
  files = ["/var/log/mysql/*.log"]  # adjust to your absolute paths

詳細的日誌欄位對應（一般／慢查詢）請參閱 TrueWatch MySQL 整合文件。

步驟 6：驗證資料擷取

#1）檢查 DataKit 狀態頁面（預設連接埠 9529），確認輸入端是否正常 #2）在 TrueWatch Explorer 中搜尋 mysql、mysql_replication_log 等量測項目 #3）查看 connections、query_time、lock_time、rows_examined、rows_sent 等欄位

若缺少特定量測項目（例如 mysql_user_status），請確認 performance_schema 已啟用，或檢查 RDS 相關限制。詳情請參閱 TrueWatch MySQL 整合文件 中的常見問題。

步驟 7：建立實用的 MySQL 儀表板

A. 使用範本儀表板（建議）

#1）前往左側的「Scenes」→ 頂部的「Dashboards」→ 點選「Create」。

#2）在「System Views」下搜尋 mysql，並選擇「Mysql Monitor View」（或特定雲端服務的 MySQL 範本）。

#3）此範本包含連線數、查詢延遲、InnoDB 與複寫等常用圖表，可依需求自訂。

範本來源與欄位參考：TrueWatch MySQL 整合文件。

B. 自訂小工具（彈性）

儀表板預覽

小工具設定範例（QPS／TPS）

• QPS：使用 mysql 指標中的 Questions 欄位，套用 non_negative_derivative 即可取得每秒查詢數。

• TPS：使用 A+B 運算式，將 Handler_commit 與 Handler_rollback 分別套用 non_negative_derivative 後相加，即可取得每秒交易數。

以下為經過實戰驗證、適用於常見資料庫監控需求的小工具，可視情況使用 Simple／Expression／DQL 查詢方式加入 TrueWatch 儀表板。

欄位範例參考自 mysql 與 mysql_replication_log 等量測項目，請於 Explorer 中確認欄位是否可用。

A. 概覽

• 時間序列（連線數）

  • 來源：mysql.connections
  • 維度：server（主機:連接埠）
  • 目的：觀察並行度與尖峰情形

• 單一數值／趨勢（p95 查詢時間）

  • 來源：mysql.query_time
  • 聚合方式：5 分鐘內的 p95
  • 目的：一目了然檢視尾端延遲

• 單一數值／趨勢（鎖定等待時間）

  • 來源：mysql.lock_time
  • 聚合方式：5 分鐘內的平均值（或 p95）
  • 目的：偵測鎖定爭用與阻塞情形

• 單一數值（每分鐘慢查詢數）

  • 來源：慢查詢日誌（inputs.mysql.log）
  • 方法：計算存在 db_slow_statement 的事件數
  • 目的：掌握慢查詢激增的情形

B. InnoDB 與吞吐量

• 時間序列（掃描列數／傳送列數）

  • 來源：mysql.rows_examined、mysql.rows_sent
  • 聚合方式：加總或速率
  • 目的：了解讀取量與回傳列數的關係，藉此推估效率

• 表格（熱門資料表／索引排行）

  • 來源：mysql.index_name、mysql.object_name、mysql.object_schema
  • 聚合方式：依 query_signature 或 object_name 分組，顯示平均 query_time 與筆數
  • 目的：定位熱門資料表／索引與緩慢操作

C. 前 N 大問題查詢（日誌／事件）

• 表格（依平均耗時排序的慢查詢排行）

  • 來源：慢查詢日誌或 mysql 事件
  • 欄位：query_signature、sql_text（或標準化後的 message）
  • 指標：avg(query_time)、count()

• 表格（等待事件排行）

  • 來源：mysql.wait_event、event_name
  • 指標：sum(event_timer_wait)

D. 複寫（如適用）

• 單一數值／表格（主節點／已執行 GTID 集合摘要）
  • 來源：mysql_replication_log.Executed_Gtid_Set、Master_Host、Master_Port
  • 目的：確認主從關係與 GTID 進度

提示：如果有此欄位，可加入 Seconds_Behind_Master 作為單一數值／時間序列，用以監控複寫延遲。

最佳實務與安全性

• 使用與應用程式帳號分離的專用最小權限監控使用者
• 在測試環境中可採用較高的收集頻率（例如 interval = "10s"）；正式環境則需依成本與效能調整
• 調整 long_query_time 與 log_queries_not_using_indexes，在雜訊與有效資訊間取得平衡
• 在容器環境中，建議優先使用 stdout／日誌驅動程式，而非檔案掛載，以避免共用敏感路徑
• 將憑證存放於機密管理系統／環境變數中，而非提交至檔案

常見問題與疑難排解

問：我看不到 mysql_user_status 這個量測項目。

答：請確認 performance_schema 是否為 ON：

SHOW VARIABLES LIKE 'performance_schema';

若顯示為 OFF，請依您的資料庫／RDS 供應商說明啟用。部分 RDS 產品可能限制此功能，詳情請參閱 TrueWatch MySQL 整合文件。

問：DataKit 正在執行，但沒有資料進來。

• 確認 mysql.conf 中的連線資訊（主機／使用者／密碼／連接埠）
• 確認安全群組／防火牆允許 DataKit 存取 MySQL
• 檢查 DataKit 狀態頁面／日誌，確認是否有連線或權限錯誤

問：慢查詢沒有顯示出來。

• 確認 slow_query_log 已啟用
• 若是從容器中收集檔案，請確認絕對路徑可讀取（使用 stdout／sidecar 通常較為簡便）
• 在 Explorer 中搜尋日誌索引，尋找標記（例如 [MYSQL_QUERY]）或慢查詢日誌欄位

參考資料

• 官方整合文件與欄位定義：TrueWatch MySQL 整合文件
• 我們的整合歷程與設計理念（監控使用者、DataKit 輸入端、sidecar）：demo-project/INTEGRATION_GUIDE.md

完成以上步驟後，您已成功將 MySQL 與 TrueWatch 整合，並建立了可實際運用的儀表板。接下來，可加入警示（Monitors）、排程報表與跨服務關聯分析，打造端到端、可用於正式環境的資料庫可觀測性。