使用 Metrics API

您正在查看的是 Apigee Edge 文档。
转到 Apigee X 文档
信息

Apigee Edge 记录了各种 API 中流动的运营数据和业务数据。根据此类数据得出的指标对于运营监控和业务监控非常有用。例如,您可以使用 Edge API Analytics 确定哪些 API 表现良好或不佳,哪些开发者带来的流量价值最高,以及哪些应用给您的后端服务造成了最多的问题。

为了帮助轻松访问这些指标数据,Edge 公开了 RESTful API。如果您需要自动执行某些 Analytics 函数(例如使用自动化客户端或脚本定期检索指标),则可以使用 Metrics API。您还可以使用 API 以自定义微件的形式构建自己的可视化图表,并将其嵌入门户或自定义应用中。

如需了解如何在 API 边缘管理界面中使用 Analytics(分析),请参阅 API Analytics 概览

Metrics API 简介

Edge 提供两种指标 API:

  • 获取指标会返回一段时间内(例如一小时、一天或一周)组织和环境的指标。

    例如,您可以获取上一周的下列数据:

    • 政策错误的数量
    • 平均响应时间
    • 总流量
  • 获取按维度整理的指标会返回一段时间内组织和环境的指标(维度分组)。

    例如,针对您上周使用维度按 API 产品、API 代理和开发者电子邮件地址分组的指标,你可以获取:

    • 每个 API 产品的政策错误数量
    • 每个 API 代理的平均响应时间
    • 每个开发者电子邮件的总流量

    获取按维度整理的指标 API 支持获取指标 API 不支持的其他功能,其中包括:

Metrics API 配额简介

Edge 对这些调用实施以下配额。配额基于处理调用的后端系统:

  • Postgres:每分钟 40 次调用
  • BigQuery:每分钟 12 次调用

通过检查响应对象确定处理调用的后端系统。每个响应对象均包含一个 metaData 属性,其中列出了在 Source 属性中处理调用的服务。例如,对于 Postgres:

{
  ...
  "metaData": {
    "errors": [],
    "notices": [
      "Source:Postgres",
      "Table used: xxxxxx.yyyyy",
      "query served by:111-222-333"
    ]
  }
}

对于 BigQuery,Source 属性为:

"Source:Big Query"

如果超过调用配额,API 将返回 HTTP 429 响应。

使用 Management API 获取指标

这两种 API 的主要区别在于:获取指标返回整个组织和环境的原始指标,而获取按维度整理的指标能让您按不同的实体类型(例如 API 产品、开发者和应用)对指标进行分组。

获取指标 API 的请求网址如下:

https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/stats

对于获取按维度整理的指标 API,您需要在网址中的 /stats 后方添加一项其他资源,该资源用于指定所需维度

https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/stats/dimension

例如,如需获取按 API 代理分组的指标,您可以使用以下网址调用 Management API:

https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/stats/apiproxy

指定要返回的指标

对于获取指标获取按维度组织的指标 API,您都可以使用 select 查询参数指定要检索的 metrics,以及可选的聚合函数,格式如下:

?select=metric

或者:

?select=aggFunction(metric)

其中:

  • metric 指定要返回的数据。例如,API 请求数、缓存命中数或政策错误数。如需了解列明了与 select 查询参数搭配使用的指标名称表,请参阅metrics
  • aggFunction 指定针对指标运行的可选聚合函数。例如,您可以将以下聚合函数与处理延迟时间指标结合使用:

    • avg:返回平均处理延迟时间。
    • min:返回最小处理延迟时间。
    • max:返回最大处理延迟时间。
    • sum:返回所有处理延迟时间的总和。

    并非所有指标都支持所有聚合函数。metrics中的文档包含一个列明了指标名称和指标所支持函数(sumavgminmax)的表。

例如,如需返回平均每秒事务数(即 API 代理请求数),请使用以下代码:

?select=tps

请注意,此示例不需要聚合函数。下一个示例使用聚合函数返回缓存命中的总和:

?select=sum(cache_hit)

您可以为单个 API 调用返回多个指标。如需获取政策错误数总和指标和平均请求大小指标,请使用以逗号分隔的指标列表设置 select 查询参数:

?select=sum(policy_error),avg(request_size)

指定时间段

Metrics API 可以返回指定时间段的数据。使用 timeRange 查询参数指定时间段,格式如下:

?timeRange=MM/DD/YYYY%20HH:MM~MM/DD/YYYY%20HH:MM

请注意 HH:MM 之前的 %20timeRange 参数要求在 HH:MM 之前使用采用网址编码的空格字符或 + 字符,例如 MM/DD/YYYY+HH:MM~MM/DD/YYYY+HH:MM

例如:

?timeRange=03/01/2018%2000:00~03/30/2018%2023:59

请勿使用 24:00 作为时间,因为该时间会绕至 00:00。请改用 23:59。

使用分隔符

如需在 API 调用中分隔多个维度,请使用英文逗号 (,) 作为分隔符。例如,在 API 调用中

curl https://api.enterprise.apigee.com/v1/o/myorg/e/prod/stats/apis,apps?select=sum(message_count)&timeRange=9/24/2018%2000:00~10/25/2018%2000:00&timeUnit=day

维度 apisapps, 分隔。

API 调用示例

本部分提供了使用获取指标 API 和获取按维度整理的指标 API 的示例。如需查看其他示例,请参阅 Metrics API 示例

返回一个月内调用 API 的总次数

要查看一个月内调用组织和环境中所有 API 的总次数,请使用获取指标 API:

curl -v "https://api.enterprise.apigee.com/v1/o/{org}/e/{env}/stats/?select=sum(message_count)&timeRange=03/01/2018%2000:00~03/31/2018%2023:59" \
-u email:password

示例响应:

{
  "environments": [
    {
      "metrics": [
        {
          "name": "sum(message_count)",
          "values": [
            "7.44944088E8"
          ]
        }
      ],
      "name": "prod"
    }
  ],
...
}

返回每个 API 代理在两天内收到的消息总数

在此示例中,您返回了所有 API 代理在两天内收到的请求数量的指标。select 查询参数在维度 apiproxy 中为指标 message_count 定义了聚合函数 sum。报告会返回世界协调时间 (UTC) 2018 年 6 月 20 日到 2018 年 6 月 21 日期间所有 API 针对所接收流量的请求消息吞吐量:

curl  https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/apiproxy?"select=sum(message_count)&timeRange=06/20/2018%2000:00~06/21/2018%2023:59" \
-u email:password

示例响应:

{
  "environments" : [ {
    "dimensions" : [ {
      "metrics" : [ {
        "name" : "sum(message_count)",
        "values" : [ {
          "timestamp" : 1498003200000,
          "value" : "1100.0"
        } ]
      } ],
      "name" : "target-reroute"
    } ],
    "name" : "test"
  } ]...
}

此响应表明,在 2018 年 6 月 20 日至 2018 年 6 月 21 日期间,在测试环境中运行且名为“target-reroute”的 API 代理接收了 1100 条消息。

要获取其他维度的指标,请指定不同的维度作为 URI 参数。例如,您可以指定 developer_app 维度来检索开发者应用的指标。以下 API 调用会返回指定时间段内来自任何应用的总吞吐量(接收到的消息):

curl  https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/developer_app?"select=sum(message_count)&timeRange=06/20/2018%2000:00~06/21/2018%2023:59&timeUnit=day" \
-u email:password

示例响应:

{
  "environments": [
    {
      "dimensions": [
        {
          "metrics": [
            {
              "name": "sum(message_count)",
              "values": [
                {
                  "timestamp": 1498003200000,
                  "value": "886.0"
                }
              ]
            }
          ],
          "name": "Test-App"
        },
        {
          "metrics": [
            {
              "name": "sum(message_count)",
              "values": [
                {
                  "timestamp": 1498003200000,
                  "value": "6645.0"
                }
              ]
            }
          ],
          "name": "johndoe_app"
        },
        {
          "metrics": [
            {
              "name": "sum(message_count)",
              "values": [
                {
                  "timestamp": 1498003200000,
                  "value": "1109.0"
                }
              ]
            }
          ],
          "name": "marys_app"
        }
  ]...
}

按相对排名对结果进行排序

很多时候,您获取指标时只希望获得一部分数据集的结果。通常情况下,您需要获取“前 10 名”结果,例如“前 10 个最慢的 API”“前 10 个最活跃的应用”。为此,您可以使用 topk 查询参数作为请求的一部分。

例如,您可能想知道谁是顶级开发者(通过吞吐量来衡量),或者性能最差(即“最慢”)的目标 API 是什么(通过延迟时间衡量)。

topk(表示“top k”实体)用于报告与给定指标的最高值关联的实体。这允许您为说明特定条件的实体列表过滤涉指标。例如,要查找上周哪个目标网址出错最多,请将 topk 参数附加到该请求中,并将其值设置为 1

curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/target_url?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)&topk=1" \
  -u email:password
{
  "environments": [
    {
      "dimensions": [
        {
          "metrics": [
            {
              "name": "sum(is_error)",
              "values": [
                {
                  "timestamp": 1494201600000,
                  "value": "12077.0"
                }
              ]
            }
          ],
          "name": "http://api.company.com"
        }
      ]...
}

此请求的结果是一组指标,这组指标显示出错最多的目标网址为 http://api.company.com

您还可以使用 topk 参数对经历最高吞吐量的 API 进行排序。以下示例检索了排名最靠前的 API 的指标,该指标由上周的最高吞吐量定义:

curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/apiproxy?"select=sum(message_count)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=day&sortby=sum(message_count)&sort=DESC&topk=1" \
-u email:password

示例响应

{
  "environments": [
    {
      "dimensions": [
        {
          "metrics": [
            {
              "name": "sum(message_count)",
              "values": [
                {
                  "timestamp": 1494720000000,
                  "value": "5750.0"
                },
                {
                  "timestamp": 1494633600000,
                  "value": "5752.0"
                },
                {
                  "timestamp": 1494547200000,
                  "value": "5747.0"
                },
                {
                  "timestamp": 1494460800000,
                  "value": "5751.0"
                },
                {
                  "timestamp": 1494374400000,
                  "value": "5753.0"
                },
                {
                  "timestamp": 1494288000000,
                  "value": "5751.0"
                },
                {
                  "timestamp": 1494201600000,
                  "value": "5752.0"
                }
              ]
            }
          ],
          "name": "testCache"
        }
      ],
      "name": "test"
    }
  ]...
}

过滤结果

如需查看更细化的数据,您可以过滤结果以限制返回的数据。使用过滤条件时,必须使用维度作为过滤条件属性。

例如,假设您需要从按请求的 HTTP 动词过滤的后端服务中检索错误计数。您的目标是了解每个后端服务有多少 POST 和 PUT 请求生成了错误。为此,您可以使用维度 target_url 和过滤条件 request_verb

curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/target_url?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&filter=(request_verb%20in%20'POST','PUT')" \
-u email:password

示例响应:

{
  "environments" : [
    {
      "dimensions" : [
        {
          "metrics" : [
            {
              "name" : "sum(is_error)",
              "values" : [
                {
                  "timestamp" : 1519516800000,
                  "value" : "1.0"
                }
              ]
          }
        ],
        "name" : "testCache"
        }
      ],
      "name" : "test"
    }
  ]...
}

分页结果

在生产环境中,对 Edge Analytics API 的某些请求会返回非常大的数据集。为了便于在基于界面的应用上下文中显示大型数据集,API 本身便支持分页功能。

如需对结果进行分页,请使用 offsetlimit 查询参数以及 sortby 排序参数,以确保项排序的一致性。

例如,以下请求可能会返回大型数据集,因为它检索了上周所有 API 在产品环境中出现的所有错误的指标。

curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/apiproxy?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)" \
-u email:password

如果基于界面的应用可以在每个页面上合理地显示 50 个结果,那么您可以将限制设置为 50。由于 0 计为第一项,因此以下调用会按降序返回 0-49 项(默认值为 sort=DESC)。

curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/apiproxy?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)&limit=50&offset=0" \
-u email:password

对于结果的第二“页”,请使用偏移量查询参数,如下所示。请注意,限制和偏移量是相同的。因为 0 计为第一项。限值为 50 且偏移量为 0 时,会返回 0-49 项。偏移量为 50 时,会返回 50-99 项。

curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/apiproxy?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)&limit=50&offset=50" \
-u email:password