Correlation ID
用途說明#
透過使用HTTP標頭傳輸的唯一ID來關聯請求和回應。
欄位配置說明#
啟用時可以看到以下畫面：
對應的配置說明如下：
| 參數 | 類型 | 預設值 | 說明 | 必填 |
|---|---|---|---|---|
| header_name | string | Kong-Request-ID | 用於關聯ID的HTTP標頭名稱。 | V |
| generator | string | uuid#counter | 用於關聯ID的生成器。 可接受的值為 uuid、uuid#counter和tracker。請參閱生成器。 | V |
| 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，且以下透過API Manager來呼叫該服務的路由，呼叫一隻/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。