設定快訊和通知

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件
資訊

快訊條件會定義特定狀態碼 (例如 404/502/2xx/4xx/5xx)、延遲和錯誤代碼閾值 (超過此值會在使用者介面中觸發視覺快訊),並透過電子郵件、Sslack、分頁 rduty 或 Webhook 等各種管道傳送通知。您可以在環境、API Proxy、目標服務或區域層級設定快訊。觸發快訊時,系統會使用您新增快訊和通知時定義的方法傳送通知。

舉例來說,對於部署至實際工作環境的 Order-prod API Proxy,5xx 錯誤率在 5 分鐘內超過 23% 時,您可能會想觸發快訊並傳送通知給營運團隊。

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

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

如需更多資訊,請在快訊通知內文中點選下列連結:

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

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

關於快訊類型

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

舉例來說,您可以在發生以下情況時發出「已修正」快訊:

  • [target mytarget1] [5xx 錯誤率] [大於] [10%] [10 分鐘] (從 [target mytarget1])
  • [region us-east-1] 的 [2xx 錯誤計數] [小於] [50],時間為 [5 分鐘]
  • [p90 延遲時間] 於 [proxy myproxy1] 上 [超過] [750 毫秒] [10 分鐘]

19.11.13 安全性報告 Beta 版新增不同類型的快訊:

  • 「總流量 (Beta 版)」快訊。快訊類型,可讓您針對一段時間內的流量變化,設定快訊。
  • 異常狀況 (Beta 版) 快訊。Edge 會偵測流量和效能問題的快訊類型,讓您不必自行預先定義。然後針對這些異常狀況發出警示。
  • TLS 過期 (Beta 版) 快訊。這個快訊類型,可在 TLS 憑證即將到期時傳送通知。

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

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

查看快訊設定

如要查看目前定義的快訊設定,請在 Edge UI 中依序點選「Analyze」>「Alert Rules」(快訊)

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

快訊電子郵件

如圖中所示,「快訊」頁面可讓您:

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

如要查看貴機構過去 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),請將指標設為「高強度跳離錯誤代碼」
      • 您可以使用 AssignMessage 政策重新編寫 HTTP 回應代碼,無論是來自 Proxy 錯誤或目標錯誤。API Monitoring 會忽略所有重寫的代碼,並記錄實際的 HTTP 回應代碼。
    • 「延遲時間」:從下拉式選單中選取延遲時間值。具體而言:p50 (第 50 個百分位數)、p90 (第 90 個百分位數)、p95 (第 95 個百分位數) 或 p99 (第 99 個百分位數)。舉例來說,選取「p95」即可設定快訊,在第 95 個百分位數的回應延遲時間大於下方設定的門檻時觸發。
    • 「Fault Code」:從清單中選取類別、子類別和錯誤代碼。或者,請選取下列其中一個類別或子類別:

      • 全部 - 此類別/子類別中所有錯誤碼的合併總數必須符合指標條件。
      • 任何 - 此類別/子類別中的單一錯誤碼必須符合指標條件。

      詳情請參閱「錯誤程式碼參考資料」。

    • 總流量 (Beta 版):選取增加或減少的流量。 詳情請參閱流量 (Beta 版) 快訊一文。

    門檻

    為所選指標設定門檻:

    • 狀態碼:針對一段時間內的百分比費率、計數或每秒交易次數 (TPS),設定門檻。
    • 延遲時間:以一段時間內的總時間長度或目標延遲時間 (毫秒) 為單位選取門檻。在此情況下,系統會在指定的觀察延遲時間 (百分位數) 時觸發快訊;如果有流量,超過指定時間範圍內的門檻條件,系統也會更新「每分鐘」(如果有流量的話)。也就是說,系統不會匯總整個時間範圍的閾值條件。
    • 錯誤代碼:以百分比速率、計數或每秒交易次數 (TPS) 設定一段時間內的門檻。
    維度 按一下「+ 新增維度」,然後指定要傳回結果的維度詳細資訊,包括 API Proxy、目標服務或開發人員應用程式和地區。

    如果您將某個維度設為:

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

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

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

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

  6. 按一下「+ 新增條件」即可新增其他條件,然後重複步驟 4 和 5。

    注意:如果指定多個條件,系統會在符合「所有」條件時觸發快訊。

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

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

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

  8. 按一下「+ 通知」即可新增快訊通知。
    通知詳細資訊 說明
    頻道 選取您要使用的通知管道,並指定目的地:Email、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 屬性的所有可能屬性:

快訊類型 可能的閾值違反格式內容
恆亮
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 callout 政策Java callout 政策,下列幾則快訊才適用。

快訊 UI 範例 API 範例
所有 API 均適用的 5xx 狀態碼 為 API Proxy 設定 5xx 狀態碼快訊 使用 API 為 API Proxy 設定 5xx 狀態碼快訊
API Proxy 的 P95 延遲時間 為 API Proxy 設定 P95 延遲時間快訊 使用 API 為 API Proxy 設定 P95 延遲時間快訊
所有 API Proxy 的 404 (找不到應用程式) 狀態碼 為所有 API Proxy 設定 404 (找不到應用程式) 狀態碼快訊 針對使用 API 的所有 API Proxy 設定 404 (找不到應用程式) 狀態碼快訊
API 的 API Proxy 數量 為 API 設定 API Proxy 數量快訊 使用 API 為 API 設定 API Proxy 數量快訊
目標服務的錯誤率 為目標服務設定錯誤率快訊 使用 API 為目標服務設定錯誤率快訊
服務呼叫政策的錯誤率 (如適用) 為服務呼叫政策設定錯誤率快訊 使用 API 為 Service callout 政策設定錯誤率快訊
特定錯誤代碼,包括:
  • 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 服務呼叫執行錯誤 (如適用)
    • UI:執行政策 > Java 呼叫 > 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"
  • 配額違規事項
    • UI:流量管理政策 > 配額 > 配額違規
    • API:
      "faultCodeCategory": "Traffic Mgmt Policy",
      "faultCodeSubCategory": "Quota",
      "faultCodeName": "Quota Violation"
  • 安全性政策錯誤
    • UI:安全性政策 > 不限
    • API:
      "faultCodeCategory": "Security Policy",
      "faultCodeName": "Any"
  • Sense 錯誤 (如適用)
    • 使用者介面:Sense > Sense > Sense GrowFault
    • API:
      "faultCodeCategory": "Sense",
      "faultCodeSubCategory": "Sense",
      "faultCodeName": "Sense RaiseFault"
  • 服務呼叫執行錯誤 (如適用)
    • UI:Execution Policy > 服務呼叫 > Service callout ExecutionFailed
    • API:
      "faultCodeCategory": "Execution Policy",
      "faultCodeSubCategory": "Service Callout",
      "faultCodeName": "ServiceCallout ExecutionFailed"
  • 目標錯誤
    • UI:Gateway > Target > Gateway TimeoutWithTargetOr 呼
    • API:
      "faultCodeCategory": "Gateway",
      "faultCodeSubCategory": "Target",
      "faultCodeName": "Gateway TimeoutWithTargetOrCallout"
  • 目標錯誤,沒有有效目標
    • UI:Gateway > 目標 > Gateway TargetServerConfiguredInLoadBalancersIsDown
    • API:
      "faultCodeCategory": "Gateway",
      "faultCodeSubCategory": "Target",
      "faultCodeName": "Gateway TargetServerConfiguredInLoadBalancerIsDown
  • 目標錯誤、非預期的結果
    • UI:Gateway > Target > Gateway UnexpectedEOFAtTarget
    • API:
      "faultCodeCategory": "Gateway", "faultCodeSubCategory": "Target", "faultCodeName" : "Gateway UnexpectedEOFAtTarget"
  • 虛擬主機錯誤
    • UI:「閘道」>「虛擬主機」>「VirtualHost InvalidKeystoreOrTrustStore」
    • API:
      "faultCodeCategory": "Gateway",
      "faultCodeSubCategory": "Virtual Host",
      "faultCodeName": "VirtualHost InvalidKeystoreOrTrustStore"
設定政策錯誤代碼快訊 使用 API 設定政策錯誤代碼快訊

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

以下範例展示如何在任一區域的飯店 API Proxy 每秒交易 (TPS) 5xx 狀態碼超過 100 分鐘時,在使用者介面設定快訊時觸發快訊。詳情請參閱新增快訊和通知

如要瞭解如何使用 API,請參閱使用 API 為 Proxy 設定 5xx 狀態碼快訊

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

以下展示如何在任一地區的飯店 API Proxy 達到 5 分鐘時,透過第 95 個百分位數的總回應延遲時間超過 100 毫秒時,透過使用者介面設定快訊的做法。詳情請參閱新增快訊和通知

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

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

以下範例說明如何透過使用者介面設定快訊,也就是在任何區域的所有 API Proxy 的 404 狀態碼百分比超過 5% 時觸發快訊。詳情請參閱新增快訊和通知

若要瞭解如何使用 API,請參閱「針對使用 API 的所有 API Proxy 設定 404 (找不到應用程式) 快訊」一文。

為 API 設定 API Proxy 數量快訊

以下示範如何在任一區域的 API 的 5xx 程式碼數量超過 200 個時觸發快訊,以及如何透過使用者介面設定快訊。在這個範例中,系統會在 Critical API Proxy 集合中擷取 API。詳情請參閱:

如要瞭解如何使用 API,請參閱使用 API 為 API 設定 API Proxy 數量快訊

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

以下範例說明如何使用使用者介面設定快訊,並在任一區域的目標服務的 500% 的程式碼比率超過 10% 時觸發快訊。在這個範例中,目標服務擷取到「關鍵目標」集合中。詳情請參閱:

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

為 Service callout 政策設定錯誤率快訊

以下提供範例,說明如何使用 UI 設定快訊;如果 Service callout 政策指定服務的 500 程式碼比率超過任一區域達 10%,就會觸發這個 UI。詳情請參閱:

如要瞭解如何使用 API,請參閱使用 API 為服務呼叫政策設定錯誤率快訊

設定政策錯誤代碼快訊

以下範例說明如何使用 UI 設定快訊;對於所有 API 而言,Verify JWT 政策JWT AlgorithmMismatch 錯誤代碼計數超過 5 分鐘時就會觸發。詳情請參閱:

如要瞭解如何使用 API,請參閱使用 API 針對政策錯誤程式碼設定錯誤代碼快訊