Google Cloud Apigee 客服案件的最佳做法

您正在查看 Apigee Edge 說明文件。
請參閱 Apigee X 說明文件。 info

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

在客服案件中提供詳細的必要資訊，可協助 Google Cloud Apigee 支援團隊迅速且有效率地回覆您。如果您的客服案件缺少重要細節，我們會需要詢問更多資訊，這可能需要多次來回溝通。這會耗費更多時間，且可能導致問題解決時間延後。本最佳做法指南可讓您瞭解我們在解決技術性客服案件時所需要的資訊，

描述問題

問題應包含詳細資訊，說明發生的情況與預期情況的差異，以及發生的時間和方式。良好的 Apigee 支援案件應包含每個 Apigee 產品的下列重要資訊：

重要資訊 說明 適用於公用雲端的 Apigee Edge 私人雲端適用的 Apigee Edge
產品 發生問題的特定 Apigee 產品，包括適用的版本資訊。
  • 版本
問題詳細資料 清楚且詳細的問題說明，概述問題，包括完整的錯誤訊息 (如有)。
  • 錯誤訊息
  • 追蹤工具輸出內容
  • 重現問題的步驟
  • 完整的 API 要求/指令
  • 錯誤訊息
  • 追蹤工具輸出內容
  • 重現問題的步驟
  • 完整的 API 要求/指令
  • 元件診斷記錄
時間 問題開始發生的確切時間戳記，以及問題持續的時間。
  • 問題發生的日期、時間和時區
  • 問題持續時間
  • 問題發生的日期、時間和時區
  • 問題持續時間
設定 問題發生的詳細資訊。
  • 機構名稱
  • 環境名稱
  • API Proxy 名稱
  • 修訂版本
  • 網路拓撲
  • Edge 元件失敗

下列各節會進一步說明這些概念。

產品

我們提供多種 Apigee 產品，包括 Apigee Edge 公用雲和 Apigee Edge 私人雲，因此需要具體資訊，才能瞭解是哪個產品發生問題。

下表列出一些範例，說明「應做」欄中的完整資訊，以及「不應做」欄中的不完整資訊：

正確做法 禁止事項
在公用雲組織中部署 API Proxy OAuth2 失敗 ...

API Proxy 部署作業失敗

(我們需要知道您在哪個 Apigee 產品中遇到問題。)

在 Edge Private Cloud 4.50.00 版上安裝失敗，並顯示以下錯誤訊息 ...

在私有雲設定中安裝失敗。

(缺少版本資訊)

問題詳細資料

請提供觀察到的問題的確切資訊，包括錯誤訊息 (如有) 以及觀察到的預期和實際行為。

下表列出一些範例，說明「DO」欄位中的完整資訊，以及「DON'T」欄位中的不完整資訊：

正確做法 禁止事項

新的 edgemicro Proxy edgemicro_auth 發生錯誤，並顯示以下錯誤訊息：

{"error":"missing_authorization","error_description":"Missing Authorization header"}

今天建立的新 edgemicro proxy 無法運作

(代理伺服器名稱不明。無法確定 Proxy 是傳回錯誤或任何非預期的回應)。

我們的客戶在向 API 代理提出要求時，會收到 500 錯誤，並顯示以下錯誤訊息：

{"fault":{"faultstring":"Execution of JSReadResponse failed with error: Javascript runtime error: \"TypeError: Cannot read property \"content\" from undefined. (JSReadResponse.js:23)","detail":{"errorcode":"steps.javascript.ScriptExecutionFailed"}}}

我們的客戶在向 API 代理提出要求時，會收到 500 錯誤。

(僅傳送 500 錯誤並不足以提供我們調查問題的相關資訊。我們需要知道實際的錯誤訊息和觀察到的錯誤代碼)。

時間

時間是相當重要的資訊。支援工程師必須知道您首次發現問題的時間、問題持續多久，以及問題是否仍在發生。

負責解決問題的支援工程師可能不在您的時區，因此類似下列的敘述會使問題難以診斷。因此，建議您使用 ISO 8601 格式輸入日期時間戳記，以便提供問題發生時間的確切時間資訊。

下表列出一些範例，說明「應做」欄中顯示問題發生的確切時間和持續時間，以及「不應做」欄中顯示問題發生時間的模糊或不明確資訊：

正確做法 禁止事項
昨天在 2020-11-06 17:30 PDT 和 2020-11-06 17:35 PDT 之間，我們觀察到大量 503s...

昨天下午 5 點 30 分，我們發現有大量 503s 發生了 5 分鐘。

(我們必須使用隱含日期，而且也無法確認這個問題是在哪個時區發生)。
從 2020-11-09 15:30 IST 到 2020-11-09 18:10 IST，我們發現下列 API Proxy 的延遲時間過長 ...

上週我們發現部分 API Proxy 的延遲時間偏高。

(我們無法確認這個問題在過去一週內發生的日期和時間長度)。

設定

我們需要瞭解您在哪裡遇到問題的詳細資訊。視您使用的產品而定，我們需要以下資訊：

  • 如果您使用 Apigee Cloud，可能會有一個以上的機構，因此我們需要知道您觀察到問題的特定機構和其他詳細資料：
    • 機構和環境名稱
    • API Proxy 名稱和修訂版本號碼 (適用於 API 要求失敗)
  • 如果您使用私有雲 ，可能會使用多種支援的安裝拓樸之一。因此，我們需要瞭解您使用的拓撲結構，包括資料中心和節點數量等詳細資料。

下表列出一些範例，說明「DO」欄位中的完整資訊，以及「DON'T」欄位中的不完整資訊：

正確做法 禁止事項

401 自 2020 年 11 月 6 日 09:30 CST 起，Edge 公用雲中的錯誤數量增加。

Edge 設定詳細資料：

失敗 API 的詳細資料如下：
  機構名稱：myorg
  環境名稱：test
  API Proxy 名稱：myproxy
  修訂版本號碼：3

錯誤：

{"fault":{"faultstring":"Failed to resolve API Key variable request.header.X-APP-API_KEY","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}

401 錯誤數量增加。

(不會提供任何有關使用中產品的資訊，例如問題發生時的時間或任何設定詳細資料)。

新增其他閘道節點後，無法在 Edge Private Cloud 4.19.06 版本 啟動訊息處理器。

診斷記錄：
已附上 Message Processor 記錄。

網路拓撲：
已附加包含額外節點的檔案 network-topology.png。

新增其他閘道節點後，無法在 Edge Private Cloud 4.19.06 版本 啟動訊息處理器。

(缺少訊息處理器記錄和網路拓撲)。

有用的資料

提供與問題有關的資料可幫助我們確切瞭解您遇到的問題，以加速疑難排解。

本節將說明一些實用成果，可供所有 Apigee 產品使用：

所有 Apigee 產品的通用構件

以下構件適用於所有 Apigee 產品：Apigee Edge on Public Cloud 和 Apigee Edge on Private Cloud：

構件 說明
Trace 工具輸出內容 追蹤工具輸出內容包含透過 Apigee 產品傳送的 API 要求詳細資訊。這對於任何執行階段錯誤 (例如 4XX、5XX 和延遲問題) 都很有幫助。
螢幕截圖 螢幕截圖可協助我們瞭解實際行為或觀察到的錯誤。這項功能可協助您找出任何錯誤或問題，例如使用者介面或 Analytics 中的錯誤或問題。
HAR (HTTP 封存檔) HAR 是 HTTP 工作階段工具擷取的檔案，可用於偵錯任何 UI 相關問題。您可以使用 Chrome、Firefox 或 Internet Explorer 等瀏覽器擷取螢幕截圖。
tcpdumps tcpdump 工具會擷取透過網路傳送或接收的 TCP/IP 封包。這項功能可用於任何網路相關問題，例如 TLS 握手失敗、502 錯誤和延遲問題等。

Apigee Edge for Private Cloud 的其他構件

針對 Apigee Edge for Private Cloud，我們可能需要一些額外的構件，以便更快速地診斷問題。

構件 說明
網路拓撲 邊緣安裝拓樸圖表，說明私有雲設定，包括所有資料中心、節點和各節點中安裝的元件。
Edge 元件診斷記錄 與特定 Apigee Edge 元件 (例如 Message Processor、Router 或 Cassandra) 相關的診斷記錄。
安裝設定檔 安裝或升級 Apigee Edge 時使用的靜默設定檔。

遇到安裝或遷移問題時，您可以使用這個檔案驗證所有設定是否正確。
記憶體快照資料 記憶體快照資料是 Java 記憶體程序的快照。如果某些 Edge 元件出現記憶體使用率過高或 OutOfMemory 錯誤，這項功能就很實用。
執行緒傾印 執行緒傾印是執行中的 Java 程序所有執行緒的快照。

如果您發現特定 Edge 元件出現 CPU 或負載過高的問題，這項功能就非常實用。

個案範本和個案

本節將根據本文所述的最佳做法，提供不同產品的案件範本和示例案件：

公用雲端上的 Apigee Edge

範本

本節提供 Apigee Edge 公用雲端範本。

問題：

<請詳細說明問題或您觀察到的行為。請在適用情況下加入產品名稱和版本。>

錯誤訊息：

<Include the complete error message observed (if any)>

問題開始時間 (ISO 8601 格式)：

問題結束時間 (ISO 8601 格式)：

Apigee 設定詳細資料：
  機構名稱：
  環境名稱：
  API Proxy 名稱：
  修訂版本號碼：

重現問題的步驟：

<提供重現問題的步驟 (如有)>

診斷資訊：

<附件檔案清單>

範例

本節將提供 Apigee Cloud (Google Cloud 上的 Apigee/Apigee Edge 公用雲) 的範例案例。

問題：

我們在 公用雲 機構中看到大量 503 服務無法使用錯誤。請你調查並解決這個問題，或是建議我們如何解決這個問題。

錯誤訊息：

{"fault":{"faultstring":"The Service is temporarily available", "detail":{"errorcode":"messaging.adaptors.http.flow.ServiceUnavailable"}}}

問題開始時間 (ISO 8601 格式)：2020-10-04 06:30 IST

問題結束時間 (ISO 8601 格式)：問題仍在發生中。

Apigee Cloud 設定詳細資料：
  機構名稱：myorg
  環境名稱：dev
  API 代理程式名稱：myproxy
  修訂版本號碼：3

重現問題的步驟：

執行下列 curl 指令，重現問題：

curl -X GET 'https://myorg-dev.apigee.net/v1/myproxy'

診斷資訊：

追蹤工具輸出內容 (trace-503.xml)

私人雲端適用的 Apigee Edge

範本

本節提供 Apigee Edge for Private Cloud 的範本。

問題：

<請詳細說明問題或您觀察到的行為。請在適用情況下加入產品名稱和版本。>

錯誤訊息：

<Include the complete error message observed (if any)>

問題開始時間 (ISO 8601 格式)：

問題結束時間 (ISO 8601 格式)：

Edge Private Cloud 設定詳細資料：

<附上說明私有雲設定 (包括資料中心和節點) 的網路拓撲>

重現問題的步驟：

<提供重現問題的步驟 (如有)>

診斷資訊

<附件檔案清單>

範例

本節提供私人雲端適用的 Apigee Edge 範例。

問題：

在 Linux RHEL 7.6 上安裝 Edge Private Cloud 4.19.06 時，我們在 Node #10 上安裝 Apigee 管理伺服器，但遇到以下錯誤。

錯誤訊息：

<snipped as the output is too long>
Checking for management-server uuid ................................................
Unable to get uuid for management-server.
Error: setup.sh: /opt/apigee/apigee-service/bin/apigee-service exited with unexpected status 1

問題開始時間 (ISO 8601 格式)：每次安裝

問題結束時間(ISO 8601 格式)： 不適用

Edge Private Cloud 設定詳細資料：

已附上檔案 network-topology.png

重現問題的步驟：

以下是導致上述錯誤的指令：

/opt/apigee/apigee-setup/bin/setup.sh -p ms -f /app/NonProdConfig.txt

診斷資訊：

已附加下列檔案：

  • output.txt 包含上述指令的完整輸出內容，包括錯誤訊息
  • 管理伺服器記錄和
  • 設定檔 NonProdConfig.txt