Analytics API properties
This page describes API properties that you can use in API requests for DNS analytics.
Metrics
A metric is a numerical value based on an attribute of the data, for example a query count.
In API requests, metrics are set in the metrics parameter. If you need to list multiple metrics, separate them with commas.
| Metric | Name | Example | Unit |
|---|---|---|---|
| queryCount | Query count | 1000 | Count |
| uncachedCount | Uncached query count | 1 | Count |
| staleCount | Stale query count | 1 | Count |
| responseTimeAvg | Average response time | 1.0 | Time in milliseconds |
| responseTimeMedian | Median response time | 1.0 | Time in milliseconds |
| responseTime90th | 90th percentile response time | 1.0 | Time in milliseconds |
| responseTime99th | 99th percentile response time | 1.0 | Time in milliseconds |
Dimensions
Dimensions can be used to break down the data by given attributes.
In API requests, dimensions are set in the dimensions parameter. If you need to list multiple dimensions, separate them with commas.
| Dimension | Name | Example | Notes |
|---|---|---|---|
| queryName | Query Name | example.com | |
| queryType | Query Type | AAAA | Types defined by IANA. Unknown types are empty. |
| responseCode | Response Code | NOERROR | Response codes defined by IANA. Always uppercase. |
| responseCached | Response Cached | Cached | Either Cached or Uncached. |
| coloName | Colo Name | SJC | PoP code. |
| origin | Origin | 2001:db8::1 | Origin used to resolve the query. Empty if N/A or if the query was answered from cache. |
| dayOfWeek | Day Of Week | 1 | Break down by day of week. Monday is 1, and Sunday is 7. |
| tcp | TCP | 1 | Either 1 or 0 depending on the protocol used. |
| ipVersion | IP Version | 6 | IP protocol version used (currently 4 or 6). |
| querySizeBucket | Query Size Bucket | 16-31 | Query size bucket by multiples of 16. |
| responseSizeBucket | Response Size Bucket | 16-31 | Response size bucket by multiples of 16. |
Filters
Filters use the form dimension operator expression, where each part corresponds to the following:
- Dimension: Specifies the dimension to filter on. For example,
queryName. - Operator: Defines the type of filter match to use. Operators are specific to dimensions.
- Expression: States the values to include or exclude from the results. Expressions use regular expression (regex) syntax.
Filter operators
| Operator | Name | Example | Description | URL Encoded |
|---|---|---|---|---|
== | Equals | queryName==example.com | Return results where queryName is exactly example.com. | %3D%3D |
!= | Does not equal | responseCode!=NOERROR | Return results where responseCode is different from NOERROR. | !%3D |
> | Greater than | dimension>1000 | Return results where a dimension is greater than 1000. | %3E |
< | Less than | dimension<1000 | Return results where a dimension is less than 1000. | %3C |
>= | Greater than or equal to | dimension>=1000 | Return results where a dimension is greater than or equal to 1000. | %3E%3D |
<= | Less than or equal to | dimension<=1000 | Return results where a dimension is less than or equal to 1000. | %3C%3D |
Combining filters
Combine filters using OR and AND boolean logic:
ANDtakes precedence overORin all expressions.The
ORoperator is defined using a comma,or theORkeyword surrounded by whitespace.The
ANDoperator is defined using a semicolon;or theANDkeyword surrounded by whitespace.
Examples using OR
responseCode==NOERROR,responseCode==NXDOMAINindicates that response code is eitherNOERRORorNXDOMAIN.coloName==SJC OR coloName==LAXindicates queries in eitherSJCorLAX.
Examples using AND
responseCode==NOERROR;queryType==AAAAindicates that response code isNOERRORand query type isAAAA.queryType==AAAA AND coloName==SJCindicatesAAAAqueries inSJC.