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

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

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

在客服案件中提供詳細和必要資訊，可讓 Google Cloud Apigee 支援團隊快速、有效率地回覆您。當您的客服案件缺少重要的詳細資料時，我們需要請您提供更多資訊，這可能會多次往返處理。這需要更多時間，並可能導致解決問題的時間延遲。 這份最佳做法指南說明我們需要相關資訊，協助您更快速地解決技術支援案件。

描述問題

問題應包含相關資訊，說明情況與預期會發生的情況，以及問題發生的時間和方式。在好的 Apigee 客服案件中，應針對每項 Apigee 產品包含以下重要資訊：

重要資訊 說明 公有雲的 Apigee Edge 私有雲的 Apigee Edge
產品 發現問題的特定 Apigee 產品，包括適用的版本資訊。
  • 版本
問題詳細資料 提供清楚詳盡的問題說明，其中概述問題，包括完整的錯誤訊息 (如有)。
  • 錯誤訊息
  • 追蹤工具輸出
  • 重現問題的步驟
  • 完整的 API 要求/指令
  • 錯誤訊息
  • 追蹤工具輸出
  • 重現問題的步驟
  • 完整的 API 要求/指令
  • 元件診斷記錄
時間 問題開始的確切時間戳記和持續時間長度。
  • 問題發生的日期、時間和時區
  • 問題發生時間
  • 問題發生的日期、時間和時區
  • 問題發生時間
設定 觀察問題的詳細資訊。
  • 機構名稱
  • Env 名稱
  • API Proxy 名稱
  • 修訂版本
  • 網路拓撲
  • 故障邊緣元件

以下各節會詳細說明這些概念。

產品

我們提供不同的 Apigee 產品、Apigee Edge 公用雲端和 Apigee Edge 私有雲，因此需要具體說明是哪項特定產品出現問題。

下表提供幾個範例，說明如何在「DOs」欄中顯示完整資訊，以及「DON'Ts」欄中不完整的資訊：

建議做法 錯誤做法
無法在公用雲端機構中部署 API Proxy「OAuth2」...

無法部署 API Proxy

(我們需要知道您發現問題的 Apigee 產品)。

安裝 Edge Private Cloud 4.50.00 版時出現下列錯誤，且安裝失敗 ...

無法在 Private Cloud 設定中安裝。

(缺少版本資訊)

問題詳細資料

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

下表提供幾個範例，說明如何在「DOs」欄中顯示完整資訊，以及「DON'Ts」欄中不完整的資訊：

建議做法 錯誤做法

新的 edgemicro Proxy edgemicro_auth 會失敗，並出現下列錯誤：

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

目前已建立新的 edgemicro Proxy 無法運作

(Proxy 名稱不明。不清楚 Proxy 是否傳回錯誤或任何非預期的回應)。

我們的用戶端在向 API Proxy 傳送要求時，收到 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 Proxy 發出要求時，發生 500 錯誤。

(如果只傳達 500 錯誤，我們並未提供足夠的資訊來調查問題。我們需要知道實際觀察到的實際錯誤訊息和錯誤代碼)。

時間

時間是非常重要的資訊。支援工程師瞭解您首次發現這個問題的時間、持續時間，以及問題是否持續發生，至關重要。

解決問題的支援工程師可能不是您所在時區，因此有關時間的相對陳述會導致問題難以診斷。因此，建議使用 ISO 8601 格式的日期和時間戳記，提供觀察問題的確切時間資訊。

下表列出一些示例，說明「DOs」欄發生問題的時間和持續時間，以及「DON'Ts」欄中問題發生時間的明確或不清楚資訊：

建議做法 錯誤做法
太平洋夏令時間 2020 年 11 月 6 日 17:30 至 2020-11-06 17:35 (太平洋夏令時間) 之間觀察到大量503s...

昨天下午 5:30 偵測到 5 分鐘的503s大量。

(我們會強制使用隱含的日期，同時不知道這個問題出現在哪個時區)。
我們在下列 API Proxy 的 2020-11-09 15:30 至 2020-11-09 18:10 (印度標準時間) 中觀察到高延遲時間 ...

上週部分 API Proxy 出現高延遲情形。

(我們無法確定上週發生這個問題的日期和持續時間)。

設定

我們需要您詳細瞭解問題發生在哪個地方。視您使用的產品而定，我們需要以下資訊：

  • 如果使用 Apigee Cloud，可能有多個機構，我們需要知道您觀察問題的確切機構和其他詳細資料：
    • 機構和環境名稱
    • API Proxy 名稱和修訂版本編號 (適用於 API 要求失敗)
  • 如果您使用的是 Private Cloud ，可能是其中一個系統支援的安裝拓撲。因此，我們需要瞭解您使用的拓撲，包括資料中心和節點數量等詳細資料。

下表提供幾個範例，說明如何在「DOs」欄中顯示完整資訊，以及「DON'Ts」欄中不完整的資訊：

建議做法 錯誤做法

401 自 2020-11-06 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 版 中啟動訊息處理者。

診斷記錄：
附加了訊息處理器記錄檔。

網路拓撲：
附加了含有其他節點的檔案 network-topology.png。

新增額外的閘道節點後，無法在 Edge Private Cloud 4.19.06 版 中啟動訊息處理者。

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

有用的資料

提供與問題相關的構件可以加快解決問題的速度，這有助於我們瞭解您觀察到的確切行為，並取得更多深入分析資料。

本節說明幾項對所有 Apigee 產品相當實用的實用構件：

所有 Apigee 產品的常見構件

下列構件適用於所有 Apigee 產品：Apigee Edge 公用雲端和 Apigee Edge 中的私有雲：

構件 說明
追蹤工具輸出內容 追蹤工具輸出結果內含透過 Apigee 產品傳輸的 API 要求相關詳細資訊。這適用於任何執行階段錯誤，例如 4XX、5XX 和延遲問題。
螢幕截圖 螢幕截圖有助於傳達所觀察到的實際行為或錯誤背景。這對於在 UI 或 Analytics (分析) 中觀察到的任何錯誤或問題非常實用。
HAR (Http ARchive) HAR 是 HTTP 工作階段工具擷取的檔案，用於偵錯任何 UI 相關問題。你可以使用 Chrome、Firefox 或 Internet Explorer 等瀏覽器擷取影像片段。
tcpdumps tcpdump 工具會擷取透過網路傳輸或接收的 TCP/IP 封包。這適用於任何網路相關問題，例如 TLS 握手失敗、502 錯誤和延遲問題等。

Apigee Edge 私有雲的其他構件

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

構件 說明
網路拓撲 說明 Private Cloud 設定的邊緣安裝拓撲圖表，包含每個節點中安裝的所有資料中心、節點和元件。
邊緣元件診斷記錄 與特定 Apigee Edge 元件 (例如訊息處理器、路由器或 Cassandra) 相關的診斷記錄。
安裝設定檔 安裝或升級 Apigee Edge 時使用的無訊息設定檔。

如果發生安裝或遷移問題，這個檔案可用來驗證所有設定是否正確。
記憶體快照資料 記憶體快照資料是 Java 記憶體程序的快照。如果特定 Edge 元件出現高記憶體使用率或 OutOfMemory 錯誤，這個方法就非常實用。
執行緒傾印 執行緒傾印是執行中 Java 程序所有執行緒的快照。

如果在特定 Edge 元件中觀察到高 CPU 或負載，就很適合使用此方法。

客服案件範本和範例案件

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

公有雲的 Apigee Edge

範本

本節提供 Apigee Edge on Public Cloud 的範本。

問題：

<提供問題的詳細說明，或問題或您觀察到的行為。 請提供產品名稱和版本 (如適用)。>

錯誤訊息：

<加入觀察的完整錯誤訊息 (如有)>

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

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

Apigee 設定詳細資料：
機構名稱：
客戶名稱：
API Proxy 名稱：
修訂版本編號：

重現問題的步驟：

<盡可能提供重現問題的步驟>

診斷資訊：

<附加檔案清單>

範例案例

本節提供 Apigee Cloud (Apigee 在 Google Cloud/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 Proxy 名稱：myproxy
修訂版本編號：3

重現問題的步驟：

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

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

診斷資訊：

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

私有雲的 Apigee Edge

範本

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

問題：

<提供問題的詳細說明，或問題或您觀察到的行為。 請提供產品名稱和版本 (如適用)。>

錯誤訊息：

<加入觀察的完整錯誤訊息 (如有)>

問題開始時間 (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