使用 Trace 工具

您正在查看 Apigee Edge 文档。
前往 Apigee X 文档。 信息

什么是 Trace 工具？

Trace 是一种用于对 Apigee Edge 上运行的 API 代理进行问题排查和监控的工具。借助 Trace，您可以通过 API 代理流程检查每个步骤的详细信息。

观看此视频，简要了解 Trace 工具。

如何使用 Trace

Trace 简单易用。您启动跟踪会话，然后向 Edge 平台发出 API 调用，并读取结果。

  1. 访问 API 代理页面（如下所述）。

    Edge

    如需使用 Edge 界面访问“API 代理”页面，请执行以下操作：

    1. 登录 apigee.com/edge。
    2. 在左侧导航栏中，选择开发 > API 代理。

    经典边缘（私有云）

    如需使用经典版 Edge 界面访问“API 代理”页面，请执行以下操作：

    1. 登录 http://ms-ip:9000，其中 ms-ip 是管理服务器节点的 IP 地址或 DNS 名称。
    2. 在顶部导航栏中依次选择 API > API 代理。
  2. 从“API 代理”页面中选择一个 API 代理。
  3. 确保您要跟踪的 API 已部署。
  4. 点击跟踪记录，前往跟踪记录工具视图。
  5. 使用部署到轨迹下拉菜单选择要跟踪的部署环境和代理修订版本。
  6. 点击启动跟踪会话。当跟踪会话处于有效状态时，API 代理会记录处理流水线中每个步骤的详细信息。在 Trace 会话运行期间，系统会从实时流量中捕获消息和上下文数据。

  7. 如果您的代理没有任何实时流量，只需向 API 发送请求即可。您可以使用任何您希望的工具（例如 curl、Postman 或任何熟悉的工具）来发送请求。或者，您也可以直接从 Trace 工具本身发送请求。只需输入网址，然后点击发送即可。注意：您只能通过 Trace 工具发送 GET 请求，而不能发送 POST 请求。

    注意：一个 Trace 会话可以通过所选 API 代理支持每个消息处理器 10 个请求/响应事务。在边缘云中，如果有 2 个消息处理器处理流量，则支持 20 个请求/响应事务。如果您不手动停止，跟踪会话会在 10 分钟后自动停止。
  8. 捕获足够数量的请求后，点击停止 Trace 会话。
  9. 左侧菜单中会显示捕获的请求/响应事务列表。点击任意交易即可查看详细结果。

如何读取跟踪记录

跟踪记录工具包含两个主要部分，即事务映射和阶段详情：

  • 事务映射使用图标来标记 API 代理事务期间发生的每个重要步骤，包括政策执行、条件步骤和转换。将鼠标悬停在任何图标上可查看摘要信息。请求流程步骤位于事务映射的顶部，底部是响应流程步骤。
  • 该工具的阶段详情部分列出了代理内部处理的相关信息，包括设置或读取的变量、请求和响应标头等。点击任何图标可查看该步骤的阶段详情。

下面是一个已标记主代理处理细分的跟踪记录工具映射示例：

跟踪记录工具的事务映射

事务示意图图例

下表介绍了您将在事务示意图中看到的图标的意图。这些图标标记整个代理流程中每个重要的处理步骤。

事务示意图图标

向 API 代理的 ProxyEndpoint 发送请求的客户端应用。
圆圈在代理流程中标记过渡端点。当请求从客户端传入时、当请求到达目标时、当响应来自目标时以及当响应返回客户端时，都会有圆圈标记。

高竖条表示 API 代理流程中流程细分的开始。流程细分包括：ProxyEndpoint 请求、TargetEndpoint 请求、TargetEndpoint 响应和 ProxyEndpoint 响应。一个细分包括 PreFlow、条件流程和 PostFlow。

如需了解详情，请参阅配置流程。

指示已在后台进行 Analytics 操作。

一个评估为 true 的条件流程。如需了解条件流程的简介，请参阅配置流程。

请注意，某些条件是由 Edge 生成的。例如，以下表达式用于让 Edge 检查 ProxyEndpoint 是否出现错误：

((error.state equals PROXY_REQ_FLOW) or (error.state equals PROXY_RESP_FLOW))

计算结果为 false 的条件流程。如需了解条件流程，请参阅配置流程。

请注意，某些条件是由 Edge 生成的。例如，以下表达式是 Edge 用来检查 TargetEndpoint 中是否出现错误的表达式：

(((error.state equals TARGET_REQ_FLOW) or (error.state equals TARGET_RESP_FLOW)) or ((error.state equals REQ_SENT) or (error.state equals RESP_START)))

政策 每种类型的政策都有一个唯一的图标。此政策适用于 AssignMessage 政策。通过这些图标，您可以了解政策执行顺序是否正确，以及政策是否成功。您可以点击政策图标以查看其执行结果，以及预期的执行结果。例如，您可以查看消息是否已正确转换或是否正在缓存。

正确执行的政策由对勾标记明确指明。如果发生错误，图标上会显示一个红色感叹号。

提示：请注意提示或时间线，看看是否有任何政策花费的时间超出预期。
当后端目标是 Node.js 应用时显示。请参阅 Apigee Edge 上的 Node.js 概览。
API 代理调用的后端目标。
时间线表示处理完成所需的时间（以毫秒为单位）。比较运行时间细分有助于隔离耗时最长的政策，进而减慢 API 调用速度。
Epsilon 表示时间范围小于 1 毫秒。

已停用。当政策处于停用状态时，该政策会显示在政策图标上。可以使用公共 API 停用政策。请参阅 API 代理配置参考。
出错了。在“政策步骤”条件评估结果为 false 时，出现在政策图标上（参阅流变量和条件），或在执行 RaiseFault 政策时，出现在 RaiseFault 政策图标上。
已跳过。在政策步骤未执行时，在政策图标上显示为 false。如需了解详情，请参阅流变量和条件。

了解阶段详情

该工具的阶段详情部分向您详细介绍了代理在每个处理步骤的状态。以下是“阶段详情”中提供的一些详细信息。点击跟踪记录工具中的任意图标可查看所选步骤的详细信息，也可以使用下一步/返回按钮从一个步骤移动到另一个步骤。

阶段详情 说明
代理端点 指明要执行哪个 ProxyEndpoint。一个 API 代理可以有多个已命名的代理端点。
变量

列出根据政策读取并分配值的流变量，另请参阅使用流变量管理代理状态。

注意：

  • 等号 (=) 表示分配给变量的值。
  • 不等号 (≠) 表示无法为变量分配值，因为它是在只读或执行政策时出错。
  • 空字段表示已读取变量值。
请求标头 列出 HTTP 请求标头。
请求内容 显示 HTTP 请求正文。
属性 属性表示 API 代理的内部状态。默认情况下，这些列不会显示。
目标端点 指明要执行哪个 TargetEndpoint。
响应标头 列出 HTTP 响应标头。
响应内容 显示 HTTP 响应正文。
PostClientFlow 显示有关 PostClientFlow 的信息，在请求返回到发出请求的客户端应用后执行。只有 MessageLogging 政策可以附加到 PostClientFlow。PostClientFlow 目前主要用于测量响应消息的开始时间戳和结束时间戳之间的时间间隔。

使用过滤器优化消息捕获

您可以通过指定标头和/或查询参数值来过滤 Trace 工具中显示的请求。借助过滤条件，您可以定位可能导致问题的特定调用。 例如，您可能需要重点关注包含特定内容或来自特定合作伙伴或应用的请求。您可以按以下条件进行过滤：

  • HTTP 标头 - 将轨迹限制为仅包含特定标头的调用。这有助于您排查问题。您可以将标头发送给应用开发者，并要求他们将其包含在导致问题的调用中。然后，Apigee Edge 将仅记录具有该特定标头的调用，以便您检查结果。
  • 查询参数 - 系统只会记录具有特定参数值的调用。

有关过滤功能，您需要了解的事项

  • 在过滤条件字段中指定过滤条件参数后，您必须重启 Trace 会话。
  • 过滤参数之间是 AND 关系。所有指定的查询和/或标头名称/值对必须出现在请求中，才能成功匹配。
  • “过滤条件”工具不支持模式匹配。
  • 过滤参数和值区分大小写。

如何创建轨迹过滤条件

  1. 如果 Trace 会话正在运行，请点击停止 Trace 会话将其停止。
  2. 点击 Trace 工具左上角的过滤条件，展开“过滤条件”字段。

    在 Trace 工具中，“过滤条件”边栏标签被圈出。
  3. 在“过滤条件”字段中，指定您要过滤的查询参数和/或标头值。在此示例中，我们指定了两个过滤依据的查询参数。这两个参数都必须出现在请求中，才能成功匹配。

    在 Trace 工具中，在“过滤器”下的“查询参数”下，设置了两个示例名称和值。
  4. 启动跟踪会话。
  5. 调用您的 API。只有包含所有指定标头和/或查询参数的请求才能成功匹配。

在“交易”下方，系统会显示 4 个与两个预设查询参数匹配的结果。

在上述示例中，此 API 调用将显示在轨迹中：

http://docs-test.apigee.net/cats?name=Penny&breed=Calico

但以下内容不会：

http://docs-test.apigee.net/cats?name=Penny

使用 Trace 进行调试

Trace 可以让您查看许多有关 API 代理的内部详细信息。例如：

  • 您可以一目了然地看到哪些政策执行正确或失败。
  • 假设您通过其中一个 Analytics 信息中心注意到您的某个 API 导致性能下降。现在，您可以使用 Trace 来帮助确定瓶颈发生的位置。Trace 提供了完成每个处理步骤所需的时间（以毫秒为单位）。如果您发现一个步骤用时太长，您可以采取纠正措施。
  • 通过查看阶段详情，您可以检查发送到后端的标头、查看由政策设置的变量等。
  • 通过验证基本路径，您可以确保政策将消息路由到正确的服务器。

选择查看选项

选择跟踪会话的视图选项。

选项 说明
显示已停用的政策 显示所有已停用的政策。可以使用公共 API 停用政策。请参阅 API 代理配置参考。
显示已跳过的阶段 显示跳过的所有阶段。由于未按步骤条件评估为 false，导致政策执行时发生的跳过阶段。如需了解详情，请参阅流变量和条件。
显示所有流信息 表示流程细分内的转换。
自动比较选定的阶段 将所选阶段与前一阶段进行比较。将此模式关闭，仅查看所选阶段。
显示变量 显示或隐藏已读取和/或已分配值的变量。
显示属性 属性表示 API 代理的内部状态。（默认情况下隐藏）。

下载跟踪结果

您可以下载原始跟踪记录结果的 XML 文件，以便在文本编辑器中离线查看和搜索。该文件显示了监听会话的完整详细信息，包括所有标头、变量和政策的内容。

如需下载，请点击下载 Trace 会话。

以 curl 形式显示请求

跟踪对目标服务器进行的 API 调用后，您可以将请求视为 curl 命令。这对于调试特别有用，原因如下：

  • API 代理可能会修改请求，因此查看从代理到目标服务器的请求与原始请求有何不同非常有用。curl 命令表示修改后的请求。
  • 对于较大的消息载荷，您可以使用 curl 在一个位置查看 HTTP 标头和消息内容。（目前，字符数上限约为 1,000 个。如需了解有关如何突破此限制的提示，请参阅这篇社区帖子。）

出于安全考虑，curl 功能会屏蔽 HTTP 授权标头。

如需在 Trace 中看到 API 调用通过后的 curl 请求，请在“事务映射”图表中选择“发送到目标服务器的请求”阶段，然后点击“阶段详情”窗格中“发送到目标服务器的请求”列上的显示 curl 按钮。

图片注释指出了“显示 Curl”按钮和“交易映射”图表中的一个圆圈。

Apigee 支持对 Trace 的使用

默认情况下，Apigee Edge 允许 Apigee 支持团队在 API 代理上使用 Trace 工具提供支持。您可以随时停用此选项。但是，停用此选项可能会限制 Apigee 支持团队无法为您提供支持。

如需停用 Apigee 支持，请使用 Trace 工具：

  1. 登录 https://apigee.com/edge。
  2. 在左侧导航栏中，依次选择管理 > 隐私设置和安全性。
  3. 点击启用 Apigee 支持 to Trace 切换开关，以停用 Apigee 支持提供的 Trace 工具。