本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 故障診斷和監控 函數
<a name="monetization-functions-troubleshooting"></a>

此頁面可協助您診斷常見的函數錯誤，並監控生產中的函數效能。故障診斷區段依症狀進行組織 — 從您觀察到的內容開始，然後遵循原因和修正。

## 監控
<a name="monetization-functions-troubleshooting-monitoring"></a>

### CloudWatch 指標
<a name="monetization-functions-troubleshooting-cw-metrics"></a>

MediaTailor 會將函數執行的指標發佈至 Amazon CloudWatch。不需要選擇加入。

**勾點層級指標** — 每個生命週期勾點執行一個資料點：


| 指標 | 說明 | 維度 | 
| --- | --- | --- | 
| PreSessionInitHook.Invocations | 勾點執行計數 | ConfigurationName | 
| PreSessionInitHook.Errors | 勾點錯誤計數 | ConfigurationName | 
| PreSessionInitHook.Latency | 勾點執行時間 （毫秒） | ConfigurationName | 
| PreAdsRequestHook.Invocations | 勾點執行計數 | ConfigurationName | 
| PreAdsRequestHook.Errors | 勾點錯誤計數 | ConfigurationName | 
| PreAdsRequestHook.Latency | 勾點執行時間 （毫秒） | ConfigurationName | 

**函數層級指標** — 每個函數執行一個資料點：


| 指標 | 說明 | 維度 | 
| --- | --- | --- | 
| Function.Invocations | 函數執行計數 | ConfigurationName, FunctionId, FunctionType, HookType | 
| Function.Errors | 函數錯誤計數 | ConfigurationName, FunctionId, FunctionType, HookType | 
| Function.Latency | 函數執行時間 （毫秒） | ConfigurationName, FunctionId, FunctionType, HookType | 

如需設定警示和使用這些指標的詳細資訊，請參閱 [AWS Elemental MediaTailor 使用 Amazon CloudWatch 指標進行監控](monitoring-cloudwatch-metrics.md)。

### 日誌事件
<a name="monetization-functions-troubleshooting-log-events"></a>

MediaTailor 會發出日誌事件以進行函數執行。預設會發出錯誤事件。已完成和摘要事件為選擇加入。


| 事件類型 | 預設/選擇加入 | 日誌群組 | 說明 | 
| --- | --- | --- | --- | 
| PRE\_SESSION\_INIT\_HOOK\_SUMMARY | 選擇加入 | 資訊清單日誌 | 勾點執行摘要 （成功/錯誤） | 
| PRE\_SESSION\_INIT\_HOOK\_ERROR | 預設 | 資訊清單日誌 | 勾點失敗搭配 errorType 和 原因 | 
| PRE\_SESSION\_INIT\_FUNCTION\_COMPLETED | 選擇加入 | 資訊清單日誌 | 個別函數以輸入/輸出完成 | 
| PRE\_SESSION\_INIT\_FUNCTION\_ERROR | 預設 | 資訊清單日誌 | 個別函數失敗 | 
| PRE\_ADS\_REQUEST\_HOOK\_SUMMARY | 選擇加入 | ADS 互動日誌 | 勾點執行摘要 （成功/錯誤） | 
| PRE\_ADS\_REQUEST\_HOOK\_ERROR | 預設 | ADS 互動日誌 | 勾點失敗搭配 errorType 和 原因 | 
| PRE\_ADS\_REQUEST\_FUNCTION\_COMPLETED | 選擇加入 | ADS 互動日誌 | 個別函數以輸入/輸出完成 | 
| PRE\_ADS\_REQUEST\_FUNCTION\_ERROR | 預設 | ADS 互動日誌 | 個別函數失敗 | 

若要啟用選擇加入日誌事件，請參閱 [AWS Elemental MediaTailor 使用 Amazon CloudWatch 指標進行監控](monitoring-cloudwatch-metrics.md)。

使用 `eventId` 欄位來關聯相同執行的關聯層級和函數層級事件。

下列 Amazon CloudWatch Logs Insights 查詢會依 篩選函數錯誤事件`eventId`，以追蹤單一執行：

```
fields @timestamp, eventType, functionId, errorType, cause
| filter eventId = "5dc6f040-0f72-4e8c-a64e-25eeef62708c"
| sort @timestamp asc
```

## 疑難排解
<a name="monetization-functions-troubleshooting-guide"></a>

當函數失敗時，MediaTailor 會在錯誤事件中記錄 `errorType` 欄位。使用此欄位來識別失敗類別：


| 錯誤類型 | 說明 | 
| --- | --- | 
| SYNTAX\_ERROR | 表達式無法編譯或遇到執行時間類型錯誤 | 
| RESOURCE\_LIMIT\_ERROR | 表達式超過 CPU 時間、記憶體或堆疊深度限制 | 
| RESTRICTION\_ERROR | 表達式使用封鎖的函數，或超過輸入承載大小限制 | 
| TIMEOUT\_ERROR | 函數執行超過其時間限制 | 
| VALIDATION\_ERROR | 輸出路徑以目前勾點範圍內無法寫入的欄位為目標 | 
| INTERNAL\_ERROR | 與函數無關的基礎設施故障 | 

項目會依症狀組織，並在適用時參考這些錯誤類型。

### 運算式意外傳回 null
<a name="monetization-functions-ts-null"></a>

**徵狀：**預期填入的輸出值是玩家參數`null`或遺失。

**可能原因：**


| 原因 | 如何識別 | 修正 | 
| --- | --- | --- | 
| 此生命週期關聯中不存在輸入欄位。 | 您已在 PRE\_SESSION\_INITIALIZATION函數adsRequest.url中參考 。工作階段開始時無法使用 ADS 請求資料。 | 將函數移至PRE\_ADS\_REQUEST生命週期掛鉤，或使用不同的輸入欄位。請參閱 [lifecycle hook](monetization-functions-hooks.md)。 | 
| 工作階段資料中缺少輸入欄位。 | 您已參考 player\_params.campaign\_id，但播放器在工作階段初始化時未傳遞該參數。 | $exists() 使用 在存取之前檢查：{%$exists(player\_params.campaign\_id) ? player\_params.campaign\_id : 'default'%}。 | 
| 您會將物件或陣列寫入玩家參數或 ADS 請求。 | 這些命名空間只接受字串、數字和布林值。物件和陣列會篩選掉。 | 在 中存放複雜資料，temp.\*並在後續步驟中擷取字串、數字或布林值。 | 

### `RESOURCE_LIMIT_ERROR`：堆疊溢位
<a name="monetization-functions-ts-stack-overflow"></a>

**徵狀：** 函數失敗，並顯示 `errorType: "RESOURCE_LIMIT_ERROR"`和 `cause: "Stack overflow error"`。

**原因：**表達式超過 100 個層級的最大堆疊深度。這通常發生在深度巢狀條件式 (if/then/else) 表達式或複雜的變數指派。

這表示運算式的巢狀層級過多，MediaTailor 無法處理。

**修正：**簡化表達式。將複雜邏輯分成多個輸出項目，或在循序執行器中多個步驟。

### `RESOURCE_LIMIT_ERROR`：CPU 逾時
<a name="monetization-functions-ts-cpu-timeout"></a>

**徵狀：** 函數失敗，並顯示 `errorType: "RESOURCE_LIMIT_ERROR"`和 `cause: "Expression evaluation timeout: Check for infinite loop"`。

**原因：**表達式超過 100 毫秒 CPU 時間限制。這可能會在大型資料結構上執行昂貴運算的表達式中發生。

**修正：**降低表達式的複雜性。如果您正在處理大型陣列，請考慮將該邏輯移至外部服務，並使用 `HTTP_REQUEST`函數呼叫該邏輯。

### `RESTRICTION_ERROR`：不允許函數
<a name="monetization-functions-ts-function-not-allowed"></a>

**徵狀：** 函數失敗，並顯示 `errorType: "RESTRICTION_ERROR"`和 `cause: "Function '<name>' is not allowed"`。

**原因：**表達式會呼叫不在 38 個函數允許清單中的 JSONata 函數。常見範例包括 `$filter`、`$reduce`、`$split`、 `$eval`和 `$join`。

**修正：**檢查 `cause` 欄位是否有封鎖的函數名稱。將其取代為允許的替代方案。如需 38 個允許函數的完整清單，[JSONata 表達式參考](monetization-functions-jsonata.md)請參閱 。

常用的允許函數包括 `$string`、`$number`、`$contains`、 `$substring`和 `$encodeUrlComponent`。

### `RESTRICTION_ERROR`：表達式太長
<a name="monetization-functions-ts-expression-too-long"></a>

**徵狀：** 函數無法使用 建立或更新`cause: "Expression length <actual> exceeds limit <limit>"`。

**原因：**單一表達式超過 1，000 個字元。

**修正：**將表達式分成較小的部分。使用多個輸出項目，或在循序執行器中的多個步驟中分割邏輯。使用變數繫結 (`:=`) 以避免重複長子運算式。

### HTTP 錯誤：狀態碼為 null
<a name="monetization-functions-ts-status-null"></a>

**徵狀：**在`HTTP_REQUEST`函數的輸出中， `response.statusCode`為 `null`。

**原因：**無法連線外部 API、連線逾時或發生網路錯誤。發生這種情況時，MediaTailor 會將 `response.statusCode`設定為 `null`、 `response.body` 設定為 `null`，並將 `response.text`設定為 `"Internal Error"`。

**修正：**一律在存取回應資料`response.statusCode`之前檢查：

```
{%response.statusCode = 200 ? response.body.value : 'default'%}
```

此表達式會檢查 HTTP 呼叫是否傳回 200 狀態碼。如果是這樣，它會使用回應值。否則，它會回到預設值。

如果經常發生這種情況，請檢查外部 API 是否正常運作。`RequestTimeoutMilliseconds` 如果 API 速度緩慢，請考慮增加，如果您想要快速失敗，請考慮減少。

### HTTP 錯誤：回應內文為 null
<a name="monetization-functions-ts-body-null"></a>

**徵狀：** `response.statusCode`為 200，但 `response.body`為 `null`。

**原因：**回應內文不是有效的 JSON 或超過 20，000 個字元。MediaTailor 只會將最多 20，000 個字元的 JSON 回應剖析為 `response.body`。

**修正：**使用 `response.text`做為備用。`response.text` 欄位包含截斷為 20，000 個字元的原始回應內文：

```
{%response.statusCode = 200 ? ($exists(response.body.id) ? response.body.id : $substring(response.text, 0, 100)) : 'error'%}
```

如果您需要的資料超過 20，000 個字元的限制，請考慮要求外部 API 傳回較小的回應 （例如，透過請求特定欄位）。

### HTTP 錯誤：URL 驗證失敗
<a name="monetization-functions-ts-url-validation"></a>

**徵狀：**函數在執行時間失敗，並顯示有關 URL 格式錯誤、使用無效方案或超過長度上限的訊息。

**可能原因：**


| 原因 | 修正 | 
| --- | --- | 
| URL 不使用 http或 https。 | 確保 URL 表達式產生開頭為 http://或 的 URLhttps://。 | 
| 表達式評估之後，URL 超過 2，048 個字元。 | 縮短 URL。使用 POST 方法將大型參數值移至請求內文。 | 
| URL 格式不正確 （非有效的 URI)。 | 檢查表達式是否有遺失或額外的字元。$encodeUrlComponent() 用於可能包含特殊字元的查詢參數值。 | 

### `VALIDATION_ERROR`
<a name="monetization-functions-ts-validation-error"></a>

**徵狀：** 函數因 而失敗`errorType: "VALIDATION_ERROR"`。此錯誤可能發生在撰寫時間 （建立或更新函數時） 或執行時間 （函數在工作階段期間執行時）。

**可能原因：**


| 原因 | 範例 | 修正 | 
| --- | --- | --- | 
| 輸出金鑰以目前掛鉤無法寫入的命名空間為目標。 | 在連接至 的函數adsRequest.url中寫入 PRE\_SESSION\_INITIALIZATION。 | 檢查生命週期關聯中允許哪些輸出命名空間。 PRE\_SESSION\_INITIALIZATION只允許 player\_params.\*。將函數移至正確的勾點或變更輸出索引鍵。請參閱 [lifecycle hook](monetization-functions-hooks.md)。 | 
| 輸出金鑰使用無效的字元。 | 輸出金鑰，例如 player\_params.device type（含空格）。僅允許字母、數字、底線和連字號。 | 重新命名輸出金鑰以僅使用有效字元。例如，請player\_params.device\_type改用 。 | 
| 輸出金鑰的開頭不是有效的字首。 | 輸出金鑰，例如 custom.myValue而非 player\_params.myValue或 temp.myValue。 | 使用有效的輸出字首：temp.\*、 player\_params.\*或 adsRequest.\*。 | 
| JSONata 表達式有語法錯誤。 | 缺少關閉引號或不完整的條件：{%session.id & %}。 | 檢閱表達式是否有遺漏的引號、不相符的括號或不支援的運算子，例如 ??或 ?:。 | 
| HTTP\_REQUEST 函數中缺少必要欄位。 | URL 欄位為空白或未指定方法。 | 確保已設定 URL 和方法欄位。方法必須是 GET或 POST。 | 
| 運算式建立的 URL 無效。 | 評估的 URL 使用不支援的結構描述，例如 ftp://、超過 2，048 個字元，或格式不正確。 | 確認 URL 表達式產生有效的 http://或 https:// URL。$encodeUrlComponent() 用於可能包含特殊字元的查詢參數值。 | 
| HTTP 標頭包含無效的字元或使用限制名稱。 | 標頭值包含換行符號，或標頭名稱為 host或 transfer-encoding。 | 從標頭值移除無效字元。避免受限制的標頭名稱。如需標頭限制[HTTP\_REQUEST](monetization-functions-types-http-request.md)，請參閱 。 | 

檢查錯誤日誌事件中的 `cause` 欄位 - 它會識別哪個欄位或表達式驗證失敗。

### `INTERNAL_ERROR`
<a name="monetization-functions-ts-internal-error"></a>

**徵狀：** 函數因 而失敗`errorType: "INTERNAL_ERROR"`。

**原因：**發生與函數組態無關的基礎設施故障。

**修正：**重試請求。如果錯誤仍然存在，請聯絡 AWS Support。