# Internet Monitor クエリインターフェイスを使用する
AWS アプリケーションのインターネットトラフィックをより深く理解するには、Internet Monitor の*クエリインターフェイス*を使用する方法があります。クエリインターフェイスを使用するには、選択したデータフィルタを使用してクエリを作成してから、そのクエリを実行して Internet Monitor データのサブセットを返します。クエリにより返されるデータを調べると、アプリケーションがインターネット上でどのように動作しているのか分かります。
可用性とパフォーマンスのスコア、転送バイト数、往復時間、先頭バイトまでの時間 (TTFB) など、Internet Monitor がモニターでキャプチャする、すべてのメトリクスをクエリして調べることができます。
Internet Monitor はクエリインターフェイスを使用してデータを提供し、Internet Monitor コンソールのダッシュボードでそのデータを調べることができます。**[分析]** ページまたは **[最適化]** ページのダッシュボードにある検索オプションを使用すると、アプリケーションのインターネットデータをクエリおよびフィルタリングできます。
ダッシュボードよりも柔軟にデータを調べたりフィルタリングしたりしたい場合は、AWS Command Line Interface または AWS SDK と組み合わせて Internet Monitor API オペレーションを使うと、自分でクエリインターフェイスを使えます。このセクションでは、アプリケーションのインターネットトラフィックに関する洞察を得るために、クエリインターフェイスで使用可能なクエリの種類と、データのサブセット作成時に指定するフィルターについて説明します。
**Topics**
+ [クエリインターフェースを使用する方法](#CloudWatch-IM-view-cw-tools-cwim-query-use-query)
+ [クエリの例](#CloudWatch-IM-view-cw-tools-cwim-query-example-queries)
+ [クエリ結果を取得する](#CloudWatch-IM-view-cw-tools-cwim-query-get-data)
+ [トラブルシューティング](#CloudWatch-IM-view-cw-tools-cwim-query-troubleshooting)
## クエリインターフェースを使用する方法
クエリインターフェイスで、クエリタイプを選択し、フィルタの値を指定してクエリを作成すると、ログファイルから目的のデータのサブセットが返ってきます。その後、データサブセットをさらに絞り込んだり、並べ替えたり、レポートを作成したりできます。
このクエリプロセスの動作は、次のようになります。
1. クエリを実行すると、Internet Monitor はクエリ固有の `query ID` を返します。このセクションでは、使用可能なクエリタイプと、クエリ内のデータをフィルタリングするオプションについて説明します。この仕組みを理解するには、「[クエリの例](#IMQueryInterfaceExamples)」のセクションもご覧ください。
1. [GetQueryResults](https://docs.aws.amazon.com/internet-monitor/latest/api/API_GetQueryResults.html) API オペレーションでは、クエリ ID とモニター名を指定して、クエリの結果のデータを返します。クエリの種類ごとに、異なるデータフィールドのセットが返されます。詳細については、「[クエリ結果を取得する](#IMGetQueryData)」をご参照ください。
クエリインターフェイスは、次のクエリタイプをサポートします。次に示すように、ログファイルからトラフィックについての情報を、クエリタイプごとに返します。
+ **測定値:** 可用性スコア、パフォーマンススコア、総トラフィック、往復時間を 5 分間隔で表示します。
+ **上位のロケーション:** モニタリング中の上位のロケーションと ASN の組み合わせについて、可用性スコア、パフォーマンススコア、総トラフィック、最初のバイトまでの時間 (TTFB) 情報を、トラフィック量別に表示します。
+ **上位のロケーションの詳細:** Amazon CloudFront の TTFB、現在の設定、最もパフォーマンスの高い Amazon EC2 設定を 1 時間間隔で表示します。
+ **全体的なトラフィックの提案:** モニタリングされる各 AWS ロケーションのすべてのトラフィックについて、30 日間の加重平均を使用して TTFB を提供します。
+ **全体的なトラフィックの提案の詳細:** 30 日間の加重平均を使用して、上位ロケーションごとに、提案された AWS ロケーションの TTFB を提供します。
+ **ルーティングの提案:** IP プレフィックスから DNS リゾルバーの AWS ロケーションまでの予測平均ラウンドトリップタイム (RTT) を提供します。RTT は、1 時間ごとに 1 時間分のデータを基に計算されます。
特定の条件を使用して、データをさらにフィルタリングできます。ルーティング提案を除くほとんどのクエリタイプでは、次の条件の 1 つ以上を指定してフィルタリングできます。
+ **AWS ロケーション:**AWS ロケーションには、CloudFront または `us-east-2` などの AWS リージョンを指定できます。
+ **ASN:** DNS リゾルバー (通常は ISP) のAS 番号 (ASN) (例えば、4225 など) を指定します。
+ **クライアントロケーション:**ロケーションとして都市、地下鉄、行政区画、または国を指定します。
+ **提案された AWS ロケーション:** `us-east-2` などの AWS リージョン、または AWS ローカルゾーンを指定します。このフィルターは、全体的なトラフィック提案の詳細クエリタイプで使用できます。
+ **地域:** 一部のクエリでは、`geo` を指定します。これは `Top locations` のクエリタイプを使用するクエリでは必須ですが、他のクエリタイプでは使用できません。フィルタパラメーターの `geo` を指定するタイミングについては、「[クエリの例](#IMQueryInterfaceExamples)」セクションを参照してください。
ルーティング提案クエリ タイプでは、次の条件を 1 つ以上指定することで、データをさらに絞り込めます。
+ **現在の AWS ロケーション:** `us-east-2` などの AWS リージョンを指定します。
+ **提案された AWS ロケーション:** `us-east-2` などの AWS リージョン、または AWS ローカルゾーンを指定します。
+ **IPv4 プレフィックス:** `192.0.2.0/24` のように、IPv4 プレフィックスを標準形式で指定します。
+ **Monitor ARN:** 特定のモニターの ARN を指定します。
+ **DNS リゾルバー IP:** DNS リゾルバーの IP アドレスを指定します。
+ **DNS リゾルバー ISP:** DNS リゾルバー (通常は ISP) の名前 (例えば、`Cloudflare` など) を指定します。
+ **DNS リゾルバー ASN:** DNS リゾルバーの AS 番号 (ASN) (例えば、4225 など) を指定します。
データのフィルタリングに使用できる演算子は、`EQUALS` と `NOT_EQUALS` です。パラメータのフィルタリングについて詳しくは、[FilterParameter](https://docs.aws.amazon.com/internet-monitor/latest/api/API_FilterParameter.html) API のオペレーションを参照してください。
クエリインターフェイスのオペレーションの詳細については、「Internet Monitor API リファレンスガイド」にある次の API オペレーションを参照してください。
+ クエリを作成して実行するには、[StartQuery](https://docs.aws.amazon.com/internet-monitor/latest/api/API_StartQuery.html) API オペレーションを参照してください。
+ クエリを停止するには、[StopQuery](https://docs.aws.amazon.com/internet-monitor/latest/api/API_StopQuery.html) API オペレーションを参照してください。
+ 作成したクエリを使用してデータを返すには、[GetQueryResults](https://docs.aws.amazon.com/internet-monitor/latest/api/API_GetQueryResults.html) API オペレーションを参照してください。
+ クエリのステータスを取得するには、[GetQueryStatus](https://docs.aws.amazon.com/internet-monitor/latest/api/API_GetQueryStatus.html) API オペレーションを参照してください。
## クエリの例
モニターのログファイルから、フィルタリングされたデータセットを取得するクエリを作成するには、[StartQuery](https://docs.aws.amazon.com/internet-monitor/latest/api/API_StartQuery.html) API オペレーションを使用します。クエリについて、クエリタイプとフィルタパラメータを指定します。次に、Internet Monitor クエリインターフェイス API オペレーションを使用してクエリ結果を取得すると、処理するデータのサブセットが取得されます。
クエリタイプとフィルタパラメータがどのように動作するのか、いくつかの例を挙げて説明します。
**例 1**
ある都市を除き、特定の国のモニターから、ログファイルのデータをすべて取得したいとしましょう。次の例は、このシナリオの `StartQuery` オペレーションで作成できる、クエリのフィルターパラメーターを示しています。
```
{
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"]
},
]
}
```
**例 2**
別の例として、大都市圏ごとに上位のロケーションを確認したいとしましょう。このシナリオでは、次の例で示すクエリを使用できます。
```
{
MonitorName: "TestMonitor"
StartTime: "2023-07-12T20:00:00Z"
EndTime: "2023-07-12T21:00:00Z"
QueryType: "TOP_LOCATIONS"
FilterParameters: [
{
Field: "geo",
Operator: "EQUALS",
Values: ["metro"]
},
]
}
```
**例 3**
例えば、ロサンゼルスの大都市圏で最もよく利用されている、都市とネットワークの組み合わせを確認するとします。そのためには、`geo=city` を指定してから、`metro` をロサンゼルスに設定します。これで、全体の大都市圏とネットワークではなく、ロサンゼルス大都市圏における上位の都市ネットワークを、クエリが返すようになりました。
次のクエリの例が使用できます。
```
{
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"]
}
]
}
```
**例 4**
次に、特定の行政区画 (米国の州など) の TTFB データを取得するとします。
このシナリオのクエリは、次の例のようになります。
```
{
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"]
},
]
}
```
**例 5**
次に、アプリケーションにクライアントトラフィックがあるすべてのロケーションの TTFB データを取得するとします。
このシナリオのクエリは、次の例のようになります。
```
{
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],
...
```
**例 6**
特定の新しい AWS リージョンの TTFB データを取得するとします。
このシナリオのクエリは、次の例のようになります。
```
{
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]
```
**例 7**
最後の例は、特定の DNS リゾルバーのデータの取得についてです。
このシナリオのクエリは、次の例のようになります。
```
{
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]
```
## クエリ結果を取得する
クエリを実行した後、別の Internet Monitor API オペレーション [GetQueryResults](https://docs.aws.amazon.com/internet-monitor/latest/api/API_GetQueryResults.html) を実行すると、結果のセットをクエリとともに返すことができます。`GetQueryResults` を実行するときに、クエリで定義したクエリ ID と、モニターの名前を指定します。`GetQueryResults` は指定したクエリの結果セットからデータを取得します。
クエリを実行する場合は、`GetQueryResults` を実行して結果を見る前に、クエリの実行を完了していたことを確認してください。[GetQueryStatus](https://docs.aws.amazon.com/internet-monitor/latest/api/API_GetQueryStatus.html) API オペレーションを使用すると、クエリが完了したかどうか確認できます。クエリの `Status` が `SUCCEEDED` になったら、結果を確認してください。
クエリが完了した後は、次の情報が結果の確認に役立ちます。次のリストで説明するように、クエリの作成時に使用したクエリタイプには、それぞれログファイルに固有な、一連のデータフィールドが含まれています。
**測定値**
`measurements` のクエリタイプでは、次のデータが返ります。
`timestamp, availability, performance, bytes_in, bytes_out, rtt_p50, rtt_p90, rtt_p95`
**上位のロケーション**
`top locations` クエリタイプは、場所ごとにデータをグループ化し、その期間の平均データを提供します。返されるデータには、次が含まれます。
`aws_location, city, metro, subdivision, country, asn, availability, performance, bytes_in, bytes_out, current_fbl, best_ec2, best_ec2_region, best_cf_fbl`
`city`、`metro` および `subdivision` は、`geo` フィールドでロケーションタイプを選択した場合にのみ返されることに注意してください。`geo` で指定したロケーションタイプに応じて、次のロケーションフィールドが返されます。
```
city = city, metro, subdivision, country
metro = metro, subdivision, country
subdivision = subdivision, country
country = country
```
**上位のロケーションの詳細**
`top locations details` クエリタイプは、時間ごとにグループ化されたデータを返します。クエリは次を返します。
`timestamp, current_service, current_fbl, best_ec2_fbl, best_ec2_region, best_cf_fbl`
**全体的なトラフィックの提案**
`overall traffic suggestions` クエリタイプは、時間ごとにグループ化されたデータを返します。クエリは次を返します。
`current_aws_location, proposed_aws_location, average_fbl, traffic, optimized_traffic_excluding_cf, optimized_traffic_including_cf`
**全体的なトラフィックに関する提案の詳細**
`overall traffic suggestions details` クエリタイプは、時間ごとにグループ化されたデータを返します。クエリは次を返します。
`aws_location, city, metro, subdivision, country, asn, traffic, current_aws_location, fbl_data`
**ルーティングの提案**
`routing suggestions` クエリタイプは、時間ごとにグループ化されたデータを返します。クエリは次を返します。
`dns_resolver_ip, dns_resolver_asn, dns_resolver_isp, ipv4_prefixes, current_aws_location, current_latency, proposed_aws_location, proposed_latency`
`GetQueryResults` API オペレーションを実行すると、Internet Monitor はレスポンスで次を返します。
+ クエリが返す結果を含んでいる、文字列配列のデータ。情報は `Fields` フィールドに合わせた配列で返されます。また、API 呼び出しによっても返されます。`Fields` フィールドを使用すると、`Data` リポジトリから情報を解析でき、目的に合わせて、さらに絞り込んだりソートしたりできます。
+ (`Data` フィールドのレスポンスにおいて) クエリがデータを返したフィールドを一覧表示する、フィールドの配列。この配列のそれぞれの項目は、`availability_score` - `float` のように、名前とデータ型がペアになっています。
## トラブルシューティング
クエリインターフェイス API オペレーションを使用したときに、エラーが返される場合は、Internet Monitor を使用するために必要なアクセス許可があることを確認してください。特に、次のアクセス許可があることを確認してください。
```
internetmonitor:StartQuery
internetmonitor:GetQueryStatus
internetmonitor:GetQueryResults
internetmonitor:StopQuery
```
これらのアクセス許可は、コンソールで Internet Monitor ダッシュボードを使用する場合に推奨される、AWS Identity and Access Management ポリシーに含まれています。詳細については、「[Internet Monitor の AWS マネージドポリシー](CloudWatch-IM-permissions.md)」を参照してください。