使用 Trace 工具

您正在查看的是 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 (Private Cloud)

    如需使用传统版 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。当跟踪会话处于活动状态时,API 代理会记录处理流水线中每个步骤的详细信息。在跟踪会话运行时,系统会从实时流量中捕获消息和上下文数据。

  7. 如果没有任何实时流量流经您的代理,则只需向 API 发送请求即可。您可以使用任何想要发送请求的工具(例如 curl、Postman 或任何熟悉的工具)。或者,您也可以直接从跟踪工具本身发送请求。只需输入网址,然后点击发送即可。注意:您只能从跟踪工具发送 GET 请求,而不能从 POST 请求发送。

    注意:对于每个消息处理器,一个跟踪会话可以通过所选的 API 代理支持 10 个请求/响应事务。在 Edge Cloud 中,有 2 个消息处理器处理流量,支持 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 将只记录使用该特定标头的调用,以便您查看结果。
  • 查询参数 - 只有具有特定参数值的调用才会被记录。

关于过滤器功能的须知事项

  • 在过滤器字段中指定过滤器参数后,您必须重启跟踪会话。
  • 过滤器参数以 AND 运算符相连。请求中必须包含所有指定的查询和/或标头名称/值对,才能成功匹配。
  • 过滤器工具不支持模式匹配。
  • 过滤条件参数和值区分大小写。

如何创建跟踪过滤器

  1. 如果跟踪会话正在运行,请点击 Stop Trace 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 授权标头。

如需在 API 调用传入 Trace 后查看 curl 请求,请在事务映射图中选择“Request sent to target server”(发送到目标服务器的请求)阶段,然后点击“Phase Details”(阶段详细信息)窗格中“Request sent to target server”(已发送到目标服务器)列中的 Show curl(显示 curl)按钮。

图片注解指出了 Show Curl 按钮和 Transaction Map 图中的一个圆圈。

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.