分析指标、维度和过滤器参考文档

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

此主题是分析指标、维度和过滤器的参考文档。如需详细了解如何使用这些参数,请参阅 API Analytics 概览

本主题会显示出现在界面中的指标和维度的名称,并且您需要在 API 调用中使用它们。

指标

您可以在自定义报告和 Apigee API 调用中检索以下 API 指标。

自定义报告名称 在 Apigee API 中使用的名称 函数 说明
每秒平均事务数 tps

平均事务数,即每秒的 API 代理请求数。请注意,如果相应时间段内事务量相对较少,且界面定制报告中的每秒平均事务数小于两位小数,则每秒平均事务数可能为零。

API 语法:tps

缓存命中 cache_hit 总和

使用 ResponseCache(而不是来自目标服务的响应)的成功 API 请求数。

API 语法:sum(cache_hit)

L1 缓存元素计数 ax_cache_l1_count 平均值、最小值、最大值

在给定时间段内每个事务的 L1(内存)缓存中的元素数量。例如,如果您为一天选择了 max,而当天特定事务缓存中的最高元素数为 12,那么计数将为 12。对于 avg,如果您查询的时间段中有 3 笔事务,并且其缓存计数分别为 5、6 和 7,则平均值为 6。如缓存内部说明中所述,L1 缓存是内存缓存,与 L2 数据库缓存不同。

API 语法:avg(ax_cache_l1_count)

政策错误 policy_error 总和

在指定时间段内的政策错误总数。

政策错误通常是由设计引起的。例如,如果在请求中传递了无效的 API 密钥,VerifyApiKey 政策会抛出错误,如果 API 调用数量超过政策中定义的限制,SpikeArrest 政策会抛出错误。因此,此指标可用于找出 API 中的潜在问题。例如,通过按 developer_app 维度分组的 policy_error 指标,您可能会发现给定应用的 API 密钥或 OAuth 令牌已过期;或者,您可能会发现某个特定 API 代理抛出大量 SpikeArrest 政策错误,从而发现代理的峰值控制限制未考虑节假日流量的增加。

仅当错误导致 API 代理故障时,才会在分析中记录政策错误。例如,如果政策的 continueOnError 特性设置为 true,则API 代理会继续处理请求,即使政策失败也是如此。在这种情况下,分析中不会记录政策错误。

“发生错误的政策名称”(ax_execution_fault_policy_name) 维度有助于按政策名称对政策错误进行分组。

目标故障(例如 404503)不会被视为政策故障。这些故障会被计为 API 代理故障 (is_error)。

API 语法:sum(policy_error)

代理错误 is_error 总和

API 代理在指定时间段内失败的总次数。当政策失败或发生运行时故障(例如目标服务出现 404503)时,会发生代理故障。

代理 (apiproxy) 维度有助于按代理对 API 代理故障进行分组。

API 语法:sum(is_error)

请求处理延迟时间 request_processing_latency 平均值、最小值、最大值

Apigee 处理传入请求所用的时间(平均值、最小值或最大值),以毫秒为单位。计时从请求到达 Apigee 开始,到 Apigee 将请求转发给目标服务时结束。

使用不同的维度,您可以通过 API 代理、开发者应用、地区等检查请求处理延迟时间。

API 语法:max(request_processing_latency)

请求大小 request_size 总值、平均值、最小值、最大值

Apigee 收到的请求载荷的大小(以字节为单位)。

API 语法:avg(request_size)

已执行的响应缓存 ax_cache_executed 总和

ResponseCache 政策在给定时间段内执行的总次数。

由于 ResponseCache 政策附加在 API 代理请求中的两个位置(一次在请求中,一次在响应中),所以其通常在一个 API 调用中执行两次。缓存 GET 和缓存 PUT 各计为一次执行。

不过,如果政策中的 <SkipCacheLookup> 元素评估为 true,则响应缓存执行为 0;如果政策中的 <SkipCachePopulation> 元素评估为 true(在响应中),则响应缓存执行为 0。

Trace 概览中,您可以点击已执行 API 调用中的 ResponseCache 图标,并查看 responsecache.executed 流变量以查看是否存在缓存执行(值为 1)。

API 语法:sum(ax_cache_executed)

响应处理延迟时间 response_processing_latency 平均值、最小值、最大值

Apigee 处理 API 响应所用的时间(平均值、最小值或最大值),以毫秒为单位。计时从 API 代理收到目标服务响应时开始,到 Apigee 将响应转发给原始调用者时结束。

使用不同的维度,您可以通过 API 代理、地区等来检查响应处理延迟时间。

API 语法:min(response_processing_latency)

响应大小 response_size 总值、平均值、最小值、最大值

返回客户端的响应负载的大小(以字节为单位)。

API 语法:max(response_size)

目标错误 target_error 总和

来自目标服务的 5xx 响应总数。这些目标服务错误不是由 Apigee 引起的。

API 语法:sum(target_error)

目标响应时间 target_response_time 总值、平均值、最小值、最大值

目标服务器响应调用的时长(总值、平均值、最小值或最大值),以毫秒为单位。此指标可帮助您了解目标服务器的性能。计时从 Apigee 将请求转发到目标服务开始,到 Apigee 收到响应时结束。

请注意,如果 API 调用从缓存返回响应(例如,使用 ResponseCache 政策),则调用永远不会到达目标服务,并且目标响应时间指标不会被记录。

API 语法:avg(target_response_time)

总响应时间 total_response_time 总值、平均值、最小值、最大值

从 Apigee 收到来自客户端的请求到 Apigee 将响应发送回客户端所用时长(总值、平均值、最小值或最大值),以毫秒为单位。该时间包括网络开销(例如,负载平衡器和路由器完成工作所需的时间)、请求处理延迟时间、响应处理延迟时间以及目标响应时间(如果响应是来自目标服务,而不是缓存)。

使用不同的维度,您可以通过 API 代理、开发者应用、地区等检查处理延迟时间。

API 语法:avg(total_response_time)

流量 message_count 总和

Apigee 在指定时间段内处理的 API 调用总数。

使用维度以对您最有意义的方式对流量计数进行分组。

API 语法:sum(message_count)

Mint 费率 x-apigee_mintng_rate

API 调用收取的费率。

维度

维度可让您查看有意义的分组中的指标。例如,当您查看每个开发者应用或 API 代理的总流量计数时,会看到其变得更加强大。

以下是 Apigee 开箱即用的维度。

自定义报告名称 在 Apigee API 中使用的名称 说明
Apigee 实体
Access Token access_token 应用最终用户的 OAuth 访问令牌。
API 产品 api_product

包含正在调用的 API 代理的 API 产品的名称。为了获取此维度,进行调用的开发者应用必须与包含 API 代理的一个或多个 API 产品相关联,并且正在被调用的代理必须检查 API 密钥或随 API 调用一起发送的 OAuth 令牌。密钥或令牌与 API 产品相关联。如需了解详情,请参阅如何生成完整的分析数据?

如果不符合上述条件,您会看到值 (not set)。另请参阅分析实体值“(not set)”是什么意思?

缓存键 ax_cache_key

包含被访问的 ResponseCache 值的键。如需详细了解如何为响应缓存构建键,请参阅 ResponseCache 政策

调试工具中,当您选择用于读取缓存数据或将数据写入缓存的 ResponseCache 政策时,您可以在 responsecache.cachekey 流变量中看到此值。

缓存名称 ax_cache_name

包含 ResponseCache 政策所用键值对的缓存的名称,前缀为 orgName__envName__。例如,如果组织为 myorgf,环境为 test,缓存名称为 myCache,则 ax_cache_namefoo__test__myCache

调试工具中,当您选择 ResponseCache 政策时,可以在 responsecache.cachename 流变量中看到此值。

缓存源: ax_cache_source

从中检索 ResponseCache 的缓存级别(L1 内存或 L2 数据库)。当从目标(而非缓存)传送响应(响应缓存使用目标响应刷新)或请求中的缓存键无效时,该维度还会显示 CACHE_MISS。缓存键的大小限制为 2 KB。

调试工具中,当您选择 ResponseCache 政策时,可以在 responsecache.cachesource 流变量中看到此值。

如需详细了解缓存级别,请参阅缓存内部说明

客户端 ID client_id

进行 API 调用的开发者应用的使用方密钥(API 密钥),可以作为 API 密钥在请求中传递也可以包含在 OAuth 令牌中。

若要获取此维度,必须配置接收调用的代理,使其可以检查是否存在有效的 API 密钥或 OAuth 令牌。在 Apigee 中注册应用后,开发者应用可获得用于生成 OAuth 令牌的 API 密钥。如需了解详情,请参阅如何生成完整的分析数据?

如果不符合上述条件,您会看到值 (not set)。另请参阅分析实体值“(not set)”是什么意思?

开发者应用 developer_app

进行 API 调用的 Apigee 注册的开发者应用。

要获得此维度,应用必须与包含正被调用的 API 代理的一个或多个 API 产品关联,并且代理必须检查 API 密钥或随 API 调用一起发送的 OAuth 令牌。密钥或令牌用于识别开发者应用。如需了解详情,请参阅如何生成完整的分析数据?

如果不符合上述条件,您会看到值 (not set)。另请参阅分析实体值“(not set)”是什么意思?

开发者电子邮件地址 developer_email

其应用进行 API 调用的Apigee 注册的开发者的电子邮件。

为了获取此维度,开发者必须拥有与一个或多个包含正被调用的 API 代理的 API 产品相关联的应用,并且代理必须检查 API 密钥或随 API 调用一起发送的 OAuth 令牌。密钥或令牌用于识别开发者应用。如需了解详情,请参阅如何生成完整的分析数据?

如果不符合上述条件,您会看到值 (not set)。另请参阅分析实体值“(not set)”是什么意思?

开发者 ID: developer

由 Apigee 生成的唯一开发者 ID,格式为 org_name@@@unique_id

为了获取此维度,开发者必须拥有与一个或多个包含正被调用的 API 代理的 API 产品相关联的应用,并且代理必须检查 API 密钥或随 API 调用一起发送的 OAuth 令牌。密钥或令牌用于标识开发者。有关详情,请参阅如何生成完整的分析数据?

如果不符合上述条件,您会看到值 (not set)。另请参阅分析实体值“(not set)”是什么意思?

环境 environment 在其中部署 API 代理的 Apigee 环境。例如 testprod
流名称错误 ax_execution_fault
  _flow_name

API 代理中引发错误的已命名。例如 PreFlowPostFlow 或您创建的条件流的名称。

请注意,在 Apigee API 中使用的全名为 ax_execution_fault_flow_name,无需换行。

如果没有发生错误,您将会看到值 (not set)

流资源 flow_resource 仅限 Apigee 使用。如果您有兴趣,请参阅如何在 Google Analytics(分析)中使用“资源流”维度
流状态错误 ax_execution_fault
  _flow_state

引发错误的 API 代理流状态的名称,例如 PROXY_REQ_FLOWTARGET_RESP_FLOW

请注意,在 Apigee API 中使用的全名为 ax_execution_fault_flow_state,无需换行。

网关流 ID gateway_flow_id 当 API 调用在 Apigee 中移动时,每次调用都会获得自己的网关流程 ID。示例:rrt329ea-12575-114653952-1。网关 ID 有助于区分高 TPS 指标(在这些场景中,组织、环境和时间戳等维度在其他调用中是完全相同的)。
组织 organization 部署 API 代理的 Apigee 组织。
政策名称错误 ax_execution_fault
  _policy_name

抛出错误并导致 API 调用失败的政策的名称。

请注意,在 Apigee API 中使用的全名为 ax_execution_fault_policy_name,无需换行。

如果政策抛出错误,但将政策根特性 continueOnError 设置为 true,则 API 代理流不会发生任何故障,并且政策故障不会计入此维度。

代理 apiproxy API 代理的机器名称(不是显示名)。
代理基本路径 proxy_basepath

在 API 代理 ProxyEndpoint 上配置的 BasePath。基本路径不包括 API 代理网址的网域和端口部分。例如,如果 API 代理的基本网址为 https://apigeedocs-test.apigee.net/releasenotes/,则基本路径为 /releasenotes

该值也存储在 proxy.basepath 流变量中。

代理路径后缀 proxy_pathsuffix

向 API 代理基本路径添加的资源路径。例如,如果 API 代理的基本网址为 https://apigeedocs-test.apigee.net/hello/,且调用 https://apigeedocs-test.apigee.net/hello/json,则 pathsuffix/json

如果未使用 pathsuffix,则该值为空。

该值也存储在 proxy.pathsuffix 流变量中。

代理修订版本 apiproxy_revision 处理 API 调用的 API 代理的修订版本号。这不一定代表 API 代理的最新修订版本。如果 API 代理有 10 个修订版本,那么目前可能会部署第 8 个修订版本。此外,只要修订版本具有不同的基本路径,API 就可以部署多个修订版本,如部署代理中所述。
已解析的客户端 IP ax_resolved_client_ip

源客户端 IP 地址。ax_resolved_client_ip 维度的值是根据 ax_true_client_ipx_forwarded_for_ip 维度的值计算得出的。

请注意,在使用 Akamai 等路由产品捕获客户端的真实 IP 地址时,客户端 IP 会在 HTTP 标头中传递给 Apigee True-Client-IP,然后使用该对象设置 ax_true_client_ip 维度。

ax_resolved_client_ip 维度的值以如下方式计算:

  1. 如果 ax_true_client_ip 不为 null 且不包含本地 IP 地址,请将 ax_resolved_client_ip 设置为 ax_true_client_ip
  2. 或者,将 ax_resolved_client_ip 设置为 x_forwarded_for_ip 中第一个非本地 IP 地址。
  3. 如果 ax_true_client_ipx_forwarded_for_ip 都仅包含本地 IP,请将 ax_resolved_client_ip 设置为 x_forwarded_for_ip 中的最后一个本地 IP。
  4. 如果 ax_true_client_ipx_forwarded_for_ip 都为 null,请将 ax_resolved_client_ip 设置为 (not set)
  5. 如果 ax_true_client_ip 是本地 IP 并且 x_forwarded_for_ip 为 null,请将 ax_resolved_client_ip 设置为 (not set)
响应状态代码 response_status_code 从 Apigee 转发到客户端的 HTTP 响应状态代码,例如 200404503 等。在 Apigee 中,来自目标的响应状态代码可以被 AssignMessage 政策RaiseFault 政策等政策覆盖,这就是该维度与目标响应代码 (target_response_code)不同的原因。
虚拟主机 virtual_host API 调用所调用的虚拟主机的名称。如需了解详情,请参阅环境和环境组简介
入站/客户端
客户端 IP 地址 client_ip 命中路由器的系统 IP 地址,例如原始客户端 (proxy_client_ip) 或负载平衡器。如果 X-Forwarded-For 标头中有多个 IP,则这是最后列出的 IP。
设备类别 ax_ua_device_category 发起 API 调用的设备的类型,例如 TabletSmartphone
OS 系列 ax_ua_os_family 发起调用的设备的操作系统系列,例如 AndroidiOS
操作系统版本 ax_ua_os_version

发起调用的设备的操作系统版本。

将此维度用作操作系统系列 (ax_ua_os_family) 的第二层展开细目维度以查看操作系统版本会很有帮助。

代理客户端 IP proxy_client_ip

调用客户端的 IP 地址,存储在 proxy.client.ip 流变量中。这通常是入站调用的 X-Forwarded-For 地址,即 Apigee 从上一个外部 TCP 握手收到的 IP 地址。这可以是调用客户端,也可以是负载平衡器。如果 X-Forwarded-For 标头中有多个 IP,则这是最后列出的 IP。

引用的客户端 IP ax_true_client_ip

使用 Akamai 等路由产品捕获客户端的真实 IP 地址时,客户端 IP 会在 HTTP 标头 True-Client-IP 中传递给 Apigee。此维度会从该标头捕获真实的客户端 IP。

为了确定通过 ax_resolved_client_ip 维度访问的原始客户端 IP 地址,Apigee 会使用 ax_true_client_ipx_forwarded_for_ip 维度。

请求路径 request_path

目标服务的资源路径(不包括网域),不包括查询参数。

例如,Apigee 示例目标 http://mocktarget.apigee.net 包含若干资源,其中包括可返回问候语的 /user。无论您的 API 代理如何调用 http://mocktarget.apigee.net/user,request_path 都是 /user

Request URI request_uri

目标服务的资源路径(不包括网域),包括查询参数。

例如,Apigee 示例目标 http://mocktarget.apigee.net 包含若干资源,其中包括 /user?user={name} 资源和查询参数,可用于返回对所提供名称的自定义问候语。无论您的 API 代理如何调用 http://mocktarget.apigee.net/user?user=Dude,request_uri 都是 /user?user=Dude

请求动词 request_verb API 请求中的 HTTP 请求动词,例如 GET、POST、PUT、DELETE。
用户代理 useragent

用于发起 API 调用的用户代理或软件代理的名称。示例:

  • 通过 Chrome 拨打电话的 Pixel XL:Mozilla/5.0 (Linux; Android 7.1.2; Pixel XL Build/NHG47N) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/59.0.3071.92 Mobile Safari/537.36
  • 通过 Chrome 拨打电话的 iPad:Mozilla/5.0 (iPad; CPU OS 10_2 like Mac OS X) AppleWebKit/602.1.50 (KHTML, like Gecko) CriOS/54.0.2840.91 Mobile/14C92 Safari/602.1
  • 终端中的 cURL:curl/7.51.0
用户代理系列 ax_ua_agent_family 用户代理的系列,例如 Chrome Mobilecurl
用户代理类型 ax_ua_agent_type 用户代理类型,例如 BrowserMobile BrowserLibrary 等。
用户代理版本 ax_ua_agent_version

用户代理的版本。

将此维度用作用户代理系列 (ax_ua_agent_family) 的第二层展开细目维度以获取代理系列版本会很有帮助。

去程/目标
目标 target 处理请求的目标端点。例如 default
目标基本路径 target_basepath

在代理的 <TargetEndpoint> 中定义的目标服务的资源路径(不包括网域),不包括查询参数。

例如,假设 API 代理调用以下目标:


<TargetEndpoint name="default">
...
<HTTPTargetConnection>
  <URL>http://mocktarget.apigee.net/user?user=Dude</URL>
</HTTPTargetConnection>

在此示例中,target_basepath 为 /user

如果目标为:


<TargetEndpoint name="default">
...
<HTTPTargetConnection>
  <URL>http://mocktarget.apigee.net</URL>
</HTTPTargetConnection>

target_basepath 将为 null。

调试工具中,当您在流程图末尾选择 AX 图标时,target.basepath 流变量会映射到 target_basepath 维度。

目标主机 target_host 目标服务的主机。例如,如果 API 代理调用 http://mocktarget.apigee.net/help,则 target_host 为 mocktarget.apigee.net
目标 IP 地址 target_ip 将响应返回到 API 代理的目标服务的 IP 地址。
目标响应代码 target_response_code

目标服务向 API 代理返回的 HTTP 响应状态代码,例如 200404503 等。

null 表示请求从未到达目标服务。当 ResponseCache 政策处理响应或请求处理中出现故障时,便会出现此值。

这与响应状态代码 (response_status_code) 维度不同。

目标网址 target_url

API 代理的 TargetEndpoint 中定义的目标服务的完整网址。


<TargetEndpoint name="default">
...
<HTTPTargetConnection>
  <URL>http://mocktarget.apigee.net/user?user=Dude</URL>
</HTTPTargetConnection>

在此示例中,target_url 为 http://mocktarget.apigee.net/user?user=Dude

请注意,您还可以在 API 代理处理期间使用 target.url 流变量替换此网址。

代理链中,调用代理中的 target_url 为 null。

X-Forwarded-For IP x_forwarded_for_ip

X-Forwarded-For 标头中的 IP 地址列表。

为了确定通过 ax_resolved_client_ip 维度访问的原始客户端 IP 地址,Apigee 会使用 ax_true_client_ipx_forwarded_for_ip 维度。

X-Forwarded-For Proto x_forwarded_proto

客户端用于连接到路由器的协议。有效值包括 httphttps

时间
一周中的第几天 ax_day_of_week 发起 API 调用的周几的三个字母缩写。例如,周一、周二、周三。
ax_month_of_year 进行 API 调用的月份。例如,03 表示三月。
当天时间 ax_hour_of_day

根据 24 小时制,进行 API 调用的 2 位数小时。例如,在晚上 10 点到 11 点之间进行 API 调用,则 ax_hour_of_day 为 22。

时间值采用 UTC 格式。

时区 ax_geo_timezone 发起 API 调用的时区的常见名称,例如 America/New_York and Europe/Dublin.
一个月中某周 ax_week_of_month 一个月中的第几周。例如,如果在一个月的第 3 周进行 API 调用,ax_week_of_month 为 3。
位置
城市 ax_geo_city 发起 API 调用的城市。
ax_geo_continent 发起 API 调用的大洲的双字母代码。例如,NA 表示北美。
国家/地区 ax_geo_country 发起 API 调用的国家/地区的双字母代码。例如,US 表示美国。
地理区域 ax_geo_region 地理区域的用连字符连接的代码,例如 STATE-COUNTRY。例如,WA-US 表示美国华盛顿。
区域 ax_dn_region 部署 API 代理的 Apigee 数据中心的名称,例如 us-east-1
获利
x apigee mintng currency x-apigee.mintng_currency 为费率方案定义的货币。

过滤

借助过滤条件,您可将结果限制为具有特定特征的指标。以下是一些过滤条件示例。定义过滤条件时,请使用指标和维度 API 样式的名称。

返回名称簿或音乐的 API 代理的指标:

filter=(apiproxy in 'books','music')

返回名称以 m 开头的 API 代理的指标:

filter=(apiproxy like 'm%')

返回名称不以 m 开头的 API 代理的指标:

filter=(apiproxy not like 'm%')

返回响应状态代码介于 400599 之间的 API 调用的指标:

filter=(response_status_code ge 400 and response_status_code le 599)

返回响应状态代码为 200 且目标响应代码为 404 的 API 调用的指标:

filter=(response_status_code eq 200 and target_response_code eq 404)

返回响应状态代码为 500 的 API 调用的指标:

filter=(response_status_code eq 500)

返回不会引发错误的 API 调用的指标:

filter=(is_error eq 0)

以下是可用于构建报告过滤条件的运算符。

运算符 说明
in 添加到列表中
notin 从列表中移除
eq 等于,==
ne 不等于,!=
gt 大于,>
lt 小于,<
ge 大于或等于,>=
le 小于或等于,<=
like 如果字符串格式与提供的格式匹配,则返回 true。
not like 如果字符串格式与提供的格式匹配,则返回 false。
similar to 根据其格式是否匹配给定的字符串,返回 true 或 false。它类似于 like,不同之处在于它使用 SQL 标准正则表达式定义来解释格式。
not similar to 根据其格式是否匹配给定的字符串,返回 false 或 true。它类似于 not like,不同之处在于它使用 SQL 标准正则表达式定义来解释格式。
and 允许您使用 AND 逻辑来包含多个过滤条件表达式。该过滤条件包括满足所有条件的数据。
or 允许您使用 OR 逻辑来计算不同的可能过滤条件表达式。过滤条件包括满足至少一个条件的数据。