Python 業務參數提取 - Cloud Monitor

排查 Python 應用調用鏈路問題時，業務參數是快速定位根因和追蹤請求資訊的關鍵。ARMS 支援通過控制台配置擷取規則，無侵入地將 HTTP 要求和響應中的指定參數寫入 Span Attributes，還可配置自訂錯誤規則將匹配的 Span 標記為錯誤。

前提條件

已為 Python 應用接入 ARMS Python 探針。
Python 探針版本不低於 3.1.0。

支援範圍說明

業務參數擷取規則對架構和實際用法有一定要求。Python 版支援的參數提取類型和來源如下：

參數提取類型	參數提取來源	支援的架構	備忘
HTTP 服務端請求	Header、Query Parameter、Cookie、Body	Flask、Django、FastAPI	Body 需為 JSON 格式，詳見常見問題。
HTTP 服務端響應	Header、Body、Cookie	Flask、Django、FastAPI	Body 需為 JSON 格式；Cookie 來源讀取的是請求側 Cookie。
HTTP 用戶端請求	Header、Query Parameter	requests、httpx、aiohttp、urllib3	用戶端不支援 Body、Cookie 來源。
HTTP 用戶端響應	Header	requests、httpx、aiohttp、urllib3	-

如果需要提取的參數來源超出上述支援範圍，可通過引入 OpenTelemetry SDK 添加自訂埋點，將業務參數作為 Attributes 寫入 Span。

功能入口

登入 ARMS 控制台。
在左側導覽列選擇應用監控 > 應用列表，在頂部功能表列選擇目標地區，然後單擊目標 Python 應用的名稱。
在左側導覽列單擊應用設定，然後單擊自訂參數頁簽。
- 在业务参数提取规则地區，可以建立、查看和修改當前應用的業務參數擷取規則。ARMS 探針會動態識別規則變化，並依照所有已啟用的規則將業務參數提取出來。
- 在自定义错误设置地區，可以配置自訂錯誤規則，對提取出來的業務參數值進行匹配，命中後將對應 Span 標記為錯誤。

新增擷取規則

重要

首次建立擷取規則需要重啟應用使功能生效。後續新增或修改規則無需重啟，規則通過探針的配置熱更新動態下發，預計 1~2 分鐘後開始生效。

在业务参数提取规则地區，按以下步驟建立擷取規則：

單擊新增规则。
填寫規則名稱和 Attribute名称。
選擇参数提取类型，並配置生效接口，指定規則作用的介面範圍。
在参数提取规则地區，添加参数来源並配置參數處理步驟。支援配置多個參數來源和處理步驟，若多個來源均可提取到參數，排序在前的優先順序更高。
設定是否啟用，然後單擊儲存。

規則建立完成並啟用後將即時下發至用戶端探針側。業務參數提取後將記錄至對應調用鏈 Span 的 Attributes，可在調用鏈分析頁面按需篩選查詢。Attribute 名稱預設具有 biz. 首碼，不允許重複。

規則配置說明

參數	說明
規則名稱	該條規則的可讀名稱。
Attribute名称	提取值對應的 Span Attribute 名稱，預設以 `biz.` 開頭，後續由多個單片語成，每個單詞僅允許由大小寫字母、數字、短劃線（`-`）、底線（`_`）組成，單詞與單詞之間必須以一個半形句號（`.`）分隔。最多允許 10 個單詞。
参数提取类型	需要提取的參數類型（HTTP服务端请求/HTTP服务端响应/HTTP客户端请求/HTTP客户端响应）。
生效接口	規則作用的介面範圍，探針僅對匹配成功的介面提取相應參數，匹配語義詳見生效介面如何匹配。支援的匹配方式：等於、開始於、結束於、正則匹配、所有介面。
参数提取规则	定義待提取參數所在的實際載體來源和提取後的處理方式，支援配置多個參數來源和提取步驟。若多個來源均可提取到參數，排序在前的參數擷取規則優先順序高於後者。
参数来源	待提取參數所在的實際載體來源（Header、Query Parameter、Cookie、Body）。參數來源根據所選参数提取类型聯動過濾可選項。
參數處理步驟	流式的參數處理步驟，用於逐步解析參數載體並提取最終的參數值。可添加多條參數處理步驟，前者的解析結果會成為後者的輸入。如果不添加處理步驟，則提取到的參數值為載體對象的 JSON 文本。
是否啟用	該條規則是否啟用。

參數處理方式

Python 版支援的參數處理方式如下：

參數處理方式	輸入	輸出	說明
JsonPath	JSON 字串 / JSON 對象	String	支援點標記法的 JsonPath 語句，命中多個值時取第一個。樣本：`$.data.code`。
Regex	String	String	支援基於命名分組的Regex語句，待提取的子串對應名為 `res` 的分組，採用全匹配語義（正則需匹配完整輸入，而非子串搜尋）。樣本：`.from:(?<res>[a-z]+).`。

生效介面如何匹配

生效接口匹配的對象是 Span 名稱，格式為 要求方法路由，例如 POST /api/order、GET /api/user/{id}。因此：

等於 /api/order不會命中，應配置為 等於 POST /api/order。
或使用 以 /api/order 結尾。
或使用正則 .*/api/order（正則同樣為全匹配語義）。

值處理說明

截斷：提取值超過最大長度限制（預設 100 字元）會被截斷並以 ... 結尾。若需要提取較長的 Body 欄位，請調大提取值長度限制。
多值合并：同名 Header/Query Parameter 存在多個值時，會合并為 [a,b,c] 形式的字串。
脫敏：開啟脫敏後，提取值統一替換為 ***。
Cookie：同名 Cookie 以最後一個值為準；響應階段的 Cookie 來源讀取的是請求側的 Cookie。

生效驗證

參數擷取規則配置完成後即可生效（首次建立規則除外，需重啟應用後生效）。在調用鏈分析頁面查看相關調用鏈，如果對應介面的 Span Attributes 已有自訂 Attribute 被寫入，說明擷取規則生效。

找到新增規則對應的 Attribute 名稱。
在調用鏈分析頁面添加 attributes.$attributesName 作為查詢條件，過濾相關 Span。
單擊任意一條 Trace，在對應的 Span 下查看自訂的 Attributes。

管理規則

啟用/禁用規則：在目標規則右側設定是否啟用開關。
編輯和刪除：在目標規則右側單擊編輯或刪除，修改或刪除對應規則。
大量刪除：選中需要刪除的擷取規則，單擊大量刪除。
批量複製：選中需要複製的擷取規則，單擊批量複製至其他應用，開啟對話方塊後選擇複製到其他所有應用或指定應用。
- 批量複製至其他應用需要 1~2 分鐘生效。
- 該功能僅複製參數擷取規則，配套的自訂錯誤不會被複製到目標應用。
- 參數擷取規則要求 Attribute 名稱唯一，如果目標應用已存在同樣的 Attribute 名稱，則該條規則不會被複製到目標應用。

常見問題

什麼情況下會導致參數提取失敗？

參數提取類型或來源超出支援範圍（例如用戶端的 Body/Cookie 來源），請參見支援範圍說明確認當前架構和來源是否支援。
生效介面的匹配規則配置有誤。注意匹配對象為 要求方法路由 格式的 Span 名稱，等於 /api/order 形式的規則不會命中，請參見生效介面如何匹配。
參數處理步驟的文法配置有誤，或輸入類型與處理方式的要求不匹配：
- Regex 必須包含名為 res 的命名分組，且為全匹配語義。如需匹配子串，應在兩側補充 .*。
- JsonPath 的輸入必須是 JSON 對象或 JSON 文本；對一般字元串（如 Header 值 abc）執行 JsonPath 不會產出結果。
Python 探針版本低於 3.1.0，不支援業務參數提取功能。
首次建立規則後未重啟應用。

什麼情況下會導致 Body 提取不到？

為了保證不影響應用自身對請求/響應體的讀取，探針在讀取 Body 前會先做准入檢查，以下任一條件不滿足時，Body 來源會被整體跳過（不會截斷後解析）：

Content-Type 不是 JSON。僅支援 application/json 或以 +json 結尾的媒體類型；text/plain、application/x-www-form-urlencoded、multipart/form-data、二進位等類型不會提取。
Content-Length 缺失或超限。要求標頭中沒有 Content-Length（例如 chunked 分塊傳輸），或 Body 長度超過上限（預設 64 KB）時整體跳過。
Body 不是合法的 UTF-8 編碼 JSON。解碼或 JSON 解析失敗時跳過。
流式響應。Flask 的流式/direct_passthrough 響應、Django 的 StreamingHttpResponse、FastAPI/Starlette 的 StreamingResponse（含 SSE）均不提取響應 Body。

此外還有各架構特有的情況：

FastAPI：請求 Body 只有在應用側實際讀取時才可見——即介面聲明了 Body 參數（如 Pydantic 模型、Body()），或代碼中調用了 await request.body() / await request.json()。如果介面沒有讀取請求體，探針不會主動消費請求流，Body 也就無法提取。
Django：如果應用先通過 request.read() 等方式直接消費了請求流（觸發 RawPostDataException），或 Body 超過 Django 的 DATA_UPLOAD_MAX_MEMORY_SIZE 限制（觸發 RequestDataTooBig），Body 無法提取。正常通過 request.body 讀取不受影響（Django 會緩衝，應用仍可正常讀取）。
Flask：探針通過 request.get_data(cache=True) 讀取並緩衝請求體，應用後續仍可正常讀取，一般無額外限制。

提取到的值和預期不一致？

值以 ... 結尾：超過提取值長度限制（預設 100 字元）被截斷，可調大長度限制。
值為 ***：該規則或全域開啟了脫敏。
值形如 [a,b]：同名 Header/Query Parameter 存在多個值時的合并結果。
JsonPath 命中多個節點時只取第一個結果。
多個規則寫入了相同的 Attribute 名稱時，後應用的規則會覆蓋前者。

請求 Body 是 form 表單，能否用 Query Parameter 來源提取表單欄位？

不能。當請求的 Content-Type 為 application/x-www-form-urlencoded 時，為避免探針觸發架構的表單解析、影響應用自身讀取請求體，Query Parameter 來源會被整體跳過。此類參數建議改為通過 URL 查詢串或 Header 傳遞，或參考下一條使用自訂埋點。

Python 版目前不支援的業務參數來源如何提取？

可通過引入 OpenTelemetry SDK 為 Python 應用添加自訂埋點，將業務參數作為 Attributes 寫入 Span。