Google Cloud Apigee 支持案例最佳做法

<ph type="x-smartling-placeholder"></ph> 您正在查看 Apigee Edge 文档。
转到 Apigee X 文档。 信息

您正在查看 Apigee X 文档。
查看 Apigee Edge 文档。

在支持案例中提供详细信息和必填信息，以便 Google Cloud Apigee 支持团队能够快速而高效地回复您。如果您的支持案例缺少关键细节，我们会要求您提供更多信息，而这可能会反复多次出现。这将花费更长时间，并且可能会导致问题解决的延迟。 本最佳做法指南帮助您了解我们需要哪些信息来解决技术支持案例，以便更快地加以解决。

描述问题

问题应包含有关问题发生原因与预期结果、发生时间和方式的详细信息。一个出色的 Apigee 支持案例应包含每个 Apigee 产品的以下关键信息：

密钥信息 说明 适用于公有云的 Apigee Edge 适用于私有云的 Apigee Edge
产品 发现问题的具体 Apigee 产品，包括适用的版本信息。
  • 版本
问题详情 清晰而详细的问题描述可勾勒出问题框架，包括完整的错误消息（如果有）
  • 错误消息
  • Trace 工具输出
  • 重现问题的步骤
  • 完整的 API 请求/命令
  • 错误消息
  • Trace 工具输出
  • 重现问题的步骤
  • 完整的 API 请求/命令
  • 组件诊断日志
时间 问题出现的具体时间戳及其持续时长。
  • 问题出现的日期、时间和时区
  • 问题持续的时长
  • 问题出现的日期、时间和时区
  • 问题持续的时长
设置 被发现问题的详细信息。
  • 组织名称
  • 环境名称
  • API 代理名称
  • 修订版本
  • 网络拓扑
  • Failing Edge 组件

以下各个部分详细介绍了这些概念。

产品

有不同的 Apigee 产品，如公有云上的 Apigee Edge， 私有云上的 Apigee Edge，因此我们需要特定的 问题相关信息。

下表给出了一些示例，这些示例展示了 DOs 列中的完整信息，以及 DON'Ts 列中不完整的信息：

DOs DON'Ts
API 代理 OAuth2 在Public Cloud 组织部署失败

API 代理部署失败

（我们需要知道您在哪个 Apigee 产品发现的该问题。）
在 Edge Private Cloud 4.50.00 版本安装失败，并出现以下错误 …

在私有云设置中安装失败。

（缺少版本信息）

问题详情

提供有关所遇问题的确切信息，包括错误消息（如果有）以及观察到的预期行为和实际行为。

下表给出了一些示例，这些示例展示了 DOs 列中的完整信息，以及 DON'Ts 列中不完整的信息：

DOs DON'Ts

新的 edgemicro 代理 edgemicro_auth 失败，并显示以下错误：

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

今天新创建的 edgemicro 代理无法运行

（代理名称未知。不清楚代理会返回错误还是意外响应。）

在向 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 格式来表示日期和时间戳，以提供问题出现时的确切时间信息。

下表给出了一些示例，这些示例展示了 DOs 列出现该问题的准确时间和持续时长，以及 DON'Ts 列中关于问题出现时间的一些模糊或不确定消息：

DOs DON'Ts
昨天在 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 代理上出现高延迟现象 …

某些 API 代理上周出现了高延迟现象。

（目前尚不清楚在上周观察到该问题的具体日期和问题持续时长。）

设置

我们需要知道该问题出现的确切位置。根据您使用的产品，我们需要以下信息：

  • 如果您使用的是 Apigee Cloud，则可能拥有多个组织，因此我们需要知道问题出现的具体组织和其他详细信息：
    • 组织和环境名称
    • API 代理名称和修订版本号（用于 API 请求失败）
  • 如果您使用的是Private Cloud，则可能使用的是诸多受支持的安装拓扑之一。因此，我们需要知道您正在使用的拓扑，包括数据中心数量和节点等详细信息。

下表给出了一些示例，这些示例展示了 DOs 列中的完整信息，以及 DON'Ts 列中不完整的信息：

DOs DON'Ts

自 2020-11-06 09:30 CST 以来，Edge Public Cloud上的 401 错误有所增加。

Edge 设置详情：

失效 API 的详细信息如下所示：
  组织名称：myorg
  环境名称：test
  API 代理名称：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：

制品 说明
Trace 工具输出 Trace 工具输出包含有关流经 Apigee 产品的 API 请求的详细信息。这适用于所有运行时错误，例如 4XX、5XX 和延迟问题。
屏幕截图 屏幕截图有助于传达观察到的实际行为或错误的上下文。这对观察到的所有错误或问题（例如在界面或 Analytics 中）都非常有用。
HAR (Http ARchive) HAR 是一个由 HTTP 会话工具捕获的文件，用于调试与界面相关的问题。该文件可通过 Chrome、Firefox 或 Internet Explorer 等浏览器捕获。
tcpdumps tcpdump 工具会捕获通过网络传输或接收的 TCP/IP 数据包。这对任何网络相关的问题（例如 TLS 握手失败、502 错误和延迟问题等）都非常有用。

适用于私有云的 Apigee Edge 的额外工件

对于适用于私有云的 Apigee Edge，我们还可能需要一些额外的工件，以便更快地诊断问题。

工件 说明
网络拓扑 介绍 Private Cloud 设置的 Edge 安装拓扑图，包括每个节点中安装的所有数据中心、节点和组件。
Edge 组件诊断日志 与特定 Apigee Edge 组件相关的诊断日志，例如消息处理器、路由器或 Cassandra。
安装配置文件 安装或升级 Apigee Edge 时使用的静默配置文件。

在遇到安装或迁移问题时，此文件可用于验证所有设置是否正确。
堆转储 堆转储是 Java 内存进程的快照。这对处理某些 Edge 组件上的内存利用率高或 OutOfMemory 错误非常有用。
线程转储 线程转储是正在运行的 Java 进程的所有线程的快照。

这对处理某些 Edge 组件上出现的高 CPU 或高负载现象会非常有用。

案例模板和示例案例

本部分根据本文档中介绍的最佳做法为不同产品提供了案例模板和示例案例：

公有云上的 Apigee Edge

模板

本部分提供了一个示例模板 公有云上的 Apigee Edge。

问题：

<请详细描述您发现的问题或行为。请添加适用的产品名称和版本。>

错误消息：

<包括发现的完整错误消息（如果有）>

问题开始时间(ISO 8601 格式)：

问题结束时间 （ISO 8601 格式）：

Apigee 设置详情：
组织名称：
环境名称：
API 代理名称：
修订版本号：

重现步骤：

<尽可能重现问题的步骤>

诊断信息：

<已附加文件列表>

示例案例

本部分提供了 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 代理名称：myproxy
修订版本号：3

重现步骤：

运行以下 curl 命令以重现该问题：

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

诊断信息：

Trace 工具输出 (trace-503.xml)

适用于私有云的 Apigee Edge

模板

本部分提供了一个示例模板 适用于私有云的 Apigee Edge。

问题：

<请详细描述您发现的问题或行为。请添加适用的产品名称和版本。>

错误消息：

<包括发现的完整错误消息（如果有）>

问题开始时间(ISO 8601 格式)：

问题结束时间 （ISO 8601 格式）：

Edge Private Cloud 设置详情：

<附加介绍 Private Cloud 设置的网络拓扑，包括数据中心和节点>

重现步骤：

<尽可能重现问题的步骤>

诊断信息

<已附加文件列表>

示例案例

本部分提供了一个适用于私有云的 Apigee Edge 的示例案例。

问题：

我们在 Linux RHEL 7.6 上的 Edge Private Cloud 4.19.06 的 Node #10 部分安装 Apigee Management Server时，会出现以下错误。

错误消息：

<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