NextGen API metrics definitions

The Next Generation API provides access to metrics data loaded directly from the database with intuitive metric masks (short forms for API usage).

While over 300 metrics are available, the table below lists the most commonly used metrics. It matches metric masks with metric names as displayed in charting tiles when creating custom dashboards. In addition to summary- and page-level data, more granular object-level metrics are also available. The table below also lists prefixes/suffixes for metrics relating to object groups, e.g., image files or third-party image files.

In addition to the default average value, you can also query the standard deviation, median, and percentile values for several metrics using the trend and table calls—see Calculations below for details.

Metrics

Legend:

Level Product
S - Script T - TxP
P - Page M - MWP
O - Object A - ApP
Mask Name Description Level Products
avail Availability Average availability of selected measurements (summary- and page-level only) S, P T, M, A
uxtme User Experience User experience time reported by the browser—total time elapsed from when the browser starts navigating to a page to when it finishes loading page contents S, P T, M
nwtme Total Network Time Network Time or Total Time—total time of all network traffic for a transaction measured by a Keynote agent; response time This is the total time needed to download a web page from the network's point of view. It starts from the beginning of the base file's DNS lookup and ends when the last packet of the last page element has been delivered by WinInet to the browser for processing. It does not include any times during which no page element activity is taking place. S, P, O T, M, A
chtme Estimated Cache Time Estimated network time if objects that could be cached were cached S, P T, A
dnstm DNS DNS duration—DNS lookup time taken P, O T, M, A
tcptm Initial Connection Initial connection duration—time to open up a TCP/IP connection S, P, O T, M, A
ssltm SSL Time Time required for TLS/SSL negotiation P, O T, M, A
nelem Elements Count Number of elements S, P T, M, A
fbtme First Byte Time taken from initiating the request to first byte of response P, O T, M, A
cdtme Content Download Time Time to download all page elements P, O T, M, A
dmlod DOM Loading Start Time from the start of page navigation to the start of processing content (loading DOM) P T, M
dmint DOM interactive Time from the start of the page navigation to DOM Interactive (current document status: interactive) P T, M
ldest Load Event Start Time from the start of page navigation to the start of the unload event P T, M
unlst DOM Unload Start Time from the start of page navigation to the start of the unload event P T, M
unlen DOM Unload End Time from the start of the unload event to the end of the unload event P T, M
ldeen Load Event End Time from start to end of the load event P T, M
dmcst DOM Content Loading Start Time from the start of page navigation to to when domContentLoaded event is fired P T, M
dmcen DOM Content Loading End DOM content loading delta P T, M
dmcpt DOM Complete Time to DOM complete—time from the start of page navigation to completion of content processing P T, M
fulsc Full Screen Special custom component that indicates the time for a page to appear by showing when a specified page element begins to download S, P T, M
3_bttfp_c 3rd Party Count Before TTFP Number of third-party elements downloaded before the browser first paints something Also used as a suffix to indicate third-party count before time to first paint of an object type, e.g., css_3_bttfp_c is the third-party CSS object count before TTFP. S, P T, M, A
3_o_c 3rd Party Object Count Total number of third-party objects Also used as a suffix to indicate the third-party count of an object type, e.g., txt_3_o_c is the count of third-party text objects. S, P T, M, A
3_o_e 3rd Party Object Errors Total number of errors reported for third-party objects Also used as a suffix to indicate the third-party errors of an object type, e.g., img_3_o_e is the count of third-party image errors. S, P T, M, A
3_o_s 3rd Party Object Size Total size of third-party objects Also used as a suffix to indicate total size of third-party objects of a certain type, e.g., img_3_o_s is the total size of third-party images. S, P T, M, A
3_o_t 3rd Party Time Total time taken to download all third-party objects (the gaps between object downloads count towards total UX time) Also used as a suffix to indicate total time to download third-party objects of a certain type, e.g., img_3_o_t is the total download time of third-party images. S, P T, M, A
cltme Client Time Total time spent by agent fetching the resource, excluding time spent for interaction with the network (depends on agent’s processor speed) P T, M, A
count Total Number of Hits Number of hits or data points for synthetic for scripted measurements S, P, O T, M, A
dm_o_c Domain Count Total number of domains S, P T, M, A
fpntm Time to First Paint Time from the start of page navigation to when page elements are first displayed P T, M
nbyte Downloaded Bytes Number of bytes downloaded through the network (could be compressed) S, P T, M, A
ncnterr Content Error Content error count in a page or script S, P T, M, A
rdr_o_t Redirect Time Redirect time S, P T, M, A
reqtm Request Delta Time taken for the browser to send the request P, O T, M, A
css_ Prefix for metrics relating to all CSS performance
css_1 Prefix for metrics relating to primary domain CSS performance
css_3 Prefix for metrics relating to third-party CSS performance
dm_ Prefix for domain-level metrics
dm_1 Prefix for metrics relating to primary domains
dm_3 Prefix for metrics relating to third-party domains
elem_ Prefix for metrics relating to elements
elem_1 Prefix for metrics relating to primary domain elements
elem_3 Prefix for metrics relating to third-party elements
img_ Prefix for metrics relating to images
img_1 Prefix for metrics relating to primary domain images
img_3 Prefix for metrics relating to third-party images
js_ Prefix for metrics relating to all JavaScript files
js_1 Prefix for metrics relating to JavaScript files for primary domain content
js_3 Prefix for metrics relating to JavaScript files for third-party content
rdr_ Prefix for metrics relating to redirection
req_ Prefix for metrics relating to requests
req_3 Prefix for metrics relating to third-party requests
txt_ Prefix for metrics relating to text elements
txt_3 Prefix for metrics relating to third-party text elements

Calculations

In trend and table calls, the NextGen API supports calculating the average, standard deviation, mediansummation, and various percentile values for most metrics. These calculations are automatically performed regardless of the bucket size in trend calls (bucketing is not required for table calls). Metrics that do not support these calculations are business metrics such as availability (avail), and those that are calculated as sums such as number or errors (nerr) or number of network errors (enet).

You can request specific calculations just as you would any other metric by using the following syntax with the metrics parameter:

  • avg(<metric>)

  • sum(<metric>)

    This is the sum of all values for a given metric over the specified time range.

  • stdev(<metric>)

    Standard deviation is calculated based on a sample, not the entire population. In Excel, this is equivalent to the stdev.s (not stdev.p) calculation.

  • median(<metric>)

    The median is either the exact middle value when there is an odd number of data points, or the lower of the two middle values when there is an even number of data points.

  • percentile(<metric>,<percentile_number>), e.g., percentile(uxtme,75)

    Linear interpolation is used to construct percentile values. For example, if you request the 57th percentile value from a set of 10 data points, the value is calculated using the two nearest values.

Note

Because of the differences in calculation noted above, the median and 50th percentile values are not necessarily the same.

You can request any number of calculations, one at a time, in the metrics parameter, e.g., &metrics=avg(<metric1>),percentile(<metric1>,<percentile_number>),avg(<metric2>),percentile(<metric2>,<percentile_number>)

Note

You cannot include both percentile and median calculations in the same API call; if you do, you will run into a BADLIST error.

The string &metrics=count,nwtme,uxtme,stdev(uxtme) in an API call requests the number of data points, network time, user experience time, and standard deviation for user experience time.

When a calculation is not specified, the average or the summary value, depending on the metric, is returned by default. For example, queries for network or user experience time return average values; queries for number of errors or successes return the sum.

One value per calculation is included in each data set returned. The number of data sets depends on whether you use the trend or table call, your bucket size in trend, and the grouping you use.

The table call below (no bucketing required) asks for count, user experience time, network time, standard deviation of user experience time, and the 75th percentile of user experience time for three measurements over a one hour period. Data is grouped by measurement (monitor ID and monitor name) and sorted in descending order of user experience time.

https://ultraapi.keynote.com/v3.2/synthetic/table?login=<user_login>&pass=<md5_hash_password>&tstart=1490126400000&tend=1490130000000&metrics=count,uxtme,nwtme,stdev(uxtme),percentile(uxtme,75)&group=monid,mname&monid=785805,2204070,2115910&sort=-uxtme

The meta section of output shows request parameters: auto-bucketing applied, grouping, measurements, start and end times, and a description of the metrics requested. It also shows the automatic bucketing interval applied, if any. uxtme_calc_3 represents the standard deviation requested for user experience time. uxtme_calc_4 is the 75th percentile of user experience time.

In this table call grouped by measurement name and ID, three data sets are returned, one for each measurement.

{
	meta: {
		bucket: "minute",
		tstart: 1490126400000,
		tend: 1490130000000,
		group: {
			monid: {
				desc: "Slot ID of measurement",
				type: "number",
				name: "Slot ID"
			},
			mname: {
				desc: "Slot name of measurement",
				type: "string",
				name: "Slot Name"
			}
		},
		monid: [
			785805,
			2204070,
			2115910
		],
		metrics: {
			count: {
				desc: "Number of total hits or datapoints",
				unit: "number",
				name: "Total number of hits"
			},
			uxtme: {
				desc: "Full User Experience time as reported by the browser",
				unit: "ms",
				name: "User Experience"
			},
			uxtme_calc_3: {
				desc: "Full User Experience time as reported by the browser",
				unit: "ms",
				name: "User Experience",
				calc: "stdev(uxtme)"
			},
			uxtme_calc_4: {
				desc: "Full User Experience time as reported by the browser",
				unit: "ms",
				name: "User Experience",
				calc: "percentile(uxtme,75)"
			},
			nwtme: {
				desc: "Total time of all network traffic measured by the Keynote agent",
				unit: "ms",
				name: "Total Network time"
			}
		},
		limit: 100000,
		dbtime: 14,
		dbname: "db_raw_1 ",
		apiversion: "33.0.0.201703191851.145882-26"
	},
	data: [
		{
			monid: 2204070,
			mname: "stephans test web-recorder txp script prod val 2",
			count: 53,
			uxtme: 18081.76,
			uxtme_calc_3: 3802.2166121506384,
			uxtme_calc_4: 19510.75,
			nwtme: 11076.66
		},
		{
			monid: 2115910,
			mname: "test",
			count: 40,
			uxtme: 4359.45,
			uxtme_calc_3: 896.9707410258208,
			uxtme_calc_4: 4494,
			nwtme: 2286.85
		},
		{
			monid: 785805,
			mname: "kite.keynote.com pub",
			count: 23,
			uxtme: 2691.4347826086955,
			uxtme_calc_3: 4420.344740012181,
			uxtme_calc_4: 2144,
			nwtme: 1516.5652173913043
		}
	]
}