4. 健康檢查

服務的 check 決定如何測試每個 backend,check_options table 則設定該 checker。每次檢查都以 up、down 或 error 結束(第 1 章)。

check測試什麼適合
tcp一條 TCP 連線,可選擇加上 TLS 與 send/expect 交換任何 TCP 服務;以歡迎訊息開場的協定,例如 SMTP
http一個 GET 請求與它的狀態碼Web 服務與 health endpoint
exec每次檢查執行一次的程式既有的 Nagios 式 script、不頻繁的檢查
plugin 名稱長時間執行的 plugin 程式redis、MySQL、PostgreSQL、LDAP、DNS、RADIUS、SIP、Diameter、SMTP、AMQP、MongoDB、gRPC、QUIC 與 HTTP/3(emfor-check),或你自己寫的

在服務的 timeout 內沒有完成的檢查,結果是 down,reason 為 timeout。唯一的例外是 plugin:plugin 沒有及時回答時結果是 error,因為遲到的是 plugin,不是 backend。

tcp

沒有選項時,backend 接受連線即為 up;emfor 隨即關閉連線。連線被拒絕或無法到達則為 down;本機沒有通往 backend 的路由、或本機防火牆擋下連線時也是 down,因為本機的應用程式同樣連不到這個 backend。只有本機資源不足(開啟的檔案、緩衝區、記憶體、本機 port)才是 error。

選項型別預設值意義
send字串無連線後寫出一次的位元組。TOML 跳脫字元如 \r\n 會以對應位元組送出。需要搭配 expect。
expect字串無backend 送來的資料中必須出現的位元組(區分大小寫,最多讀 16384 位元組)。最長 16384 位元組。
tls布林false連線後立即進行 TLS handshake;絕不退回明文。
tls_verify布林truefalse 接受任何憑證(仍然加密)。需要 tls = true。
server_name字串backend IP憑證必須符合的名稱(或 IP);是名稱時也作為 SNI 送出。需要 tls = true。
ca_file絕對路徑系統 CA改為信任這個 PEM 檔中的 CA 憑證。載入設定時檔案必須存在,且至少有一張可以當作 CA 使用的憑證。需要 tls = true。
[services."smtp.svc.emfor"]
check = "tcp"
backends = ["10.0.6.11:25", "10.0.6.12:25"]
check_options = { expect = "220" }

[services."memcache.svc.emfor"]
check = "tcp"
backends = ["10.0.7.11:11211"]
check_options = { send = "stats\r\n", expect = "STAT pid" }

[services."imap.svc.emfor"]
check = "tcp"
backends = ["10.0.8.11:993"]
check_options = { tls = true, server_name = "imap.internal", expect = "* OK" }

常見的 reason:expect: got "421 too busy\r\n"(收到的前 64 位元組,已跳脫)、send: ...、tls: ...、tls: no answer to the TLS handshake (does the port speak TLS?),以及伺服器不回應握手、直接關閉連線時的 tls: connection closed during the TLS handshake (does the server have a certificate?)(例如 Active Directory 沒有憑證時的 636 port)。

http

每次檢查對 backend 的 IP 與 port 送一個 GET。不會跟隨重新導向。

選項型別預設值意義
scheme"http" 或 "https""http"協定。
path以 / 開頭的字串"/"請求路徑。#、\ 與控制字元會被拒絕,因為請求 URL 會在那裡截斷或改寫路徑;空白等特殊字元會以百分比編碼送出。
host_header字串無要送出的 Host header:主機名稱或 IP 位址,可加 :port,IPv6 要加中括號(api.internal、api.internal:8443、[2001:db8::1])。連線仍然連到 backend;用 https 時,主機名稱也是 TLS 的 server name。
expect_status非空清單["200-399"]視為 up 的狀態碼:單一狀態碼(200 或 "200")或含頭尾的範圍("200-299"),都必須在 100–599 之間。
tls_verify布林true用於 https:false 接受任何憑證。
expect_body字串無回應內容必須含有這段位元組(區分大小寫,最多讀 65536 位元組)。最長 16384 位元組。
[services."api.svc.emfor".check_options]
path = "/healthz"
host_header = "api.internal"
expect_status = ["200-299"]
expect_body = '"status":"UP"'

狀態碼不在清單內時為 down,reason 中帶有狀態碼,也不會讀內容。設了 expect_body 時,狀態碼符合的回應會一直讀到找到這段文字、內容結束或讀滿 65536 位元組;找不到時為 down,reason 為 expect_body: got "<前 64 位元組,escape 後>",讀內容失敗時 reason 以 body: 開頭。適合不論好壞都回 200、把狀態寫在內容裡的健康端點。此時 fastest 用的延遲包含讀內容的時間。

exec

每次檢查執行一次程式,不經過 shell。backend 以環境變數 EMFOR_IP、EMFOR_PORT 與 EMFOR_SERVICE 傳入。

[services."report.svc.emfor"]
check = "exec"
backends = ["10.0.3.1:5432"]
interval = "10s"
timeout = "5s"
check_options = { command = ["/usr/local/libexec/check_pg_replication", "--max-lag", "60"] }
結束方式結果
0up
1 或 2down;reason 為 stdout 的第一行,或 exit code N
其他結束代碼、被 signal 終止、無法啟動error
到 timeout 仍在執行down(timeout);程式與它所有子行程都會被終止

command 是唯一的選項:不含 NUL 的字串組成的非空清單,第一個元素是可執行檔的絕對路徑。每次檢查都啟動一個行程的成本不低;需要頻繁檢查很多 backend 時,請用 plugin。要執行現成的、命令列需要 -H 與 -p 的 Nagios 外掛,見從 Nagios 監看 emfor。

plugin 與 emfor-check

plugin 是長時間執行的程式:daemon 啟動它一次,之後透過它的 stdin 與 stdout,以 JSON 行傳送檢查請求。一個行程服務所有使用它的服務,並且可以在檢查之間保留連線與狀態。

emfor 附帶一個 plugin 程式 emfor-check,由參數選擇檢查種類:

[plugins."pgsql"]
command = ["/usr/local/libexec/emfor-check", "pgsql"]

[services."db.svc.emfor"]
check = "pgsql"
balance = "failover"
backends = ["10.0.3.1:5432", "10.0.3.2:5432"]
check_options = { user = "emfor", database = "postgres", role = "primary", password_file = "/etc/emfor/pg.pass" }
參數何時為 up
redisPING 回答 PONG(設定密碼時先 AUTH)
mysql登入成功且 SELECT 1 回傳 1(以 MariaDB 與 MySQL 8.0、8.4 測試)
pgsql登入成功且 SELECT 1 回傳 1
ldapsimple bind 成功
dns一次查詢得到預期的 response code(設定 expect_answer 時還要有記錄)
radiusStatus-Server(或 Access-Request)得到以共享密鑰簽署的 accept
sipOPTIONS 請求得到 expect_status 內的最終狀態碼(預設 200 到 499)
diameter能力交換(CER / CEA)與 Device-Watchdog(DWR / DWA)成功
smtp歡迎訊息為 220 且 EHLO 回答 250;要求時經 STARTTLS 或 TLS
amqpAMQP 0-9-1 登入成功且 vhost 開啟
mongodbhello 有回應、設了 user 時 SCRAM-SHA-256 登入成功,且角色符合
grpc標準健康服務(grpc.health.v1.Health/Check)回答 SERVING
quic經 UDP 完成 QUIC 握手,憑證通過驗證且 ALPN 在 alpn 之內;http3 = true 時,HTTP/3 GET 的狀態碼還要在 expect_status 之內

主要選項:user、password_file(絕不寫密碼本身;每次檢查都會讀取)、database(pgsql)、role(redis 為 master/replica,MySQL 與 PostgreSQL 為 primary/replica;primary 讓 failover 跟著 primary 走,replica 另外要求複寫正在進行;MongoDB 為 primary/secondary)、max_lag(搭配 role = "replica",replica 最多可以落後幾秒),以及 tls、starttls(ldap)、tls_verify、server_name、ca_file。dns plugin 則用 name、type、transport、recursion_desired、expect_rcode、expect_answer;radius plugin 用 secret_file、request、application、user、password_file、reject_is_up、nas_identifier、require_message_authenticator;sip plugin 用 transport、tls(及 TLS 相關鍵)、uri、from、expect_status;diameter plugin 用 origin_host、origin_realm、各 application id、supported_vendor_ids、host_ip_address、tls(及 TLS 相關鍵與客戶端憑證 tls_cert_file、tls_key_file);smtp plugin 用 helo、starttls、tls(及 TLS 相關鍵);amqp plugin 用 user、password_file、vhost、tls(及 TLS 相關鍵);mongodb plugin 用 user、password_file、auth_source、role、tls(及 TLS 相關鍵);grpc plugin 用 service、tls(及 TLS 相關鍵);quic plugin 用 alpn、tls_verify、server_name、ca_file(一律加密,所以沒有 tls 鍵)、http3、path、host_header、expect_status、expect_body。docs/deploy/plugins.md 列出所有選項與 reason。

emfor check-config 與每次 reload 都會啟動 plugin,讓它們驗證每個服務的 check_options,所以錯誤會在設定套用前就被發現。驗證時會建出檢查時要建的東西:ca_file 必須有可以當作 CA 使用的憑證,tls_key_file 必須是 tls_cert_file 的私鑰,而協定以 NUL 結尾或以 NUL 分隔送出的值(mysql 與 pgsql 的 user、pgsql 的 database 與密碼、amqp 的 user 與密碼)不能含 NUL。協定規定了大小上限的訊息會實際組一次:amqp 的登入必須放得進 4096 bytes 的第一個 frame,diameter 的 Capabilities-Exchange-Request 不能超過 16777215 bytes。

plugin 結束時,等待中的檢查變成 error(plugin exited),daemon 在 1 秒、2 秒、4 秒……最多 30 秒後重新啟動它;在那之前它的檢查都是 error(plugin <name> unavailable)。當掉的 plugin 不會讓 backend 變成 down:error 不算檢查失敗。但一個 backend 只收到 error 的時間超過 fall × interval 時會回到 unknown(見第 1 章),所以一直當掉的 plugin 會讓它的 backend 變成 unknown,而不是維持 healthy。以 emfor-plugin crate 寫的 plugin 中,panic 的檢查會回答 error,reason 為 check panicked: <message>,plugin 繼續執行。plugin 寫到 stderr 的每一行都以 info 記錄,一次最多 100 行,之後每秒最多 10 行;log 會寫出丟掉了幾行。每個 plugin 在自己的 process group 中執行:plugin 結束或被停止時,它啟動的行程也會一起被終止。

要自己寫 plugin,見 docs/plugins/protocol-v1.md;emfor-plugin crate 為 Rust 實作了這個協定。

排程

每個 backend 依自己的時程檢查,而且同一個 backend 不會同時有兩個檢查:

  • 啟動或 reload 後的第一次檢查,在 min(interval, 200ms) 內的隨機時刻開始。
  • backend 處於 unknown 且檢查結果為 up 或 down 時,下一次檢查在上一次結束後 min(interval, 200ms) 開始。以預設值(rise = 2),約半秒內就能確定 backend 狀態。這個快速節奏最多持續 rise + fall 次:結果一直變來變去、兩個計數都到不了門檻的 backend 會維持 unknown,之後改為每 interval 檢查一次。
  • 其他情況下,下一次檢查在上一次結束後 interval 開始,並隨機前後偏移最多 jitter(預設 10%)。

因為 interval 從檢查結束時算起,慢的 backend 不會比每 interval 一次更頻繁地被檢查。

rise、fall 與 error

  • up:成功計數加一,失敗計數歸零;到達 rise 時 backend 變成 healthy。
  • down:失敗計數加一,成功計數歸零;到達 fall 時 backend 變成 unhealthy。
  • error:計數與狀態都不變。backend 只收到 error 的時間超過 fall × interval 時,回到 unknown。

偵測故障大約需要 fall × interval(預設 6 秒);恢復大約需要 rise × interval(4 秒)。每次狀態變化都以 info 記錄,包含服務、backend、舊狀態、新狀態與 reason。

reason

down 或 error 結果帶有一個 reason,會顯示在 emfor status、log 與狀態歷史中。儲存前 reason 會被處理成安全的形式:tab、CR 與 LF 變成 \t、\r 與 \n;其他控制字元變成 \u{1b} 之類的形式;超過 512 個字元的 reason 會被截斷並以 … 結尾。

延遲

daemon 為每個 backend 量測每次 up 檢查花了多久,並保存一個平滑後的值(每個新樣本占 5%)。emfor status 與 /metrics 會顯示它,balance = "fastest" 會用到它。依賴這個值時,請選擇接近實際流量的檢查。

使用 Hugo 建立
主題 Stack 由 Jimmy 設計