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

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

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

在客服案件中提供詳細的必要資訊，有助於 Google Cloud Apigee 支援團隊快速有效率地回覆。如果客服案件缺少重要細節，我們需要詢問相關資訊，這可能導致雙方多次往返溝通。這會耗費更多時間，導致問題解決時間延遲。 這份最佳做法指南可讓您瞭解我們在解決技術支援案件時所需要的資訊，以便我們更快速地解決問題。

描述問題

問題應包含詳細資訊，說明實際發生的情況與預期情況的差異，以及發生時間和方式。理想的 Apigee 客服案件應包含下列各項 Apigee 產品的重要資訊：

重要資訊 說明 Apigee Edge Public Cloud Apigee Edge for Private Cloud
產品 觀察到問題的特定 Apigee 產品，包括適用的版本資訊。
  • 版本
問題詳細資料 清楚詳細的問題說明，包括問題概要和完整錯誤訊息 (如有)。
  • 錯誤訊息
  • 追蹤工具輸出內容
  • 重現問題的步驟
  • 完成 API 要求/指令
  • 錯誤訊息
  • 追蹤工具輸出內容
  • 重現問題的步驟
  • 完成 API 要求/指令
  • 元件診斷記錄
時間 問題發生時的確切時間戳記，以及持續時間。
  • 問題發生的日期、時間和時區
  • 問題持續時間
  • 問題發生的日期、時間和時區
  • 問題持續時間
設定 詳細說明問題發生位置。
  • 機構名稱
  • 環境名稱
  • API Proxy 名稱
  • 修訂版本
  • 網路拓撲
  • 違反規則的 Edge 元件

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

產品

Apigee 產品有 Apigee Edge Public Cloud 和 Apigee Edge Private Cloud，因此我們需要特定資訊，瞭解是哪個產品發生問題。

下表提供一些範例，顯示「應做事項」欄中的完整資訊，以及「不應做事項」欄中的不完整資訊：

正確做法 錯誤做法
在 Public Cloud 機構中，API Proxy OAuth2 的部署作業失敗。

API Proxy 部署失敗

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

Edge Private Cloud 4.50.00 版安裝失敗，並顯示下列錯誤訊息：

無法在私有雲設定中安裝。

(缺少版本資訊)

問題詳情

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

下表提供一些範例，說明「應做事項」欄位中的完整資訊，以及「不應做事項」欄位中的不完整資訊：

正確做法 錯誤做法

新的 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-06 17:30 PDT 和 2020-11-06 17:35 PDT 之間，觀察到大量 503s...

昨天下午 5 點 30 分，有大量 503s 聚集 5 分鐘。

(我們必須使用隱含日期，且不清楚觀察到這個問題時的時區。)

從 2020 年 11 月 9 日下午 3 點 30 分 (印度標準時間)到 2020 年 11 月 9 日下午 6 點 10 分 (印度標準時間)，下列 API Proxy 的延遲時間過長：...

上週部分 API Proxy 發生高延遲問題。

(不清楚上週哪一天發生這個問題，也不清楚持續時間。)

設定

請提供問題所在位置的詳細資訊。請根據使用的產品，提供下列資訊：

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

下表提供一些範例，說明「應做事項」欄位中的完整資訊，以及「不應做事項」欄位中的不完整資訊：

正確做法 錯誤做法

401自 2020 年 11 月 6 日 09:30 (CST) 起，Edge Public Cloud 的錯誤次數增加。

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 和延遲問題。
螢幕截圖 螢幕截圖有助於傳達實際觀察到的行為或錯誤背景資訊。這有助於解決觀察到的任何錯誤或問題，例如使用者介面或數據分析中的錯誤或問題。
HAR (Http ARchive) HAR 是由 HTTP 工作階段工具擷取的檔案，用於偵錯任何與 UI 相關的問題。 您可以使用 Chrome、Firefox 或 Internet Explorer 等瀏覽器擷取這類資訊。
tcpdumps tcpdump 工具會擷取透過網路傳輸或接收的 TCP/IP 封包。這項功能有助於解決任何網路相關問題，例如傳輸層安全標準 (TLS) 握手失敗、502 錯誤和延遲問題等。

Apigee Edge Private Cloud 的其他構件

如果是 Apigee Edge for Private Cloud，我們可能需要一些額外構件，以利加快問題診斷速度。

構件 說明
網路拓撲 邊緣裝置安裝拓撲圖，說明您的私有雲設定，包括所有資料中心、節點，以及安裝在每個節點中的元件。
Edge 元件診斷記錄 與特定 Apigee Edge 元件相關的診斷記錄，例如 Message Processor、Router 或 Cassandra。
安裝設定檔 安裝或升級 Apigee Edge 時使用的無聲設定檔。

如果遇到安裝或遷移問題，這個檔案有助於驗證所有設定是否正確。
記憶體快照資料 記憶體快照資料是 Java 記憶體程序的快照，如果特定 Edge 元件的記憶體用量偏高或發生 OutOfMemory 錯誤，這項功能就相當實用。
Thread dumps 執行緒傾印檔是執行中 Java 程序所有執行緒的快照。

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

案件範本和範例案件

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

公有雲上的 Apigee Edge

範本

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

問題：

<Provide detailed description of the problem or the behaviour being observed at your end. Include the product name and version where applicable.>

錯誤訊息：

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

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

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

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

重現問題的步驟：

<Provide steps to reproduce the issue where possible>

診斷資訊：

<List of files attached>

範例

本節提供 Apigee Cloud (Google Cloud 上的 Apigee/Apigee Edge Public Cloud) 的範例案例。

問題：

我們在公有雲機構中看到大量 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 for Private Cloud

範本

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

問題：

<Provide detailed description of the problem or the behaviour being observed at your end. Include the product name and version where applicable.>

錯誤訊息：

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

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

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

Edge Private Cloud 設定詳細資料：

<Attach the network topology describing the setup of your Private Cloud including data centers and nodes>

重現問題的步驟：

<Provide steps to reproduce the issue where possible>

診斷資訊

<List of files attached>

範例

本節提供 Apigee Edge Private Cloud 的範例案例。

問題：

在 Node #10 上安裝 Apigee 管理伺服器時，我們遇到下列錯誤，這是 Edge Private Cloud 4.19.06 的一部分，安裝在 Linux RHEL 7.6 上。

錯誤訊息：

<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