View metrics data using the API

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

Use the APIs described below to get API Monitoring metrics. Metrics are the data values aggregated by API Monitoring from the raw data contained in the API Monitoring logs.

The following sections describe how to manage metrics using the API.

See Metrics API for more on the metrics API.

For information about the cURL options used in these examples, see Use cURL.

Metrics APIs

The base URL that you use to make a GET request to the metrics API is:

https://apimonitoring.enterprise.apigee.com/metrics/resource

Where resource corresponds to a specific metric. The following table lists the metrics resources:

Resource Description
/traffic Get traffic metrics. Specify filters such as proxy name, interval, time window, target, status code, and many others.
/latency Get latency metrics for requests

to Edge and to backend targets. Specify filters such as proxy name, interval, target, status code, and many others.

/targets Get all target domains for a specific organization and environment.
/alerthistory Get alert history metrics for a specific organization and time window.
/alertinstance/instanceid Get alert history metrics for the specific alert instance ID.
/alertsummary Get the total count of alerts for an organization and time window.
/faultcodenames Get all faultcode names.
/faultcodes Get fault codes.
/faultcodecategories Get fault code categories.
/faultcodesubcategories Get fault code subcategories.
/faultcodedetails Get all fault code with details.

Get fault information

The /fault* resources all return metadata about the possible faults on Edge. For example, to see the list of all possible fault categories:

curl -X GET \
"https://apimonitoring.enterprise.apigee.com/metrics/faultcodecategories" \
-H "accept: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN"

Set $ACCESS_TOKEN to your OAuth 2.0 access token, as described in Obtain an OAuth 2.0 access token.

The response appears as:

{
  "faultCodeCategories":[
    "","API Protocol","Developer/App","Extension Policy","Gateway",
    "Mediation Policy","Mint","Security Policy","Sense","Traffic Mgmt Policy"
  ]
}

You can then determine the list of fault codes for the API Protocol category:

curl -X GET \
"https://apimonitoring.enterprise.apigee.com/metrics/faultcodes?faultCodeCategory=API Protocol" \
-H "accept: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN"

For additional options, see the Metrics API.

Capture metrics for traffic and latency

The Metrics API have filters that you can apply to the API to specify custom time ranges, proxies, regions, environments, and other filters to the calculated metrics. For example, to view the transactions per second (tps) metric every 10 minutes for the previous hour for all environments:

curl -X GET \
"https://apimonitoring.enterprise.apigee.com/metrics/traffic?from=-1h&to=now&select=tps&interval=10m&groupBy=env&org=myorg" \
-H "accept: application/json"  \
-H "Authorization: Bearer $ACCESS_TOKEN"

Set $ACCESS_TOKEN to your OAuth 2.0 access token, as described in Obtain an OAuth 2.0 access token.

This call returns results in the form:

{
  "results":[
    {
      "series":[
        {
          "name":"proxy",
        "tags":
             {
                "env":"prod",
                "intervalSeconds":"60",
                "org":"myorg",
                "region":"myregion"
              },
            "columns":["time","tps"],
            "values":[
              ["2018-08-15T13:10:00Z",5.03],
              ["2018-08-15T13:20:00Z",5.01],
              ["2018-08-15T13:30:00Z",5.81],
              ["2018-08-15T13:40:00Z",5.95],
              …
            ]
          },
       …
       }
    }]
}

Notice how the columns property specifies the format of values. The values property contains the tps calculated every 10 minutes, for the previous 10 minute interval.

The interval query parameter defines the frequency that the metric is saved to the results and the sampling window for value in the results. In the example above, the metric is calculated over the previous 10 minutes, and written to the results every 10 minutes.

Use the from and to query parameters to specify an ISO formatted time range. The maximum duration specified by from and to is 24 hours.

The date format can be either:

  • yyyy-mm-ddThh:mm:ssZ
  • yyyy-mm-ddThh:mm:ss+00:00

For example:

curl -X GET \
"https://apimonitoring.enterprise.apigee.com/metrics/traffic?from=2018-08-13T14%3A04%3A00Z&to=2018-08-13T14%3A10%3A00Z&select=tps&interval=1m&groupBy=env&org=myorg&proxy=PublicAPI" \
-H "accept: application/json"  \
-H "Authorization: Bearer $ACCESS_TOKEN"

Or use the from and to query parameters to specify a relative time range, for example for the last hour:

curl -X GET \
"https://apimonitoring.enterprise.apigee.com/metrics/traffic?from=-1h&to=now&select=tps&interval=1m&groupBy=env&org=myorg&proxy=PublicAPI" \
-H "accept: application/json"  \
-H "Authorization: Bearer $ACCESS_TOKEN"

Another option is to use the proxy query parameter to display transactions per second (tps) for a single proxy:

curl -X GET \
"https://apimonitoring.enterprise.apigee.com/metrics/traffic?from=-1h&to=now&select=tps&interval=1m&groupBy=env&org=myorg&proxy=PublicAPI" \
-H "accept: application/json"  \
-H "Authorization: Bearer $ACCESS_TOKEN"

For latency metrics, specify many of the same criteria as for traffic metrics. However, for the /latency resource:

  • You must specify the percentile query parameter as 50, 90, 95, or 99. For example, if you specify 90, the API returns the total response latency value in the 90th percentile.
  • The windowsize is fixed at one minute.

For example, to view the metrics for the total latency in the 90th percentile for a 1 minute window:

curl -X GET \
"https://apimonitoring.enterprise.apigee.com/metrics/latency?percentile=90&select=totalLatency&from=-1h&to=now&interval=5m&windowsize=1m&groupBy=org,env,region&org=myorg" \
-H "accept: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN"

For additional options, see Metrics API.

Capture metrics for alerts

The Metrics API return metrics for all alerts, for a specific alert, or an alert summary. For example, to get the alert history for an organization for the last hour:

curl -X GET \
"https://apimonitoring.enterprise.apigee.com/metrics/alerthistory?org=myorg&from=-1h&to=now" \
-H "accept: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN"

Set $ACCESS_TOKEN to your OAuth 2.0 access token, as described in Obtain an OAuth 2.0 access token.

This API call returns a response in the form:

[
  {
"id":"983c4c7a-c301-4697-95cc-9a7c53e05fac",
"organization":"myorg",
"environment":"prod",
"name":"Public Api 5xx error rate",
"type":"Alert",
"source":"https://www.apigee.net/sonar",
"raw_payload":"
{
    \"reportUUID\":\"\",
    \"reportEnabled\":false,
    \"organization\":\"myorg\",
    \"name\":\"Public Api 5xx error rate\",
    \"self\":\"/alerts/95cc9ef4-345f-11e8-9fd3-12774584e062\",
    \"description\":\"\",
    \"conditions\":[
    {
        \"comparator\":\"\u003e\",
        \"metric\":\"rate\",
        \"durationSeconds\":3600,
        \"name\":\"\",
        \"description\":\"\",
        \"threshold\":0.01,
        \"dimensions\":
        {
            \"proxy\":\"myAPI\",
            \"org\":\"myorg\",
            \"env\":\"prod\",
            \"region\":\"myRegion\",
            \"statusCode\":\"5xx\"
            }
        }],
        \"uuid\":\"95cc9ef4-345f-11e8-9fd3-12774584e062\",
    \"playbook\":\"This is a test alert.\"
    }",
"time":"2018-08-14T12:45:28Z"
 },
 …
]

You can then use the id in the returned array to get information about a specific alert:

curl -X GET \
"https://apimonitoring.enterprise.apigee.com/metrics/alertinstance/983c4c7a-c301-4697-95cc-9a7c53e05fac" \
-H "accept: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN"

For additional options, see the Metrics API.