Correlation ID
用途說明#
透過使用 HTTP 標頭傳輸的唯一 ID 來關聯請求和回應。
欄位配置說明#
啟用時可以看到以下畫面：
對應的配置說明如下：
| 參數 | 類型 | 預設值 | 說明 | 必填 |
|---|---|---|---|---|
| header_name | string | Kong-Request-ID | 用於關聯 ID 的 HTTP 標頭名稱。 | |
| generator | string | uuid#counter | 用於關聯 ID 的生成器。 可接受的值為以下其一： uuid、uuid#counter 和 tracker。說明請參閱生成器。 | |
| echo_downstream | boolean | false | 是否將標頭送回下游（客戶端）。 | V |
運作說明#
當啟用插件後，依照啟用的階層（全局、服務、路由、用戶），對應的請求皆會加上一個新的標頭。此標頭的名稱為 header_name 所配置的名稱，以及根據 generator 設定的生成器來生成唯一值。
在對上游服務調用時，會將標頭添加進去，並根據 echo_downstream 的設定來選擇是否在客戶端中顯示。
如果客戶端請求中已經存在帶有相同設置名稱的標頭，則會接受該標頭，且此插件不會修改該標頭內的值。
用法示例#
生成器#
uuid#
格式：
此格式將為每個請求以其十六進制形式生成一個 UUID。
uuid#counter#
格式：
在這種格式下，每個工作系統進程將生成一個 UUID，並且進一步的請求只需在＃字符後將計數器添加到 UUID。每個工作系統計數器的值都從 0 開始，並且透過每個獨立的工作系統進程遞增。
這種格式可以提供更好的性能，但可能由於格式、低數量類別屬性的關係而難以儲存或分析處理。
tracker#
格式：
在這種格式中，每個請求的相關性 ID 包含更多實際含義，請參考以下詳細說明：
| 構成參數 | 描述 |
|---|---|
| ip | 接受請求的服務器的地址。 |
| port | 接受請求的服務器的端口。 |
| pid | Nginx 工作系統進程的 pid。 |
| connection | 連接序列號。 |
| connection_requests | 透過該次連接發出的當前請求數。 |
| timestamp | 從 Nginx 緩存時間到當前時間戳經過時間的浮點數，（以秒為單位，包括毫秒作為小數部分）。 |
在全局啟用插件#
- 從網站左邊 Menu 中
外掛插件頁面中，點選右上角的新增外掛插件：
- 點選後，選擇
轉換頁籤，並啟用 Correlation ID，填寫內容參考欄位配置說明，設定成功後，任何請求(不分服務、路由、用戶)都會透過使用HTTP標頭傳輸的唯一ID來關聯請求和回應。
在服務端上啟用插件#
- 從網站左邊 Menu 中
服務 > 服務列表頁面中，選擇要啟用此插件的服務，假設為google，點選對應的編輯按鈕：
- 在編輯畫面中，點選上方的
外掛插件頁籤，再點選頁籤內容上方的新增外掛插件按鈕：
點選後，選擇 轉換 頁籤，並啟用 Correlation ID，填寫內容參考欄位配置說明，設定成功後，僅有此服務(範例為google)請求會透過使用HTTP標頭傳輸的唯一ID來關聯請求和回應。
在路由端上啟用插件#
可以由兩種方式來選擇路由，並啟用插件：
方式一：路由列表#
- 從網站左邊 Menu 中
服務 > 路由列表頁面中，選擇要啟用此插件的路由，假設為google，點選對應的編輯按鈕：
方式二：服務 > 服務列表 > 路由列表#
- 從網站左邊 Menu 中
服務 > 服務列表頁面中，選擇要啟用此插件的路由 所屬之服務(假設為google)，點選對應的編輯按鈕。
在編輯畫面中，點選上方的 路由 頁籤，選擇要啟用此插件的路由(假設為 google)，點選對應的編輯按鈕：
- 承第1步，點擊上述兩種方式之一的編輯按鈕後，在編輯畫面中，點選上方的
外掛插件頁籤，再點選頁籤內容上方的新增外掛插件按鈕：
點選新增外掛插件 按鈕後，選擇 轉換 頁籤，並啟用 Correlation ID，填寫內容參考欄位配置說明，設定成功後，僅有此路由(範例為google)請求會透過使用HTTP標頭傳輸的唯一ID來關聯請求和回應。
在用戶端上啟用插件#
- 從網站左邊 Menu 中
訂閱用戶 > 用戶列表頁面中，選擇要啟用此插件的用戶，假設為portaladmin，點選對應的編輯按鈕：
- 在編輯畫面中，點選上方的
外掛插件頁籤，再點選頁籤內容上方的新增外掛插件按鈕：
點選後，選擇 轉換 頁籤，並啟用 Correlation ID，填寫內容參考欄位配置說明，設定成功後，僅有此用戶(範例為 portaladmin)請求會透過使用HTTP標頭傳輸的唯一ID來關聯請求和回應。
驗證#
假設有一個後端服務 backend，且以下透過 GOC API Gateway 來呼叫該服務的路由，呼叫一隻 /forward 的 api。該 api 會將收到請求的標頭、路徑、 body 當成回應回傳。
啟用 Correlation ID 插件，header_name 使用預設值 Kong-Request-ID ； generator 使用預設值 uuid#counter， echo_downstream 設定為 true 。
接下來呼叫該服務驗證(使用 curl 命令來測試)：
可以看到當服務接受到我們所傳送的請求時，是有收到 Kong-Request-ID 標頭，格式為 UUID 加上計數器無誤，且因為我們設定 echo_downstream 為 true ，所以可以看到回應的標頭有含 Kong-Request-ID。
當 echo_downstream 改為 false，再次呼叫服務：
可以看到當服務接受到我們所傳送的請求時，仍有收到 Kong-Request-ID 標頭，格式為 UUID 加上計數器無誤。但因為 echo_downstream 設為 false，所以回應的標頭沒有 Kong-Request-ID。