You're viewing Apigee Edge documentation.
View Apigee X documentation.
This topic is a reference for analytics metrics, dimensions, and filters. For more context on using these, see API Analytics overview.
This topic shows the names for metrics and dimensions as they appear in the UI and as you need to use them in API calls.
- You'll see the UI names when you create Custom reports.
- Use the API-specific names when getting metrics, creating a report definition, or updating a report definition.
Following are the API metrics you can retrieve in custom reports and management API calls.
|Custom reports name||Name to use in the management API||Functions||Description|
|Average Transactions per Second||tps||None||
The average number of transactions, meaning API proxy requests, per second. Note that if you have a relatively low number of transactions over the time period, the average number of transactions per second could appear to be zero in UI custom reports if the number is smaller than two decimal places.
The number of successful API requests that use the Response Cache instead of the response from the target service.
|L1 Cache Elements Count||ax_cache_l1_count||avg, min, max||
Returns the number of elements in L1 (in-memory) cache per transaction over a given
time period. For example, if you choose
The total number of policy errors over the specified time period.
Policy errors usually occur by design. For example, the Verify API Key policy throws an error when an invalid API key is passed in the request, and a Spike Arrest policy throws an error if the number of API calls exceeds the limit defined in the policy. So this metric is useful for finding potential trouble spots in your APIs. For example, policy_error metrics, grouped by the developer_app dimension, might help you discover that an API key or OAuth token has expired for a given app; or you might find that a specific API proxy is throwing a lot of Spike Arrest errors, leading you to discover that the proxy's spike arrest limit doesn't account for an increase in holiday traffic.
A policy error is logged in analytics only if the error results in API proxy failure.
For example, if a policy's
The Policy Name on Error (ax_execution_fault_policy_name) dimension is useful for grouping policy errors by policy name.
A target failure (such as a 404 or 503) does not count as a policy failure. Those count as API proxy failures (is_error).
The total number of times API proxies failed over the specified time period. Proxy failure can occur when a policy fails or when there's a runtime failure, such as a 404 or 503 from the target service.
The Proxy (apiproxy) dimension is useful for grouping API proxy failures by proxy.
|Request Processing Latency||request_processing_latency||avg, min, max||
The amount of time (average, minimum, or maximum), in milliseconds, that it takes Edge to process incoming requests. The time starts when the request reaches Edge and ends when Edge forwards the request to the target service.
Using different dimensions, you can examine request processing latencies by API proxy, developer app, region, and so on.
|Request Size||request_size||sum, avg, min, max||
The size of the request payload received by Edge, in bytes.
|Response Cache Executed||ax_cache_executed||sum||
The total number of times a Response Cache policy was executed over the given time period.
Since the Response Cache policy is attached in two places in an API proxy (once in the request and once in the response), it usually executes twice in an API call. A cache 'get' and a cache 'put' each count as one execution.
However, response cache execution is 0 if the
|Response Processing Latency||response_processing_latency||avg, min, max||
The amount of time (average, minimum, or maximum), in milliseconds, that it takes Edge to process API responses. The time starts when the API proxy receives the target service response and ends when Apigee forwards the response to the original caller.
Using different dimensions, you can examine response processing latencies by API proxy, region, and so on.
|Response Size||response_size||sum, avg, min, max||
The size of the response payload returned to the client, in bytes.
The total number of 5xx responses from the target service. These are target service errors not caused by Apigee.
|Target Response Time||target_response_time||sum, avg, min, max||
The amount of time (sum, average, minimum, or maximum), in milliseconds, for the target server to respond to a call. This metric tells you how target servers are performing. The time starts when Edge forwards a request to the target service and ends when Edge receives the response.
Note that if an API call returns a response from cache (using the Response Cache policy, for example), the call will never reach the target service, and no target response time metrics are logged.
|Total Response Time||total_response_time||sum, avg, min, max||
The amount of time (sum, average, minimum, or maximum), in milliseconds, from when Edge receives a request from a client to when Edge sends the response back to the client. The time includes network overhead (such as the time it takes load balancers and routers to do their work), request processing latency, response processing latency, and target response time (if the response is served from the target service instead of cache).
Using different dimensions, you can examine processing latencies by API proxy, developer app, region, and so on.
The total number of API calls processed by Edge in the specified time period.
Use dimensions to group traffic counts in ways that are most meaningful to you.
Dimensions let you view metrics in meaningful groupings. For example, seeing total traffic counts becomes much more powerful when you view them for each developer app or API proxy.
Following are the dimensions Apigee provides out of the box. In addition, you can create your own dimensions, as described in Analyze API message content using custom analytics.
|Custom Reports name||Name to use in the management API||Description|
|Access Token||access_token||The app end user's OAuth access token.|
The name of the API product containing the API proxies being called. In order to get this dimension, developer apps making the calls must be associated with one or more API products that contain the API proxies, and the proxies being called must check for an API key or OAuth token sent with the API call. The key or token is associated with an API product. For more information, see First things first: How to generate complete analytics data.
The key containing the Response Cache value that was accessed. For more information on how the key is constructed for response cache, see Response Cache policy.
The name of the cache containing the keys/values used by the Response Cache policy, prefixed with orgName__envName__. For example, if the org is "foo," the environment is "test," and the cache name is "myCache," the ax_cache_name is foo__test__myCache.
The cache level ("L1" in-memory or "L2" database) from which the Response Cache was retrieved. This dimension also shows "CACHE_MISS" when the response was delivered from the target instead of cache (and response cache was refreshed with the target response); or when a cache key in the request is invalid. Cache keys are limited to 2 KB in size.
For more information on cache levels, see Cache internals.
The consumer key (API key) of the developer app making the API calls, whether passed in the request as API keys or included in OAuth tokens.
In order to get this dimension, proxies receiving calls must be configured to check for a valid API key or OAuth token. Developer apps get API keys, which can be used to generate OAuth tokens, when the apps are registered in Edge. For more information, see First things first: How to generate complete analytics data.
The Edge-registered developer app making API calls.
In order to get this dimension, apps must be associated with one or more API products that contain the API proxies being called, and the proxies must check for an API key or OAuth token sent with the API call. The key or token identifies the developer app. For more information, see First things first: How to generate complete analytics data.
The email of the Edge-registered developers whose app made the API calls.
In order to get this dimension, developers must have apps associated with one or more API products that contain the API proxies being called, and the proxies must check for an API key or OAuth token sent with the API call. The key or token identifies the developer app. For more information, see First things first: How to generate complete analytics data.
The unique Edge-generated developer ID in the form of org_name@@@unique_id.
In order to get this dimension, developers must have apps associated with one or more API products containing the API proxies being called, and the proxies must check for an API key or OAuth token sent with the API calls. The key or token identifies the developer. For more information, see First things first: How to generate complete analytics data.
|Environment||environment||The Edge environment in which the API proxies are deployed. For example, "test" or "prod".|
|Fault Code on Error||ax_edge_execution_fault_code||
The fault code of the error. For example:
|Flow Name on Error||ax_execution_fault
The named flow in an API proxy that raised an error. For example, "PreFlow," "PostFlow," or the name of a conditional flow you created.
Note that the full name to use in the management API is ax_execution_fault_flow_name, without a line break.
Where no errors occurred, you'll see the value "(not set)".
|Flow Resource||flow_resource||Apigee use only. See this Community post if you're curious.|
|Flow State on Error||ax_execution_fault
The name of the API proxy flow states that raised errors, such as "PROXY_REQ_FLOW" or "TARGET_RESP_FLOW."
Note that the full name to use in the management API is ax_execution_fault_flow_state, without a line break.
|Gateway Flow ID||gateway_flow_id||As API calls move through Edge, each call gets its own gateway flow ID. Example: rrt329ea-12575-114653952-1. Gateway Flow ID is useful for distinguishing metrics in high-TPS situations where other dimensions such as organization, environment, and timestamp are identical across calls.|
|Organization||organization||The Edge organization in which the API proxies are deployed.|
|Policy Name on Error||ax_execution_fault
The name of the policy that threw an error and caused the API call to fail.
Note that the full name to use in the management API is ax_execution_fault_policy_name, without a line break.
If a policy throws an error but the policy root attribute
|Proxy||apiproxy||The machine name (not the Display Name) of an API proxy.|
|Proxy Base Path||proxy_basepath||
The BasePath configured on the API proxy ProxyEndpoint. Base path does not include the domain and port portion of the API proxy URL. For example, if an API proxy's base URL is https://apigeedocs-test.apigee.net/releasenotes/, the base path is /releasenotes.
The value is also stored in the
|Proxy Path Suffix||proxy_pathsuffix||
The resource path added to the API proxy base path. For example, if an API proxy's
base URL is
If no pathsuffix is used, the value is empty.
The value is also stored in the
|Proxy Revision||apiproxy_revision||The revision number of the API proxy that handled API calls. This doesn't necessarily mean the latest revision of an API proxy. If an API proxy has 10 revisions, the 8th revision may currently be deployed. Also, an API may have multiple revisions deployed as long as the revisions have different Base Paths, as described in Deploying proxies in the UI.|
|Resolved Client IP||ax_resolved_client_ip||
Contains the originating client IP address. The value of the
Note that when using routing products such as Akamai to capture the true IP addresses of clients,
the client IP is passed to Edge in the HTTP header
The value of the
|Response Status Code||response_status_code||The HTTP response status code forwarded from Apigee to the client, such as 200, 404, 503, and so on. In Edge, the response status code from the target can be overwritten with policies such as Assign Message and Raise Fault, which is why this dimension can differ from Target Response Code (target_response_code).|
|Virtual Host||virtual_host||The name of the virtual host the
API call was made to. For example, organizations have two
virtual hosts by default:
|Client IP Address||client_ip||IP address of the system that hits the router, such as the original client
(proxy_client_ip) or a load balancer. When there are multiple IPs in the
|Device Category||ax_ua_device_category||The type of device from which the API call was made, such as "Tablet" or "Smartphone".|
|OS Family||ax_ua_os_family||The operating system family of the device making the call, such as "Android" or "iOS".|
The operating system version of the device making the call.
It's useful to use this as a second "drill-down" dimension with OS Family (ax_ua_os_family) to see the versions of the operating systems.
|Proxy Client IP||proxy_client_ip||
The IP address of the calling client, stored in the
|Referred Client IP||ax_true_client_ip||
When using routing products such as Akamai to capture the true IP addresses of clients,
the client IPs are passed to Edge in the HTTP header
To determine the original client IP Address, accessed through the
The resource path (not including the domain) to the target service, excluding query parameters.
For example, the Apigee sample target
The resource path (not including the domain) to the target service, including query parameters.
For example, the Apigee sample target
|Request Verb||request_verb||The HTTP request verb in the API requests, such as GET, POST, PUT, DELETE.|
The name of the user agent, or software agent, used to make the API call. Examples:
|User Agent Family||ax_ua_agent_family||The family of the useragent, such as "Chrome Mobile" or "cURL".|
|User Agent Type||ax_ua_agent_type||The useragent type, such as "Browser," "Mobile Browser," "Library," and so on.|
|User Agent Version||ax_ua_agent_version||
The version of the useragent.
It's useful to use this as a second "drill-down" dimension with User Agent Family (ax_ua_agent_family) to get the version of the agent family.
|Target Base Path||target_basepath||
The resource path (not including the domain) to the target service, excluding query
parameters, that is defined in the proxy's
For example, say an API proxy calls the following target:
<TargetEndpoint name="default"> ... <HTTPTargetConnection> <URL>http://mocktarget.apigee.net/user?user=Dude</URL> </HTTPTargetConnection>
In this example, the target_basepath is
If the target were this:
<TargetEndpoint name="default"> ... <HTTPTargetConnection> <URL>http://mocktarget.apigee.net</URL> </HTTPTargetConnection>
the target_basepath would be null.
|Target Host||target_host||The host of the target service. For example, if an API proxy calls
|Target IP Address||target_ip||The IP address of the target service returning the response to the API proxy.|
|Target Response Code||target_response_code||
The HTTP response status code returned by the target service to the API proxy, such as 200, 404, 503, and so on.
A value of "null" means the request never reached the target service. This occurs when the response is served by the Response Cache policy or when there's a failure in request processing.
This is different than the Response Status Code (response_status_code) dimension.
The full URL of the target service defined in an API proxy's TargetEndpoint.
In this example, the target_url is
Note that the URL can also be overridden during API proxy processing with the
|X Forwarded For||x_forwarded_for_ip||
The list of IP addresses in the
|Day of week||ax_day_of_week||The three-letter day of the week abbreviation on which the API calls were made. For example, Mon, Tue, Wed.|
|Month||ax_month_of_year||The numeric month in which the API calls were made. For example, "03" for March.|
|Time of Day||ax_hour_of_day||
Based on a 24-hour clock, the 2-digit hour in which API calls were made. For example, API calls made in the hour between 10pm and 11pm, the ax_hour_of_day would be 22.
The time value is in UTC.
|Time Zone||ax_geo_timezone||The common names of the time zones the API calls were made from, such as America/New_York and Europe/Dublin.|
|Week of Month||ax_week_of_month||The numeric week of the month. For example, for API calls made in the 3rd week of a month, the ax_week_of_month is 3.|
|City||ax_geo_city||The city from which the API calls were made.|
|Continent||ax_geo_continent||The two-letter code of the continent from which the API calls were made. For example, NA for North America.|
|Country||ax_geo_country||The two-letter code of the country from which the API calls were made. For example, US for United States.|
|Geographical Region||ax_geo_region||The hyphenated code for the geographic region, such as STATE-COUNTRY. For example, WA-US for Washington-United States.|
|Region||ax_dn_region||The name of the Apigee data center where API proxies are deployed, such as us-east-1.|
|Mint Transaction Ignore Message||x_apigee_mint_tx_ignoreMessage||Flag that specifies whether to ignore messages related to monetization. Set to
|Mint Transaction Status||x_apigee_mint_tx_status||Status of a monetization request, such as success, failure, invalid, or none.|
Filters let you limit results to metrics with specific characteristics. Following are some sample filters. Use metric and dimension API-style names when defining filters.
Returns metrics for API proxies with the name books or music:
filter=(apiproxy in 'books','music')
Returns metrics for API proxies with names that start with "m":
filter=(apiproxy like 'm%')
Returns metrics for API proxies with names that do not start with "m":
filter=(apiproxy not like 'm%')
Returns metrics for API calls with response status codes between 400 and 599:
filter=(response_status_code ge 400 and response_status_code le 599)
Returns metrics for API calls with response status code of 200 and a target response code of 404:
filter=(response_status_code eq 200 and target_response_code eq 404)
Returns metrics for API calls with a response status code of 500:
filter=(response_status_code eq 500)
Returns metrics for API calls that didn't result in errors:
filter=(is_error eq 0)
Following are operators you can use to build report filters.
||Include in list|
||Exclude from list|
||Not equal to,
||Greater than or equal to,
||Less than or equal to,
||Returns true if the string pattern matches the supplied pattern.|
||Returns false if the string pattern matches the supplied pattern.|
||Returns true or false depending on whether its pattern matches the given string. It is
||Returns false or true depending on whether its pattern matches the given string. It is
||Lets you use 'and' logic to include more than one filter expression. The filter includes data that meets all the conditions.|
||Lets you use 'or' logic to evaluate different possible filter expressions. The filter includes data that meets at least one of the conditions.|