設定快訊和通知

您目前查看的是 Apigee Edge 說明文件。
參閱 Apigee X 說明文件
資訊

快訊條件會定義特定狀態碼 (例如 404/502/2xx/4xx/5xx)、延遲時間和錯誤代碼門檻。如果超過 UI 中觸發的視覺化快訊,並透過各種管道傳送通知,例如電子郵件、亂數、呼叫器或 Webhook。您可以在環境、API Proxy、目標服務或區域層級設定快訊。觸發快訊時,系統會使用您新增快訊和通知時所定義的方法收到通知。

舉例來說,如果部署至實際工作環境的訂單 API Proxy,當錯誤率超過 23% 且持續 5 分鐘,且超過 5xx 錯誤率達 23% 時就會觸發快訊並傳送通知給作業團隊。

下圖顯示快訊在 UI 中的顯示方式:

以下提供您在觸發快訊時會收到的電子郵件通知範例。

在快訊通知內文中,按一下下方連結即可瞭解詳情:

  • 查看詳細資料,查看更多詳細資料,包括過去 1 小時內各個條件的快訊設定和活動。
  • 快訊定義:查看快訊的定義。
  • 快訊記錄:查看特定快訊的詳細資訊。
  • 查看教戰手冊 (如有提供) 查看建議採取的行動。
  • 查看 API Analytics (分析) 報表:查看快訊條件的自訂報表。

以下各節將說明如何設定及管理快訊和通知。

關於快訊類型

初始版的 API Monitoring 可讓您建立模式規則,以指定根據一組預先定義的條件發出快訊的時機。這些類型的快訊稱為「固定」快訊,這是 API Monitoring 初始版本支援的唯一快訊類型。

舉例來說,您可以在發生下列情況時引發「固定」快訊:

  • [target mytarget1] 的 [rate of 5xx errors] [大於] [10%] 持續 [10 分鐘]
  • [region us-east-1] 中的 [count of 2xx 錯誤] [小於] [50] ([5 分鐘])
  • [p90 違反政策] [大於] [750ms] ([10 minutes] (Proxy myproxy1)

19.11.13 安全性報告 Beta 版新增了以下類型的快訊:

  • 總流量 (Beta 版) 快訊。 此快訊類型可讓您針對一段時間內的流量在指定百分比變化時發出快訊。
  • 異常 (Beta 版) 快訊。這類快訊類型可讓 Edge 偵測流量和效能問題,您不必自行預先判定。然後,您可以提出這些異常狀況的快訊。
  • 傳輸層安全標準 (TLS) 到期 (Beta 版) 快訊。如果 TLS 憑證即將過期,您可以透過這種快訊類型發出通知。

由於 API Monitoring 現在支援多種快訊,因此「建立快訊」對話方塊現在會顯示選取快訊類型的選項:

建立快訊對話方塊現在支援多種快訊類型

查看快訊設定

如要查看目前定義的快訊設定,請在 Edge UI 中依序點選「分析」>「快訊規則」

「快訊」頁面會顯示,如下圖所示:

快訊電子郵件

如圖所示,「快訊」頁面可讓您執行下列操作:

查看貴機構已觸發的快訊記錄

如要查看貴機構在過去 24 小時內觸發的快訊記錄,請在 Edge UI 中依序點選「Analyze」>「Alert Rules」,然後按一下「History」分頁標籤。

「快訊記錄」頁面會隨即顯示。

快訊記錄

按一下快訊名稱,即可在「調查資訊主頁」中查看快訊詳細資料。您可以搜尋全部或部分的快訊名稱,藉此篩選清單。

新增快訊和通知

如要新增快訊和通知,請按照下列步驟操作:

  1. 在 Edge UI 中依序點選「Analyze」>「Alert Rules」
  2. 按一下「+ 快訊」
  3. 輸入下列快訊的一般資訊:
    欄位 說明
    快訊名稱 快訊的名稱。請使用有意義的名稱,描述觸發條件。名稱長度不得超過 128 個字元。
    快訊類型 選取「已修正」。如要進一步瞭解快訊類型,請參閱「關於快訊類型」一文。
    說明 快訊的說明。
    環境 從下拉式選單中選取環境。
    狀態 切換啟用或停用快訊。
  4. 為觸發快訊的第一個條件定義指標、門檻和維度。
    條件欄位 說明
    指標

    選取下列其中一個指標:

    • 狀態碼:從清單中選取狀態碼,例如 401、404、2xx、4xx 或 5xx HTTP。

      注意

      • API 可讓您設定更多種狀態碼。使用 API 指定介於 200-299、400-599 和萬用字元值 2xx、4xx 或 5xx 之間的任何狀態碼。請參閱「建立快訊」。
      • 如要接收頻率限制快訊 (HTTP 狀態碼 429),請將指標設為「Spike Arrest fault code」
      • 您可以使用 AssignMessage 政策從 Proxy 錯誤或目標錯誤上重寫 HTTP 回應代碼。API Monitoring 會忽略所有重寫的代碼,並記錄實際的 HTTP 回應代碼。
    • 延遲:從下拉式選單中選取延遲時間值。具體來說:p50 (第 50 個百分位數)、p90 (第 90 個百分位數)、p95 (第 95 個百分位數) 或 p99 (第 99 小時)。舉例來說,選取「p95」即可設定快訊,當第 95 個百分位數的回應延遲時間高於下方設定的門檻時,系統就會觸發快訊。
    • Fault Code:從清單中選取類別、子類別和錯誤代碼。或是在某個類別或子類別中選取下列其中一項:

      • 全部:這個類別/子類別中所有錯誤代碼的合併總數必須符合指標條件。
      • 不限:這個類別/子類別中的單一錯誤代碼必須符合指標條件。

      詳情請參閱 Fault 程式碼參考資料

    • 總流量 (Beta 版):選取流量的增減比例。 詳情請參閱路況 (Beta 版) 快訊

    門檻

    為所選指標設定門檻:

    • 狀態碼:將門檻設定成階段性的百分比、計數或每秒交易次數 (TPS)。
    • 延遲時間:選取一段時間內的總延遲時間 (毫秒) 或目標延遲時間 (毫秒)。在此情況下,如果指定的百分位數觀察到延遲時間達到指定百分比,系統就會觸發快訊。如果有流量,系統就會每分鐘更新一次,超過特定時間範圍內的門檻條件。也就是說,門檻條件不會在整個時間範圍內匯總。
    • Fault Code:將門檻設定為指定期間內的百分比、計數或每秒交易次數 (TPS)。
    維度 按一下「+新增維度」,然後指定要傳回結果的維度詳情,包括 API Proxy、目標服務或開發人員應用程式和區域。

    如果您將特定維度設為:

    • 全部:維度中的所有實體都必須符合指標條件。 您無法針對「延遲時間」類型的指標選取「全部」
    • 不限:僅適用於地區。維度中的實體必須符合任何單一區域的指標條件。
      注意:如果是 API Proxy 或目標服務,請選取支援「任何」功能的集合。
    • 集合:從清單中選取集合,即可指定一組 API Proxy 或目標服務。在這種情況下,集合中的所有實體都必須符合條件。

    將維度設為「目標」時,可以選取目標服務或 Service 呼叫 政策指定的服務。Service 呼叫政策的目標會顯示為前置字串「sc://」的值,例如「sc://my.endpoint.net」。

  5. 按一下「顯示條件資料」,即可查看過去 1 小時內的條件資料。
    如果錯誤率超過快訊條件門檻,圖表中就會顯示紅色。
    顯示條件資料

    按一下「隱藏條件資料」即可隱藏資料。

  6. 按一下「+ 新增條件」即可加入其他條件,並重複執行步驟 4 和 5。

    注意:如果您指定多個條件,只要符合「所有」條件,就會觸發快訊。

  7. 如果您想根據設定的快訊條件建立自訂報表,請按一下「根據快訊條件建立 API 數據分析報表」。如果您不是機構管理員,這個選項會顯示為灰色。

    詳情請參閱「透過快訊建立自訂報表」一文。

    注意:您可以在儲存快訊後修改自訂報表,如「管理自訂報表」一文所述。

  8. 按一下「+ 通知」即可新增快訊通知。
    通知詳細資訊 說明
    管道 選取您要使用的通知管道,並指定目的地:電子郵件、Slack、PagerDuty 或 Webhook。
    目的地 根據所選管道類型指定目的地:
    • 電子郵件 - 電子郵件地址,例如 joe@company.com
    • Slack - Slack 頻道網址,例如 https://hooks.slack.com/services/T00000000/B00000000/XXXXX
    • PagerDuty - PagerDuty 程式碼,例如 abcd1234efgh56789
    • Webhook - Webhook 網址,例如 https://apigee.com/test-webhook。如需傳送至網址的物件說明,請參閱 Webhook 物件格式一文。

      在 Webhook 網址中傳送任何憑證資訊。例如 https://apigee.com/test-webhook?auth_token=1234_abcd

      您可以指定端點網址,讓端點能剖析 Webhook 物件,以便修改或處理。 舉例來說,您可以指定 API (例如 Edge API) 或其他可處理物件的端點的網址。

      注意:每則通知只能指定一個目的地。如要為同一個頻道類型指定多個目的地,請新增其他通知。

  9. 如要新增其他通知,請重複步驟 8。
  10. 如果您已新增通知,請設定下列欄位:
    欄位 說明
    教戰手冊 (選用) 任意形式的文字欄位,提供簡短說明,建議該動作在觸發時解決。您也可以指定您的內部維基或社群網頁連結,參考最佳作法。這個欄位中的資訊會顯示在通知中。這個欄位的內容長度不得超過 1500 個半形字元。
    節流 傳送通知的頻率。從下拉式選單中選取所需值。有效值包括:15 分鐘、30 分鐘和 1 小時。
  11. 按一下「儲存」

Webhook 物件格式

如果您指定 Webhook 網址做為快訊通知的目的地,則傳送至網址的物件將採用下列格式:
{
  "alertInstanceId": "event-id",
  "alertName": "name",
  "org": "org-name",
  "description": "alert-description",
  "alertId": "alert-id",
  "alertTime": "alert-timestamp",
  "thresholdViolations":{"Count0": "Duration=threshold-duration Region=region Status Code=2xx Proxy=proxy Violation=violation-description"
  },
  "thresholdViolationsFormatted": [
    {
      "metric": "count",
      "duration": "threshold-duration",
      "proxy": "proxy",
      "region": "region",
      "statusCode": "2xx",
      "violation": "violation-description"
    }
  ],
  "playbook": "playbook-link"
}

thresholdViolationsthresholdViolationsFormatted 屬性包含快訊的詳細資料。thresholdViolations 屬性包含單一字串並提供詳細資料,thresholdViolationsFormatted 則包含說明快訊的物件。一般會使用 thresholdViolationsFormatted 屬性,因為解碼起來會比較簡單。

上方範例顯示了您在根據 HTTP 2xx 狀態碼設定快訊來觸發時 (如 statusCode 屬性所示),「固定」快訊會顯示這些屬性的內容。

這些屬性的內容取決於快訊類型 (例如固定或異常狀況),以及快訊的特定設定。舉例來說,如果您根據錯誤代碼建立固定快訊,則 thresholdViolationsFormatted 屬性會包含 faultCode 屬性,而不是 statusCode 屬性。

下表列出不同快訊類型的 thresholdViolationsFormatted 屬性所有可能屬性:

快訊類型 可能的 Level violationsFormatted 內容
Fixed
metric, proxy, target, developerApp,
region, statusCode, faultCodeCategory, faultCodeSubCategory,
faultCode, percentile, comparisonType, thresholdValue,
triggerValue, duration, violation
總分數
metric, proxy, target, developerApp,
region, comparisonType, thresholdValue, triggerValue,
duration, violation
異常狀況
metric, proxy, target, region,
statusCode, faultCode, percentile, sensitivity,
violation
TLS 到期
envName, certificateName, thresholdValue, violation

透過快訊建立自訂報表

如要透過快訊建立自訂報表,請按照下列步驟進行:

  1. 建立快訊時,請按一下「根據快訊條件建立 API 分析報表」,詳情請參閱「新增快訊和通知」。

    儲存快訊後,UI 會顯示以下訊息:

    Alert alertName saved successfully. To customize the report generated, click here.

    按一下訊息即可在新分頁中開啟報表,並預先填入相關欄位。自訂報表的預設名稱: API Monitoring Generated alertName

  2. 視需要編輯自訂報表,然後按一下「儲存」
  3. 按一下清單上的報表名稱,然後執行自訂報表

如何管理根據快訊條件建立的自訂報表:

  1. 在 Edge UI 中依序點選「Analyze」>「Alert Rules」
  2. 按一下「設定」分頁標籤
  3. 在「報表」欄中,按一下與要管理快訊相關的自訂報表。

    自訂報表頁面會顯示在新分頁中。如果「報表」欄空白,表示尚未建立自訂報表。您可以視需要編輯快訊,新增自訂報表。

  4. 視需要編輯自訂報表,然後按一下「儲存」
  5. 按一下清單上的報表名稱,然後執行自訂報表

啟用或停用快訊

如何啟用或停用快訊:

  1. 在 Edge UI 中依序點選「Analyze」>「Alert Rules」
  2. 在您要啟用或停用的快訊相關快訊中,按一下「狀態」欄中的切換鈕。

編輯快訊

如要編輯快訊,請按照下列步驟操作:

  1. 在 Edge UI 中依序點選「Analyze」>「Alert Rules」
  2. 按一下要編輯的快訊名稱。
  3. 視需要編輯快訊。
  4. 按一下「儲存」。

刪除快訊

如何刪除快訊:

  1. 在 Edge UI 中依序點選「Analyze」>「Alert Rules」
  2. 將遊標懸停在要刪除的快訊上,然後按一下動作選單中的

Apigee 建議您設定下列快訊,接收常見問題的通知。部分快訊僅適用於 API 實作,且只有在特定情況下才適用。舉例來說,只有在使用 Service 呼叫政策Java 呼叫政策時,才適用下列顯示的幾種快訊。

快訊 使用者介面範例 API 範例
所有 API 的 5xx 狀態碼 為 API Proxy 設定 5xx 狀態碼快訊 使用 API 為 API Proxy 設定 5xx 狀態碼快訊
API Proxy 的 P95 延遲時間 設定 API Proxy 的 P95 延遲快訊 使用 API 為 API Proxy 設定 P95 延遲快訊
所有 API Proxy 的 404 (Application Not Found) 狀態碼 為所有 API Proxy 設定 404 (找不到應用程式) 狀態碼快訊 使用 API 為所有 API Proxy 設定 404 (找不到應用程式) 狀態碼快訊
API 的 API Proxy 數量 為 API 設定 API Proxy 數量快訊 為使用 API 的 API 設定 API Proxy 數量快訊
目標服務的錯誤率 為目標服務設定錯誤率快訊 使用 API 為目標服務設定錯誤率快訊
服務呼叫政策的錯誤率 (如適用) 為 Service 呼叫 政策設定錯誤率快訊 使用 API 為 Service 呼叫 政策設定錯誤率快訊
特定錯誤代碼,包括:
  • API 通訊協定錯誤 (通常為 4xx)
    • UI:API 通訊協定 > 全部
    • API:
      "faultCodeCategory":"API Protocol",
      "faultCodeSubCategory":"ALL"
  • 全部接收的 HTTP 錯誤
    • UI:「Gateway」(閘道) >「Other」(其他) >「Gateway HTTPErrorResponseCode」
    • API:
      "faultCodeCategory": "Gateway",
      "faultCodeSubCategory": "Others",
      "faultCodeName": "Gateway HTTPErrorResponseCode"
  • Java 服務呼叫執行錯誤 (如適用)
    • 使用者介面:「Execution Policy」>「Java callout」>「Java callout ExecutionFailed」
    • API:
      "faultCodeCategory": "Execution Policy",
      "faultCodeSubCategory": "Java Callout",
      "faultCodeName": "JavaCallout ExecutionFailed"
  • 節點指令碼執行錯誤 (如適用)
    • UI:Execution Policy > Node Script > NodeScript ExecutionError
    • API:
      "faultCodeCategory": "Execution Policy",
      "faultCodeSubCategory": "Node Script",
      "faultCodeName": "NodeScript ExecutionError"
  • 配額違規事項
    • 使用者介面:流量管理政策 > 配額 > 配額違規
    • API:
      "faultCodeCategory": "Traffic Mgmt Policy",
      "faultCodeSubCategory": "Quota",
      "faultCodeName": "Quota Violation"
  • 安全性政策錯誤
    • UI:安全性政策 > 任何
    • API:
      "faultCodeCategory": "Security Policy",
      "faultCodeName": "Any"
  • Sense 錯誤 (如適用)
    • 使用者介面:Sense > Sense > Sense IncreaseFault
    • API:
      "faultCodeCategory": "Sense",
      "faultCodeSubCategory": "Sense",
      "faultCodeName": "Sense RaiseFault"
  • 服務呼叫執行錯誤 (如適用)
    • 使用者介面:「Execution Policy」>「Service callout」>「Service callout ExecutionFailed」
    • API:
      "faultCodeCategory": "Execution Policy",
      "faultCodeSubCategory": "Service Callout",
      "faultCodeName": "ServiceCallout ExecutionFailed"
  • 目標錯誤
    • UI:閘道 > 目標 > Gateway TimeoutWithTargetOr 附近的
    • API:
      "faultCodeCategory": "Gateway",
      "faultCodeSubCategory": "Target",
      "faultCodeName": "Gateway TimeoutWithTargetOrCallout"
  • 目標錯誤,沒有有效目標
    • UI:Gateway > Target > Gateway TargetServerConfiguredInLoadBalancersIsDown
    • API:
      "faultCodeCategory": "Gateway",
      "faultCodeSubCategory": "Target",
      "faultCodeName": "Gateway TargetServerConfiguredInLoadBalancerIsDown
  • 目標錯誤,非預期的 EOF
    • UI:Gateway > Target > Gateway UnexpectedEOFAtTarget
    • API:
      "faultCodeCategory": "Gateway", "faultCodeSubCategory": "Target", "faultCodeName" : "Gateway UnexpectedEOFAtTarget"
  • 虛擬主機錯誤
    • UI:Gateway > Virtual Host > VirtualHost InvalidKeystoreOrTrustStore
    • API:
      "faultCodeCategory": "Gateway",
      "faultCodeSubCategory": "Virtual Host",
      "faultCodeName": "VirtualHost InvalidKeystoreOrTrustStore"
設定政策錯誤代碼快訊 使用 API 設定政策錯誤程式碼快訊

為 API Proxy 設定 5xx 狀態碼快訊

以下示例說明如何透過使用者介面設定快訊,當飯店 API Proxy 的每秒狀態碼為 5xx 狀態碼 (TPS) 超過 100 分鐘,且任何區域的交易時間超過 10 分鐘時,就會觸發快訊。詳情請參閱新增快訊和通知

如要進一步瞭解如何使用 API,請參閱使用 API 為 Proxy 設定 5xx 狀態碼警示

設定 API Proxy 的 P95 延遲時間快訊

以下範例說明如何透過 UI 設定快訊,當任何區域的飯店 API Proxy 於第 95 個百分位數的總回應延遲時間超過 100 毫秒時,達到 100 毫秒時,就會觸發快訊。詳情請參閱新增快訊和通知

如要進一步瞭解如何使用 API,請參閱使用 API 為 API Proxy 設定 P95 延遲快訊

為所有 API Proxy 設定 404 (找不到應用程式) 快訊

以下範例說明如何透過 UI 設定快訊,當所有 API Proxy 的 404 狀態碼百分比在所有區域的 5 分鐘內超過 5% 時,就會觸發快訊。詳情請參閱新增快訊和通知

如要進一步瞭解如何使用 API,請參閱使用 API 為所有 API Proxy 設定 404 (Application Not Found) 快訊

為 API 設定 API Proxy 數量快訊

以下範例說明如何透過使用者介面設定快訊,當任何區域的 API 中,有 5xx 代碼超過 200 且多 5 分鐘時就會觸發。在此範例中,API 擷取到 Critical API Proxy 集合中。詳情請參閱:

如要進一步瞭解如何使用 API,請參閱「為使用 API 的 API 設定 API Proxy 數量快訊」一文。

為目標服務設定錯誤率快訊

以下範例說明如何透過 UI 設定快訊,當目標服務中的 500 次代碼使用率超過任一區域的 1 小時超過 10% 時,系統就會觸發快訊。在此範例中,目標服務會擷取到「關鍵目標」集合中。詳情請參閱:

如要進一步瞭解如何使用 API,請參閱「使用 API 為目標服務設定錯誤率快訊」。

為 Service 呼叫 政策設定錯誤率快訊

以下範例說明如何透過 UI 設定快訊,當 Service Call Call 政策指定服務的 500 次代碼率超過任何區域的 1 小時達 10% 時,就會觸發快訊。詳情請參閱:

如要進一步瞭解如何使用 API,請參閱「使用 API 為服務呼叫政策設定錯誤率快訊」一文。

設定政策錯誤代碼快訊

以下範例說明如何透過 UI 設定快訊,當 Verify JWT 政策JWT AlgorithmMismatch 錯誤代碼數量超過 5 分鐘且所有 API 超過 5 分鐘時,就會觸發快訊。詳情請參閱:

如要進一步瞭解如何使用 API,請參閱使用 API 為政策錯誤程式碼設定錯誤程式碼快訊