# Exploring your data with CloudWatch tools and the Internet Monitor query interface
In addition to visualizing your performance and availability for your application with the Internet Monitor dashboard, there are several methods that you can use to dive deeper into the data that Internet Monitor generates for you. These methods include using CloudWatch tools with Internet Monitor data stored in CloudWatch Log files and using the Internet Monitor query interface. The tools that you can use include CloudWatch Logs Insights, CloudWatch Metrics, CloudWatch Contributor Insights, and Amazon Athena. You can use some or all these tools, as well as the dashboard, to explore Internet Monitor data, depending on your needs.
Internet Monitor aggregates CloudWatch metrics about traffic to your application and to each AWS Region, and includes data such as total traffic impact, availability, and round-trip time. This data is published to CloudWatch Logs and is also available to use with the Internet Monitor query interface. Details about geo-granularity and other aspects of the information available to explore for each one varies.
Internet Monitor publishes data for your monitor at 5 minute intervals, and then makes the data available in several ways. The following table lists scenarios for accessing Internet Monitor data, and describes features of the data that is collected for each one.
****
| Feature | CloudWatch Logs | Export to S3 | Query interface | CloudWatch dashboard |
| --- | --- | --- | --- | --- |
| Enabled by default | Yes | No | Yes | Yes |
| Number of city-networks that data is collected for | Top 500 (see note below) | All | All | All |
| Data retention | User controlled | User controlled | 30 days | 30 days |
| Geo-granularities that data is collected for | All (city-network, metro\$1network, subdivision\$1network, country\$1network) | City-network | All (city-network, metro\$1network, subdivision\$1network, country\$1network) | All (city-network, metro\$1network, subdivision\$1network, country\$1network) |
| How to query and filter data | [Use CloudWatch Logs Insights to explore Internet Monitor measurements](CloudWatch-IM-view-cw-tools-logs-insights.md) | [Use Amazon Athena to query internet measurements in Amazon S3 log files](CloudWatch-IM-view-cw-tools.S3_athena.md) | [Use the Internet Monitor query interface](CloudWatch-IM-view-cw-tools-cwim-query.md) | [Monitor and optimize with the Internet Monitor dashboard](CloudWatch-IM-monitor-and-optimize.md) |
Note: Top 500 measurements are captured for city-networks; top 250 for metro\$1networks, top 100 for subdivision\$1networks, top 50 for country\$1networks.
This chapter describes how to query and explore your data by using CloudWatch tools or the Internet Monitor query interface, together with examples for each method.
**Topics**
+ [CloudWatch Logs Insights](CloudWatch-IM-view-cw-tools-logs-insights.md)
+ [CloudWatch Contributor Insights](CloudWatch-IM-view-cw-tools-contributor-insights.md)
+ [CloudWatch Metrics](CloudWatch-IM-view-cw-tools-metrics-dashboard.md)
+ [Athena with S3 logs](CloudWatch-IM-view-cw-tools.S3_athena.md)
+ [Internet Monitor query interface](CloudWatch-IM-view-cw-tools-cwim-query.md)
# Use CloudWatch Logs Insights to explore Internet Monitor measurements
You can use CloudWatch Logs Insights queries to filter a subset of logs for a specific city or geography (client location), client ASN (ISP), and AWS source location. Internet Monitor publishes granular measurements of availability and round-trip time to CloudWatch Logs that you can explore using CloudWatch Logs Insights.
To learn more about client location accuracy in Internet Monitor, see [ Geolocation information and accuracy in Internet Monitor](CloudWatch-IM-inside-internet-monitor.md#IMGeolocationSourceAccuracy).
The examples in this section can help you create CloudWatch Logs Insights queries to learn more about your own application traffic measurements and metrics. If you use these examples in CloudWatch Logs Insights, replace *monitorName* with your own monitor name.
**View traffic optimization suggestions**
On the **Traffic insights** tab in Internet Monitor, you can view traffic optimization suggestions, filtered by a location. To see the same information that is displayed in the **Traffic optimization suggestions** section on that tab, but without the location granularity filter, you can use the following CloudWatch Logs Insights query.
1. In the AWS Management Console, navigate to CloudWatch Logs Insights.
1. For **Log Group**, select `/aws/internet-monitor/monitorName/byCity` and `/aws/internet-monitor/monitorName/byCountry`, and then specify a time range.
1. Add the following query, and then run the query.
```
fields @timestamp,
clientLocation.city as @city, clientLocation.subdivision as @subdivision, clientLocation.country as @country,
`trafficInsights.timeToFirstByte.currentExperience.serviceName` as @serviceNameField,
concat(@serviceNameField, ` (`, `serviceLocation`, `)`) as @currentExperienceField,
concat(`trafficInsights.timeToFirstByte.ec2.serviceName`, ` (`, `trafficInsights.timeToFirstByte.ec2.serviceLocation`, `)`) as @ec2Field,
`trafficInsights.timeToFirstByte.cloudfront.serviceName` as @cloudfrontField,
concat(`clientLocation.networkName`, ` (AS`, `clientLocation.asn`, `)`) as @networkName
| filter ispresent(`trafficInsights.timeToFirstByte.currentExperience.value`)
| stats avg(`trafficInsights.timeToFirstByte.currentExperience.value`) as @averageTTFB,
avg(`trafficInsights.timeToFirstByte.ec2.value`) as @ec2TTFB,
avg(`trafficInsights.timeToFirstByte.cloudfront.value`) as @cloudfrontTTFB,
sum(`bytesIn` + `bytesOut`) as @totalBytes,
latest(@ec2Field) as @ec2,
latest(@currentExperienceField) as @currentExperience,
latest(@cloudfrontField) as @cloudfront,
count(*) by @networkName, @city, @subdivision, @country
| display @city, @subdivision, @country, @networkName, @totalBytes, @currentExperience, @averageTTFB, @ec2, @ec2TTFB, @cloudfront, @cloudfrontTTFB
| sort @totalBytes desc
```
**View internet availability and RTT (p50, p90, and p95)**
To view the internet availability and round-trip time (p50, p90, and p95) for traffic, you can use the following CloudWatch Logs Insights query.
**End user geography: ** Chicago, IL, United States
**End user network (ASN): ** AS7018
**AWS service location: ** US East (N. Virginia) Region
To view the logs, do the following:
1. In the AWS Management Console, navigate to CloudWatch Logs Insights.
1. For **Log Group**, select `/aws/internet-monitor/monitorName/byCity` and `/aws/internet-monitor/monitorName/byCountry`, and then specify a time range.
1. Add the following query, and then run the query.
The query returns all the performance data for users connecting from AS7018 in Chicago, IL towards US East (N. Virginia) Region over the selected time period.
```
fields @timestamp,
internetHealth.availability.experienceScore as availabilityExperienceScore,
internetHealth.availability.percentageOfTotalTrafficImpacted as percentageOfTotalTrafficImpacted,
internetHealth.performance.experienceScore as performanceExperienceScore,
internetHealth.performance.roundTripTime.p50 as roundTripTimep50,
internetHealth.performance.roundTripTime.p90 as roundTripTimep90,
internetHealth.performance.roundTripTime.p95 as roundTripTimep95
| filter clientLocation.country == `United States`
and clientLocation.city == `Chicago`
and serviceLocation == `us-east-1`
and clientLocation.asn == 7018
```
For more information, see [Analyzing log data with CloudWatch Logs Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AnalyzingLogData.html).
# Use Contributor Insights to identify top locations and ISPs
CloudWatch Contributor Insights can help you identify top client locations and ASNs (typically, internet service providers or ISPs) for your AWS application. Use the following sample Contributor Insights rules to get started with rules that are useful with Internet Monitor. For more information, see [Create a Contributor Insights rule in CloudWatch](ContributorInsights-CreateRule.md).
To learn more about client location accuracy in Internet Monitor, see [ Geolocation information and accuracy in Internet Monitor](CloudWatch-IM-inside-internet-monitor.md#IMGeolocationSourceAccuracy).
**Note**
Internet Monitor stores internet measurements data every five minutes, so after you set up a Contributor Insights rule, you must adjust the period to five minutes to see a graph.
**View top locations and ASNs impacted by an availability impact**
To view top client locations and ASNs impacted by a drop in availability, you can use the following Contributor Insights rule in the Syntax editor. Replace *monitor-name* with your own monitor name.
```
{
"Schema": {
"Name": "CloudWatchLogRule",
"Version": 1
},
"AggregateOn": "Sum",
"Contribution": {
"Filters": [
{
"Match": "$.clientLocation.city",
"IsPresent": true
}
],
"Keys": [
"$.clientLocation.city",
"$.clientLocation.networkName"
],
"ValueOf": "$.awsInternetHealth.availability.percentageOfTotalTrafficImpacted"
},
"LogFormat": "JSON",
"LogGroupNames": [
"/aws/internet-monitor/monitor-name/byCity"
]
}
```
**View top client locations and ASNs impacted by a latency impact**
To view top client locations and ASNs impacted by an increase in round-trip time (latency), you can use the following Contributor Insights rule in the Syntax editor. Replace *monitor-name* with your own monitor name.
```
{
"Schema": {
"Name": "CloudWatchLogRule",
"Version": 1
},
"AggregateOn": "Sum",
"Contribution": {
"Filters": [ {
"Match": "$.clientLocation.city",
"IsPresent": true
}
],
"Keys": [
"$.clientLocation.city",
"$.clientLocation.networkName"
],
"ValueOf": "$.awsInternetHealth.performance.percentageOfTotalTrafficImpacted"
},
"LogFormat": "JSON",
"LogGroupNames": [
"/aws/internet-monitor/monitor-name/byCity"
]
}
```
**View top client locations and ASNs impacted by total percentage of traffic**
To view top client locations and ASNs impacted by total percentage of traffic, you can use the following Contributor Insights rule in the Syntax editor. Replace *monitor-name* with your own monitor name.
```
{
"Schema": {
"Name": "CloudWatchLogRule",
"Version": 1
},
"AggregateOn": "Sum",
"Contribution": {
"Filters": [
{
"Match": "$.clientLocation.city",
"IsPresent": true
}
],
"Keys": [
"$.clientLocation.city",
"$.clientLocation.networkName"
],
"ValueOf": "$.percentageOfTotalTraffic"
},
"LogFormat": "JSON",
"LogGroupNames": [
"/aws/internet-monitor/monitor-name/byCity"
]
}
```
# View Internet Monitor metrics or set alarms in CloudWatch Metrics
You can view or set alarms on Internet Monitor metrics by using CloudWatch alarms and CloudWatch Metrics in the CloudWatch console. Internet Monitor publishes metrics to your account, including metrics for performance, availability, round-trip time, and throughput (bytes per second). To find all metrics for your monitor, in the CloudWatch Metrics dashboard, see the custom namespace `AWS/InternetMonitor`.
To see examples for using several of these metrics to help determine values to choose for a city-networks maximum limit for your monitor, see [Choosing a city-network maximum value](IMCityNetworksMaximum.md). To learn more about setting alarms for Internet Monitor, see [Create alarms with Internet Monitor](CloudWatch-IM-create-alarm.md).
Metrics are aggregated across all internet traffic to your VPCs, Network Load Balancers, CloudFront distributions, or WorkSpaces directories in the monitor, and to all traffic to each AWS Region and internet edge location that is monitored. Regions are defined by the service location, which can either be all locations or a specific Region, such as `us-east-1`.
Note: *city-networks* are pairs of client locations and the ASNs the clients use (typically internet service providers or ISPs).
Internet Monitor provides the following metrics.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-IM-view-cw-tools-metrics-dashboard.html)
For more information, see [Metrics in Amazon CloudWatch](working_with_metrics.md).
# Use Amazon Athena to query internet measurements in Amazon S3 log files
You can use Amazon Athena to query and view the internet measurements that Internet Monitor publishes to an Amazon S3 bucket. There's an option in Internet Monitor to publish internet measurements for your application to an S3 bucket for internet-facing traffic for your monitored city-networks (client locations and ASNs, typically internet service providers or ISPs). Regardless of whether you choose to publish measurements to S3, Internet Monitor automatically publishes internet measurements to CloudWatch Logs every five minutes for the top 500 (by traffic volume) city-networks for each monitor.
This chapter includes steps for how to create a table in Athena for internet measurements located in an S3 log file, and then provides [example queries](#CloudWatch-IM-view-cw-tools.S3_athena.athena-sample-queries) to see different views of the measurements. For example, you can query for your top 10 impacted city-networks by latency impact.
## Using Amazon Athena to create a table for internet measurements in Internet Monitor
To start using Athena with your Internet Monitor S3 log files, you first create a table for the internet measurements.
Follow the steps in this procedure to create a table in Athena based on the S3 log files. Then, you can run Athena queries on the table, such as [these example internet measurements queries](#CloudWatch-IM-view-cw-tools.S3_athena.athena-sample-queries), to get information about your measurements.
**To create an Athena table**
1. Open the Athena console at [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/).
1. In the Athena query editor, enter a query statement to generate a table with Internet Monitor internet measurements. Replace the value for the LOCATION parameter with the location of S3 bucket where your Internet Monitor internet measurements are stored.
```
CREATE EXTERNAL TABLE internet_measurements (
version INT,
timestamp INT,
clientlocation STRING,
servicelocation STRING,
percentageoftotaltraffic DOUBLE,
bytesin INT,
bytesout INT,
clientconnectioncount INT,
internethealth STRING,
trafficinsights STRING
)
PARTITIONED BY (year STRING, month STRING, day STRING)
ROW FORMAT SERDE 'org.openx.data.jsonserde.JsonSerDe'
LOCATION
's3://amzn-s3-demo-bucket/bucket_prefix/AWSLogs/account_id/internetmonitor/AWS_Region/'
TBLPROPERTIES ('skip.header.line.count' = '1');
```
1. Enter a statement to create a partition to read the data. For example, the following query creates a single partition for a specified date and location:
```
ALTER TABLE internet_measurements
ADD PARTITION (year = 'YYYY', month = 'MM', day = 'dd')
LOCATION
's3://amzn-s3-demo-bucket/bucket_prefix/AWSLogs/account_id/internetmonitor/AWS_Region/YYYY/MM/DD';
```
1. Choose **Run**.
**Example Athena statements for internet measurements**
The following is an example of a statement to generate a table:
```
CREATE EXTERNAL TABLE internet_measurements (
version INT,
timestamp INT,
clientlocation STRING,
servicelocation STRING,
percentageoftotaltraffic DOUBLE,
bytesin INT,
bytesout INT,
clientconnectioncount INT,
internethealth STRING,
trafficinsights STRING
)
PARTITIONED BY (year STRING, month STRING, day STRING)
ROW FORMAT SERDE 'org.openx.data.jsonserde.JsonSerDe'
LOCATION 's3://internet-measurements/TestMonitor/AWSLogs/1111222233332/internetmonitor/us-east-2/'
TBLPROPERTIES ('skip.header.line.count' = '1');
```
The following is an example of a statement to create a partition to read the data:
```
ALTER TABLE internet_measurements
ADD PARTITION (year = '2023', month = '04', day = '07')
LOCATION 's3://internet-measurements/TestMonitor/AWSLogs/1111222233332/internetmonitor/us-east-2/2023/04/07/'
```
## Sample Amazon Athena queries to use with internet measurements in Internet Monitor
This section includes example queries that you can use with Amazon Athena to get information about your application's internet measurements published to Amazon S3.
**Query your top 10 impacted (by total percentage of traffic) client locations and ASNs**
Run this Athena query to return your top 10 impacted (by total percentage of traffic) city-networks—that is, client locations and ASNs, typically internet service providers.
```
SELECT json_extract_scalar(clientLocation, '$.city') as city,
json_extract_scalar(clientLocation, '$.networkname') as networkName,
sum(percentageoftotaltraffic) as percentageoftotaltraffic
FROM internet_measurements
GROUP BY json_extract_scalar(clientLocation, '$.city'),
json_extract_scalar(clientLocation, '$.networkname')
ORDER BY percentageoftotaltraffic desc
limit 10
```
**Query your top 10 impacted (by availability) client locations and ASNs **
Run this Athena query to return your top 10 impacted (by total percentage of traffic) city-networks—that is, client locations and ASNs, typically internet service providers.
```
SELECT json_extract_scalar(clientLocation, '$.city') as city,
json_extract_scalar(clientLocation, '$.networkname') as networkName,
sum(
cast(
json_extract_scalar(
internetHealth,
'$.availability.percentageoftotaltrafficimpacted'
)
as double )
) as percentageOfTotalTrafficImpacted
FROM internet_measurements
GROUP BY json_extract_scalar(clientLocation, '$.city'),
json_extract_scalar(clientLocation, '$.networkname')
ORDER BY percentageOfTotalTrafficImpacted desc
limit 10
```
**Query your top 10 impacted (by latency) client locations and ASNs **
Run this Athena query to return your top 10 impacted (by latency impact) city-networks—that is, client locations and ASNs, typically internet service providers.
```
SELECT json_extract_scalar(clientLocation, '$.city') as city,
json_extract_scalar(clientLocation, '$.networkname') as networkName,
sum(
cast(
json_extract_scalar(
internetHealth,
'$.performance.percentageoftotaltrafficimpacted'
)
as double )
) as percentageOfTotalTrafficImpacted
FROM internet_measurements
GROUP BY json_extract_scalar(clientLocation, '$.city'),
json_extract_scalar(clientLocation, '$.networkname')
ORDER BY percentageOfTotalTrafficImpacted desc
limit 10
```
**Query traffic highlights for your client locations and ASNs **
Run this Athena query to return traffic highlights, including availability score, performance score, and time to first byte for your city-networks—that is, client locations and ASNs, typically internet service providers. .
```
SELECT json_extract_scalar(clientLocation, '$.city') as city,
json_extract_scalar(clientLocation, '$.subdivision') as subdivision,
json_extract_scalar(clientLocation, '$.country') as country,
avg(cast(json_extract_scalar(internetHealth, '$.availability.experiencescore') as double)) as availabilityScore,
avg(cast(json_extract_scalar(internetHealth, '$.performance.experiencescore') as double)) performanceScore,
avg(cast(json_extract_scalar(trafficinsights, '$.timetofirstbyte.currentexperience.value') as double)) as averageTTFB,
sum(bytesIn) as bytesIn,
sum(bytesOut) as bytesOut,
sum(bytesIn + bytesOut) as totalBytes
FROM internet_measurements
where json_extract_scalar(clientLocation, '$.city') != 'N/A'
GROUP BY
json_extract_scalar(clientLocation, '$.city'),
json_extract_scalar(clientLocation, '$.subdivision'),
json_extract_scalar(clientLocation, '$.country')
ORDER BY totalBytes desc
limit 100
```
For more information about using Athena, see the [Amazon Athena User Guide](https://docs.aws.amazon.com/athena/latest/ug/).
# Use the Internet Monitor query interface
An option for understanding more about internet traffic for your AWS application is to use the Internet Monitor *query interface*. To use the query interface, you create a query with data filters that you choose, and then run the query to return a subset of your Internet Monitor data. Exploring the data that the query returns can give you insights into how your application is performing on the internet.
You can query and explore all the metrics that Internet Monitor captures with your monitor, including availability and performance scores, bytes transferred, round-trip times, and time to first byte (TTFB).
Internet Monitor uses the query interface to provide the data that you can explore in the Internet Monitor console dashboard. By using search options in the dashboard—on the **Analyze** page or the **Optimize** page—you can query and filter internet data for your application.
If you'd like more flexibility to explore and filter your data than the dashboard provides, you can use the query interface yourself, by using Internet Monitor API operations with the AWS Command Line Interface or with an AWS SDK. This section introduces the types of queries that you can use with the query interface, and the filters that you can specify to create a subset of data, to get insights about internet traffic for your application.
**Topics**
+ [How to use the query interface](#CloudWatch-IM-view-cw-tools-cwim-query-use-query)
+ [Query examples](#CloudWatch-IM-view-cw-tools-cwim-query-example-queries)
+ [Get query results](#CloudWatch-IM-view-cw-tools-cwim-query-get-data)
+ [Troubleshooting](#CloudWatch-IM-view-cw-tools-cwim-query-troubleshooting)
## How to use the query interface
You create a query with the query interface by choosing a *query type*, and then specifying filter values, to return a specific desired subset of your log file data. Then, you can work with the data subset, to further filter and sort, create reports, and so on.
The query process works like this:
1. When you run a query, Internet Monitor returns a `query ID` that is unique to the query. This section describes the query types that are available, and options for filtering data in queries. To understand how this works, you can also review the section on [query examples](#IMQueryInterfaceExamples).
1. You specify the query ID with your monitor name with the [GetQueryResults](https://docs.aws.amazon.com/internet-monitor/latest/api/API_GetQueryResults.html) API operation to return data results for the query. Each query type returns a different set of data fields. To learn more, see [Get query results](#IMGetQueryData).
The query interface provides the following query types. Each query type returns a different set of information about your traffic from the log files, as shown.
+ **Measurements:** Provides availability score, performance score, total traffic, and round-trip times, at 5 minute intervals.
+ **Top locations:** Provides availability score, performance score, total traffic, and time to first byte (TTFB) information, for the top location and ASN combinations that you're monitoring, by traffic volume.
+ **Top locations details:** Provides TTFB for Amazon CloudFront, your current configuration, and the best performing Amazon EC2 configuration, at 1 hour intervals.
+ **Overall traffic suggestions:** Provides TTFB, using a 30-day weighted average, for all traffic in each AWS location that is monitored.
+ **Overall traffic suggestions details:** Provides TTFB, using a 30-day weighted average, for each top location, for a proposed AWS location.
+ **Routing suggestions:** Provides the predicted average round-trip time (RTT) from an IP prefix toward an AWS location for a DNS resolver. The RTT is calculated at one hour intervals, over a one hour period.
You can filter the data more by using specific criteria. With most query types, except routing suggestions, you can filter by specifying one or more of the following criteria:
+ **AWS location:** For AWS location, you can specify CloudFront or an AWS Region, such as `us-east-2`.
+ **ASN:** Specify the autonomous system number (ASN) of a DNS resolver (typically, an ISP), for example, 4225.
+ **Client location:** For location, specify a city, metro, subdivision, or country.
+ **Proposed AWS location:** Specify an AWS Region, such as `us-east-2`, or an AWS Local Zone. You can use this filter with the overall traffic suggestions details query type.
+ **Geo:** Specify `geo` for some queries. This is required for queries that use the `Top locations` query type, but not allowed for other query types. To understand when to specify `geo` for filter parameters, see the [query examples](#IMQueryInterfaceExamples) section.
For the routing suggestions query type, you can filter the data more by specifying one or more of the following criteria:
+ **Current AWS location:** Specify an AWS Region, such as `us-east-2`.
+ **Proposed AWS location:** Specify an AWS Region, such as `us-east-2`, or an AWS Local Zone.
+ **IPv4 prefix:** Specify an IPv4 prefix in the standard format, similar to `192.0.2.0/24`.
+ **Monitor ARN:** Specify the ARN for a specific monitor.
+ **DNS resolver IP:** Specify the IP address of a DNS resolver.
+ **DNS resolver ISP:** Specify the name of a DNS resolver (typically an ISP), for example, `Cloudflare`.
+ **DNS resolver ASN:** Specify the autonomous system number (ASN) of a DNS resolver, for example, 4225.
The operators that you can use for filtering your data are `EQUALS` and `NOT_EQUALS`. For details about filtering parameters, see the [FilterParameter](https://docs.aws.amazon.com/internet-monitor/latest/api/API_FilterParameter.html) API operation.
To see details about the query interface operations, see the following API operations in the Internet Monitor API Reference Guide:
+ To create and run a query, see the [StartQuery](https://docs.aws.amazon.com/internet-monitor/latest/api/API_StartQuery.html) API operation.
+ To stop a query, see the [StopQuery](https://docs.aws.amazon.com/internet-monitor/latest/api/API_StopQuery.html) API operation.
+ To return data for a query that you've created, see the [GetQueryResults](https://docs.aws.amazon.com/internet-monitor/latest/api/API_GetQueryResults.html) API operation.
+ To retrieve the status of a query, see the [GetQueryStatus](https://docs.aws.amazon.com/internet-monitor/latest/api/API_GetQueryStatus.html) API operation.
## Query examples
To create a query that you can use to retrieve a filtered set of data from your monitor's log file, you use the [StartQuery](https://docs.aws.amazon.com/internet-monitor/latest/api/API_StartQuery.html) API operation. You specify a query type and filter parameters for the query. Then, when you use the Internet Monitor query interface API operation to get query results using the query, it will retrieve the subset of your data that you want to work with.
To illustrate how query types and filter parameters work, let's look at some examples.
**Example 1**
Let's say that you want to retrieve all of your monitor's log file data for a specific country, except for one city. The following example shows filter parameters for a query that you could create with the `StartQuery` operation for this scenario.
```
{
MonitorName: "TestMonitor"
StartTime: "2023-07-12T20:00:00Z"
EndTime: "2023-07-12T21:00:00Z"
QueryType: "MEASUREMENTS"
FilterParameters: [
{
Field: "country",
Operator: "EQUALS",
Values: ["Germany"]
},
{
Field: "city",
Operator: "NOT_EQUALS",
Values: ["Berlin"]
},
]
}
```
**Example 2**
As another example, let's say that you want to see your top locations by metropolitan area. You could use the following example query for this scenario.
```
{
MonitorName: "TestMonitor"
StartTime: "2023-07-12T20:00:00Z"
EndTime: "2023-07-12T21:00:00Z"
QueryType: "TOP_LOCATIONS"
FilterParameters: [
{
Field: "geo",
Operator: "EQUALS",
Values: ["metro"]
},
]
}
```
**Example 3**
Now, let's say that you want to see the top city-network combinations in the Los Angeles metro area. To do this, specify `geo=city`, and then set `metro` to Los Angeles. Now, the query returns the top city-networks in the Los Angeles metro area instead of the top metro\$1networks overall.
Here's the example query that you could use:
```
{
MonitorName: "TestMonitor"
StartTime: "2023-07-12T20:00:00Z"
EndTime: "2023-07-12T21:00:00Z"
QueryType: "TOP_LOCATIONS"
FilterParameters: [
{
Field: "geo",
Operator: "EQUALS",
Values: ["city"]
},
{
Field: "metro",
Operator: "EQUALS",
Values: ["Los Angeles"]
}
]
}
```
**Example 4**
Next, let's say that you want to retrieve TTFB data for a specific subdivision (for example, a U.S. state).
The following is an example query for this scenario:
```
{
MonitorName: "TestMonitor"
StartTime: "2023-07-12T20:00:00Z"
EndTime: "2023-07-12T21:00:00Z"
QueryType: "TOP_LOCATION_DETAILS"
FilterParameters: [
{
Field: "subdivision",
Operator: "EQUALS",
Values: ["California"]
},
]
}
```
**Example 5**
Now, let's say that you want to retrieve TTFB data for every location where your application has client traffic.
The following is an example query for this scenario:
```
{
MonitorName: "TestMonitor"
StartTime: "2023-07-12T20:00:00Z"
EndTime: "2023-07-12T21:00:00Z"
QueryType: "OVERALL_TRAFFIC_SUGGESTIONS"
FilterParameters: []
}
Results:
[us-east-1, 40, us-west-2, 30],
[us-east-1, 40, us-west-1, 35],
[us-east-1, 40, us-east-1, 44],
[us-east-1, 40, CloudFront, 22],
...
[us-east-2, 44, us-west-2, 30],
[us-east-2, 44, us-west-1, 35],
...
```
**Example 6**
Let's say that you want to retrieve TTFB data for a specific new AWS Region.
The following is an example query for this scenario:
```
{
MonitorName: "TestMonitor"
StartTime: "2023-07-12T20:00:00Z"
EndTime: "2023-07-12T21:00:00Z"
QueryType: "OVERALL_TRAFFIC_SUGGESTIONS_DETAILS"
FilterParameters: [
{
Field: "proposed_aws_location",
Operator: "EQUALS",
Values: ["us-west-2"]
},
]
}
Results:
[San Jose, San Jose-Santa Clara, California, United States, 7922, us-east-1, 40, 350, 350, us-west-2, 45]
[San Jose, San Jose-Santa Clara, California, United States, 7922, us-west-1, 35, 450, 450, us-west-2, 45]
```
**Example 7**
A final example is to retrieve data for specific DNS resolvers.
The following is an example query for this scenario:
```
{
MonitorName: "TestMonitor"
StartTime: "2023-07-12T20:00:00Z"
EndTime: "2023-07-12T21:00:00Z"
QueryType: "ROUTING_SUGGESTIONS"
FilterParameters: [
{
Field: "proposed_aws_location",
Operator: "EQUALS",
Values: ["us-east-1"]
},
]
}
Results:
[162.158.180.245, 13335, Cloudflare, [5.4.0.0/14], us-east-2, 200.0, us-east-1, 160.0]
[162.158.180.243, 13313, Cloudflare, [5.4.0.0/10], us-east-2, 150.0, us-east-1, 125.0]
```
## Get query results
After you define a query, you can return a set of results with the query by running another Internet Monitor API operation, [GetQueryResults](https://docs.aws.amazon.com/internet-monitor/latest/api/API_GetQueryResults.html). When you run `GetQueryResults`, you specify the query ID for the query that you've defined, along with the name of your monitor. `GetQueryResults` retrieves data for the specified query into a result set.
When you run a query, make sure that the query has finished running before you use `GetQueryResults` to look at the results. You can determine if the query has completed by using the [GetQueryStatus](https://docs.aws.amazon.com/internet-monitor/latest/api/API_GetQueryStatus.html) API operation. When the `Status` for the query is `SUCCEEDED`, you can go ahead with reviewing the results.
When your query completes, you can use the following information to help you review the results. Each query type that you use to create a query includes a unique set of data fields from the log files, as described in the following list:
**Measurements**
The `measurements` query type returns the following data:
`timestamp, availability, performance, bytes_in, bytes_out, rtt_p50, rtt_p90, rtt_p95`
**Top locations**
The `top locations` query type groups data by location, and provides the data averaged over the time period. The data that it returns includes the following:
`aws_location, city, metro, subdivision, country, asn, availability, performance, bytes_in, bytes_out, current_fbl, best_ec2, best_ec2_region, best_cf_fbl`
Note that `city`, `metro`, and `subdivision` are only returned if you choose that location type for the `geo` field. The following location fields are returned, depending on the location type that you specify for `geo`:
```
city = city, metro, subdivision, country
metro = metro, subdivision, country
subdivision = subdivision, country
country = country
```
**Top locations details**
The `top locations details` query type returns data grouped hour by hour. The query returns the following data:
`timestamp, current_service, current_fbl, best_ec2_fbl, best_ec2_region, best_cf_fbl`
**Overall traffic suggestions**
The `overall traffic suggestions` query type returns data grouped hour by hour. The query returns the following data:
`current_aws_location, proposed_aws_location, average_fbl, traffic, optimized_traffic_excluding_cf, optimized_traffic_including_cf`
**Overall traffic suggestions details**
The `overall traffic suggestions details` query type returns data grouped hour by hour. The query returns the following data:
`aws_location, city, metro, subdivision, country, asn, traffic, current_aws_location, fbl_data`
**Routing suggestions**
The `routing suggestions` query type returns data grouped hour by hour. The query returns the following data:
`dns_resolver_ip, dns_resolver_asn, dns_resolver_isp, ipv4_prefixes, current_aws_location, current_latency, proposed_aws_location, proposed_latency`
When you run the `GetQueryResults` API operation, Internet Monitor returns the following in the response:
+ A *data string array* that contains the results that the query returns. The information is returned in arrays that are aligned with the `Fields` field, also returned by the API call. Using the `Fields` field, you can parse the information from the `Data` repository and then further filter or sort it for your purposes.
+ An *array of fields* that lists the fields that the query returned data for (in the `Data` field response). Each item in the array is a name-datatype pair, such as `availability_score`-`float`.
## Troubleshooting
If errors are returned when you use query interface API operations, verify that you have the required permissions to use Internet Monitor. Specifically, make sure that you have the following permissions:
```
internetmonitor:StartQuery
internetmonitor:GetQueryStatus
internetmonitor:GetQueryResults
internetmonitor:StopQuery
```
These permissions are included in the recommended AWS Identity and Access Management policy to use the Internet Monitor dashboard in the console. For more information, see [AWS managed policies for Internet Monitor](CloudWatch-IM-permissions.md).