Version: 2.8.1

Zipkin

用途說明#

傳播 Zipkin distributed tracing spans，並將 spans 報告給 Zipkin server。

欄位配置說明#

啟用時可以看到以下畫面：

插件啟用配置圖

對應的配置說明如下：

參數	類型	預設值	說明	必填
local_service_name	string	kong	Zipkin 中顯示的服務名稱。自定義此名稱以在 Zipkin request traces 中區分您的服務。	V
http_endpoint	string		Zipkin spans 的完整 HTTP(S) 端點應由 GOC API Gateway 發送。如果未指定，Zipkin 插件將僅充當追蹤的 header 生成器/發送器。
sample_ratio	number	0.001	對不包含追蹤 ID 的請求進行採樣的頻率。設置為 0 以關閉採樣，或設置為 1 以對所有請求進行採樣。該值必須介於 0 和 1 之間（含）。
include_credential	boolean	true	指定當前經過身份驗證的用戶的憑證，是否應包含在發送到 Zipkin server 的 metadata 中。	V
traceid_byte_count	integer	16	每個請求的追蹤 ID 的字節長度。該值可以是 8 或 16。	V
header_type	string	preserve	通過插件的所有 HTTP 請求都帶有追踪 HTTP 請求標記。此屬性對插件在傳入的請求中預期追蹤的 header 類型進行編碼。可能的值為：b3、b3-single、w3c、preserve、jaeger、ot 或 ignore。 - b3：在傳入請求中預期追蹤的 Zipkin’s B3 multiple headers，如果這些請求中缺少 headers，則會將它們添加到傳輸的請求中。 - b3-single：預期或添加 Zipkin 的 B3 single-header tracing headers。 - w3c：預期或添加 W3C 的 traceparent tracing headers。 - preserve：不預期任何格式，並且將傳輸任何已識別或存在的 header，如果沒有找到，則默認為 b3。如果預期的 tracing headers 與傳入的 tracing headers 不匹配（例如：當 header_type 設置為 b3，但在傳入的請求中發現 w3c 樣式的 tracing headers 時），插件會將兩種 tracing headers 添加到請求中，並在日誌中生成不匹配的警告。 - jaeger：預期或添加 Jaeger-style tracing headers (uber-trace-id)。 - ot：預期或添加 ot-tracer-* 形式的 OpenTelemetry tracing headers。 - ignore：不從傳入請求中讀取任何 tracing headers。使用 default_header_type 值啟動新請求，如果沒有設置 default_header_type 值，則退回為 b3。	V
default_header_type	string	b3	允許指定要添加到沒有預先存在的 tracing headers ，且 header_type 設置為 preserve 的請求的 header 類型。當 header_type 設置為任何其他值時， default_header_type 將被忽略。可能的值為 b3、b3-single、w3c、jaeger 或 ot。有關值的定義，請參閱 header_type 的 entry。	V
tags_header	string	Zipkin-Tags	Zipkin 插件會將額外的 headers 添加到與任何 HTTP 請求關聯的 tags，這些請求帶有一個以此屬性命名的 header。格式為： name_of_tag=value_of_tag，以分號 (;) 分隔。例如：使用預設值，帶有 header Zipkin-Tags 的請求：fg=blue； bg=red 將生成一條追蹤，其標記 fg 的值為 blue，另一個標記為 bg 的值為 red。	V
static_tags	array of string tags		在此屬性上指定的 tags 將添加到生成的請求追蹤中。例如：[ { "name": "color", "value": "red" } ]。

如何運作#

啟用後，此插件以與 zipkin 兼容的方式追蹤請求。

插件代碼圍繞 OpenTracing 核心構建，使用 opentracing-lua library 來收集每個 phase 的請求的時序數據。此插件使用 opentracing-lua 兼容的 extractor、injector、reporters 來實現 Zipkin 的協議。

Reporter#

OpenTracing "reporter" 是將追蹤的數據報告給另一個系統的方式。此插件記錄所給予的請求的追蹤數據，並使用 Zipkin v2 API 將其作為批次發送到 Zipkin server。

note

zipkin 版本需要高於 1.31。

http_endpoint 配置變量必須包含完整的 uri，包括 scheme、host、port 和 path 部分（i.e. 您的 uri 可能以 /api/v2/spans 當作結尾）。

Spans#

插件會執行請求採樣。對於觸發插件的每個請求，會選擇一個介於 0 和 1 之間的隨機數。

如果該數字大於配置的 sample_ratio，則將生成具有多個 spans 的 trace。如果 sample_ratio 設置為 1，那麼所有請求都會生成一個 trace（這可能非常嘈雜、干擾）。

對於每個被追蹤的請求，都會生成以下 spans：

Request span：每個請求 1 個。在 GOC API Gateway 中包含整個請求（種類: SERVER）。Proxy 和 Balancer span 是這個 span 的 children。它包含 rewrite phase 的以下 logs/annotations：
- krs - kong.rewrite.start
- krf - kong.rewrite.finish
Request span 有以下 tags：
- lc： hardcode 為 kong。
- kong.service：處理請求時匹配的服務的 uuid，如果有的話。
- kong.service_name：處理請求時匹配的服務名稱，如果服務存在且具有名稱屬性。
- kong.route：處理請求時匹配的路由的 uuid（如果有）（在不匹配的請求上可以為 nil）。
- kong.route_name：處理請求時匹配的路由名稱，如果路由存在且具有名稱屬性。
- http.method：用於原始請求的 HTTP 方法（僅適用於 HTTP 請求）。
- http.path：請求的路徑（僅適用於 HTTP 請求）。
- 如果設置了插件 tags_header 配置選項，並且請求包含具有適當名稱和正確編碼 tags 的 headers，那麼 trace 將包含這些 tags。
- 如果設置了插件 static_tags 配置選項，則配置選項中的 tags 將包含在 trace 中。
Proxy span：每個請求 1 個，包含 GOC API Gateway 對請求的大部分內部處理（種類：CLIENT）。包含插件 phases 開始/結束的以下 logs/annotations：
- kas - kong.access.start
- kaf - kong.access.finish
- kbs - kong.body_filter.start
- kbf - kong.body_filter.finish
- khs - kong.header_filter.start
- khf - kong.header_filter.finish
- kps - kong.preread.start (僅適用於 stream 請求)
- kpf - kong.preread.finish (僅適用於 stream 請求)
Balancer span(s)：每個請求 0 個或多個，每個包含一次 balancer 嘗試（種類：CLIENT）。包含以下特定於 balancer 的 tags：
- kong.balancer.try：指示嘗試的數字（1 表示第一次 load-balancing 嘗試，2 表示第二次，依此類推）。
- peer.ipv4 或 peer.ipv6 用於 balancer IP。
- peer.port 用於 balancer port。
- error：如果 balancing 嘗試不成功，則設置為 true，否則不會設置。
- http.status_code：出現錯誤時收到的 HTTP status code。
- kong.balancer.state：特定於 NGINX 的錯誤描述，next/failed 表示 HTTP 失敗，或者 0 表示 stream 失敗。相當於 OpenResty 的 balancer 的 get_last_failure 函數中的 state_name。