使用 Trace 工具

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

什么是跟踪工具？

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

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

如何使用 Trace

Trace 简单易用。您启动一个跟踪会话，然后对 Edge 平台进行 API 调用， 并读取结果。

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

    Edge

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

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

    传统 Edge（私有云）

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

    1. 登录 http://ms-ip:9000，其中 ms-ip 是 管理服务器节点的 IP 地址或 DNS 名称。
    2. 选择 API >API 代理。
  2. 从“API 代理”页面选择 API 代理。
  3. 确保已部署您要跟踪的 API。
  4. 点击 Trace 以转到“跟踪”工具视图。
  5. 使用 Deployment to Trace 下拉菜单选择 您要跟踪的部署环境和代理修订版本。
  6. 点击 Start Trace Session。当 Trace 会话处于活动状态时，API 代理 记录处理流水线中每个步骤的详细信息。在 Trace 会话运行时， 从实时流量中获取消息和情境数据。

  7. 如果没有实时流量流经代理，则只需发送请求即可 该 API。你可以使用任何要发送请求的工具，例如 curl、Postman 或 任何熟悉的工具或者，您也可以直接从跟踪工具本身发送请求。只需输入 该网址，然后点击发送。注意：您最多只能从 跟踪工具，但不是 POST 请求。

    注意：一个 Trace 会话支持每个会话 10 个请求/响应事务 消息处理器。在具有 2 个消息处理器的 Edge 云中 处理流量，支持 20 个请求/响应事务。自动跟踪会话 如果没有手动停止，则会在 10 分钟后停止运行
  8. 捕获到足够数量的请求后，点击 Stop Trace Session。
  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 目前主要用于测量响应消息的开始时间戳和结束时间戳之间的时间间隔。

使用过滤器优化邮件捕获

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

  • HTTP 标头 - 将跟踪记录限制为仅包含包含 标头。这是帮助您排查问题的好方法。您可以将标头发送到 并要求他们在导致出现问题的通话中纳入验证。然后选择 Apigee Edge 只会记录带有该特定标头的调用，以便您检查结果。
  • 查询参数 - 仅限具有特定参数值的调用 将被录制。

关于过滤功能的须知事项

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

如何创建跟踪记录 过滤条件

  1. 如果跟踪会话正在运行，请点击停止跟踪以停止跟踪 Session。
  2. 点击跟踪工具左上角的过滤器以展开 过滤条件字段。

    在“跟踪”工具中，过滤器边栏标签带有圆圈。
  3. 在“过滤条件”字段中，指定要过滤的查询参数和/或标头值 。在此示例中，我们指定了两个要过滤的查询参数。两个参数都必须是 。

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

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

在上面的示例中，此 API 调用将显示在 Trace 中：

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，导致政策执行时发生的跳过阶段。如需了解详情，请参阅流变量和条件。
显示所有 FlowInfo 表示流程细分内的转换。
自动比较选定的阶段 将所选阶段与前一阶段进行比较。将此模式关闭，仅查看所选阶段。
显示变量 显示或隐藏已读取和/或已分配值的变量。
显示属性 属性表示 API 代理的内部状态。（默认情况下隐藏）。

下载跟踪记录结果

您可以下载包含原始轨迹结果的 XML 文件，以便在文本文本中离线查看和搜索 编辑器。该文件显示了收听会话的完整详情，包括 所有标头、变量和政策

如需下载，请点击 Download Trace Session。

将请求显示为 curl

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

  • API 代理可能会修改请求，因此，了解从代理发出的请求是如何 目标服务器与原始请求不同。curl 命令表示 请求。
  • 对于较大的消息负载，您可以通过 curl 命令查看 HTTP 标头和消息 一站式管理各种内容（目前的字符数限制约为 1,000 个字符。有关 请参阅 此社区帖子）。

出于安全考虑，curl 功能会遮盖 HTTP Authorization 标头。

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

图片注释会指出“显示卷曲”按钮和 交易映射图。

Apigee 支持对 Trace 的使用

By default, Apigee Edge allows Apigee Support to use the Trace tool on your API proxies to provide support. You may disable this option at any time. However, disabling this option may limit Apigee Support's ability to provide you with support.

To disable Apigee Support from using the Trace tool:

  1. Sign in to https://apigee.com/edge.
  2. Select Admin > Privacy & Security in the left navigation bar.
  3. Click the Enable Apigee Support to Trace toggle to disable use of the Trace tool by Apigee Support.