# Usar a interface de consulta do Monitor de Internet Uma opção para saber mais sobre o tráfego da internet para a aplicação da AWS é usar a *interface de consulta* do Monitor de Internet. Para usar a interface de consulta, você cria uma consulta com filtros de dados escolhidos por você e, em seguida, executa a consulta para retornar um subconjunto dos dados do Monitor de Internet. A exploração dos dados que a consulta retorna pode fornecer insights sobre a performance da sua aplicação na Internet. Você pode consultar e explorar todas as métricas que o Monitor de Internet captura com seu monitor, incluindo pontuações de disponibilidade e performance, bytes transferidos, tempos de ida e volta e tempo até o primeiro byte (TTFB). O Monitor de Internet usa a interface de consulta para fornecer os dados que podem ser explorados no painel do console do Monitor de Internet. Ao usar as opções de pesquisa no painel, na página **Analisar** ou na página **Otimizar**, você pode consultar e filtrar dados da Internet para sua aplicação. Se você quiser mais flexibilidade para explorar e filtrar seus dados do que o painel oferece, você pode usar a interface de consulta por conta própria, usando as operações da API do Monitor de Internet com a AWS Command Line Interface ou com um SDK da AWS. Esta seção apresenta os tipos de consultas que podem ser usados com a interface de consulta e os filtros que podem ser especificados para criar um subconjunto de dados, a fim de obter insights sobre o tráfego da Internet para a sua aplicação. **Topics** + [Como usar a interface de consulta](#CloudWatch-IM-view-cw-tools-cwim-query-use-query) + [Exemplos de consulta](#CloudWatch-IM-view-cw-tools-cwim-query-example-queries) + [Obter resultados da consulta](#CloudWatch-IM-view-cw-tools-cwim-query-get-data) + [Solução de problemas](#CloudWatch-IM-view-cw-tools-cwim-query-troubleshooting) ## Como usar a interface de consulta Você cria uma consulta com a interface de consulta ao escolher um *tipo de consulta* e, em seguida, especificar valores de filtro para retornar um subconjunto específico desejado dos dados do arquivo de log. Em seguida, você pode trabalhar com o subconjunto de dados para filtrar e classificar mais detalhadamente, criar relatórios e assim por diante. O processo de consulta funciona da seguinte forma: 1. Quando você executa uma consulta, o Monitor de Internet retorna um `query ID` que é exclusivo da consulta. Esta seção descreve os tipos de consulta disponíveis e as opções de filtragem de dados nas consultas. Para entender como isso funciona, consulte também a seção sobre [exemplos de consultas](#IMQueryInterfaceExamples). 1. Você especifica o ID da consulta com o nome do monitor com a operação da API [GetQueryResults](https://docs.aws.amazon.com/internet-monitor/latest/api/API_GetQueryResults.html) para retornar os resultados dos dados da consulta. Cada tipo de consulta retorna um conjunto diferente de campos de dados. Para saber mais, consulte [Como obter resultados de consulta](#IMGetQueryData). A interface de consulta fornece os tipos de consulta apresentados a seguir. Cada tipo de consulta retorna um conjunto diferente de informações sobre seu tráfego a partir dos arquivos de log, conforme mostrado. + **Medições:** fornece pontuação de disponibilidade, pontuação de performance, tráfego total e tempos de ida e volta, em intervalos de cinco minutos. + **Principais localizações:** fornece pontuação de disponibilidade, pontuação de performance, tráfego total e informações de tempo até o primeiro byte (TTFB) para as principais combinações de localização e ASN que estão sendo monitorados, por volume de tráfego. + **Detalhes das principais localizações:** fornece o TTFB para o Amazon CloudFront, sua configuração atual e a configuração do Amazon EC2 com melhor performance, em intervalos de uma hora. + **Sugestões gerais de tráfego:** fornece TTFB, usando uma média ponderada de 30 dias, para todo o tráfego em cada local monitorado da AWS. + **Detalhes gerais das sugestões de tráfego:** fornece TTFB, usando uma média ponderada de 30 dias, para cada local principal, para um local proposto da AWS. + **Sugestões de roteamento:** disponibiliza o tempo de ida e volta (RTT) médio estimado de um prefixo de IP para uma localidade da AWS, com base em um resolvedor de DNS. O RTT é calculado em intervalos de uma hora, durante um período de uma hora. É possível filtrar os dados com mais precisão ao usar critérios específicos. Com a maioria dos tipos de consulta, exceto as sugestões de roteamento, você pode realizar a filtragem ao especificar um ou mais dos seguintes critérios: + **Localidade da AWS:** para a localidade da AWS, você pode especificar CloudFront ou uma Região da AWS, como `us-east-2`. + **ASN:** especifique o número de sistema autônomo (ASN) de um resolvedor de DNS (geralmente, um ISP), por exemplo, 4225. + **Localização do cliente:** para a localização, especifique uma cidade, metro, subdivisão ou país. + **Local proposto da AWS:** especifique uma Região da AWS, como `us-east-2`, ou uma Zona local da AWS. Esse filtro pode ser usado com o tipo de consulta de detalhes das sugestões gerais de tráfego. + **Geo:** especifique a `geo` para algumas consultas. Isso é necessário para as consultas que usam o tipo de consulta `Top locations`, mas não é permitido para outros tipos de consulta. Para saber quando especificar o `geo` para os parâmetros de filtro, consulte a seção de [exemplos de consulta](#IMQueryInterfaceExamples). Para o tipo de consulta de sugestões de roteamento, você pode realizar a filtragem mais aprofundada dos dados ao especificar um ou mais dos seguintes critérios: + **Localidade da AWS atual:** especifique uma Região da AWS, como `us-east-2`. + **Local proposto da AWS:** especifique uma Região da AWS, como `us-east-2`, ou uma Zona local da AWS. + **Prefixo IPv4:** especifique um prefixo IPv4 no formato padrão, que é semelhante a `192.0.2.0/24`. + **ARN do monitor:** especifique o ARN de um monitor específico. + **IP do resolvedor de DNS:** especifique o endereço IP de um resolvedor de DNS. + **ISP do resolvedor de DNS:** especifique o nome de um resolvedor de DNS (geralmente, um ISP), por exemplo, `Cloudflare`. + **ASN do resolvedor de DNS:** especifique o número de sistema autônomo (ASN) de um resolvedor de DNS, por exemplo, 4225. Os operadores que você pode usar para filtrar seus dados são `EQUALS` e `NOT_EQUALS`. Para obter detalhes sobre os parâmetros de filtragem, consulte a operação da API [FilterParameter](https://docs.aws.amazon.com/internet-monitor/latest/api/API_FilterParameter.html). Para ver detalhes sobre as operações da interface de consulta, consulte as seguintes operações de API no Guia de referência de APIs do Monitor de Internet: + Para criar e executar uma consulta, consulte a operação da API [StartQuery](https://docs.aws.amazon.com/internet-monitor/latest/api/API_StartQuery.html). + Para interromper uma consulta, consulte a operação da API [StopQuery](https://docs.aws.amazon.com/internet-monitor/latest/api/API_StopQuery.html). + Para retornar dados de uma consulta que você criou, consulte a operação da API [GetQueryResults](https://docs.aws.amazon.com/internet-monitor/latest/api/API_GetQueryResults.html). + Para recuperar o status de uma consulta, consulte a operação da API [GetQueryStatus](https://docs.aws.amazon.com/internet-monitor/latest/api/API_GetQueryStatus.html). ## Exemplos de consulta Para criar uma consulta que você possa usar para recuperar um conjunto filtrado de dados do arquivo de log do seu monitor, use a operação da API [StartQuery](https://docs.aws.amazon.com/internet-monitor/latest/api/API_StartQuery.html). Você especifica um tipo de consulta e parâmetros de filtro para a consulta. Então, quando você usar a operação da API da interface de consulta do Monitor de Internet para obter os resultados da consulta usando a consulta, ela recuperará o subconjunto dos dados com os quais você deseja trabalhar. Para ilustrar como funcionam os tipos de consulta e os parâmetros de filtro, vamos dar uma olhada em alguns exemplos. **Exemplo 1** Digamos que você queira recuperar todos os dados do arquivo de log do seu monitor para um país específico, exceto para uma cidade. O exemplo a seguir mostra os parâmetros de filtro para uma consulta que você poderia criar com a operação `StartQuery` para esse cenário. ``` { 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"] }, ] } ``` **Exemplo 2** Como outro exemplo, digamos que você queira ver suas principais localizações por área metropolitana. Você pode usar o exemplo de consulta a seguir para esse cenário. ``` { MonitorName: "TestMonitor" StartTime: "2023-07-12T20:00:00Z" EndTime: "2023-07-12T21:00:00Z" QueryType: "TOP_LOCATIONS" FilterParameters: [ { Field: "geo", Operator: "EQUALS", Values: ["metro"] }, ] } ``` **Exemplo 3** Agora, digamos que você queira ver as principais combinações de cidade-rede na área metropolitana de Los Angeles. Para fazer isso, especifique `geo=city`, e depois defina `metro` como Los Angeles. Agora, a consulta retorna as principais cidades-redes na área metropolitana de Los Angeles em vez das principais metro\+redes em geral. Aqui está o exemplo de consulta que você pode usar: ``` { 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"] } ] } ``` **Exemplo 4** Em seguida, digamos que você queira recuperar dados de TTFB para uma subdivisão específica (p. ex., um estado dos EUA). A seguir, um exemplo de consulta para esse cenário: ``` { 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"] }, ] } ``` **Exemplo 5** Agora, digamos que você queira recuperar dados de TTFB para cada local em que sua aplicação tenha tráfego de clientes. A seguir, um exemplo de consulta para esse cenário: ``` { 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], ... ``` **Exemplo 6** Suponhamos que você deseje recuperar dados de TTFB para uma nova Região da AWS específica. A seguir, um exemplo de consulta para esse cenário: ``` { 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] ``` **Exemplo 7** Um exemplo final corresponde à recuperação de dados para resolvedores de DNS específicos. A seguir, um exemplo de consulta para esse cenário: ``` { 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] ``` ## Obter resultados da consulta Depois de definir uma consulta, você pode retornar um conjunto de resultados com a consulta executando outra operação da API do Monitor de Internet, [GetQueryResults](https://docs.aws.amazon.com/internet-monitor/latest/api/API_GetQueryResults.html). Ao executar `GetQueryResults`, você especifica o ID da consulta que você definiu, juntamente com o nome do seu monitor. `GetQueryResults` recupera os dados da consulta especificada em um conjunto de resultados. Quando você executar uma consulta, certifique-se de que a consulta tenha sido concluída antes de usar `GetQueryResults` para visualizar os resultados. Você pode determinar se a consulta foi concluída usando a operação da API [GetQueryStatus](https://docs.aws.amazon.com/internet-monitor/latest/api/API_GetQueryStatus.html). Quando o `Status` da consulta for de `SUCCEEDED`, você pode prosseguir com a análise dos resultados. Quando a consulta for concluída, você poderá usar as seguintes informações como auxílio para a análise dos resultados. Cada tipo de consulta que você usa para criar uma consulta inclui um conjunto exclusivo de campos de dados dos arquivos de log, conforme descrito na lista a seguir: **Medições** O tipo de consulta `measurements` retorna os seguintes dados: `timestamp, availability, performance, bytes_in, bytes_out, rtt_p50, rtt_p90, rtt_p95` **Principais localizações** O tipo de consulta `top locations` agrupa os dados por localização e fornece a média dos dados ao longo do período. Os dados que esse tipo de consulta retorna incluem o seguinte: `aws_location, city, metro, subdivision, country, asn, availability, performance, bytes_in, bytes_out, current_fbl, best_ec2, best_ec2_region, best_cf_fbl` Observe que `city`, `metro`, e `subdivision` só serão retornados se você escolher esse tipo de localização para o campo `geo`. Os seguintes campos de localização são retornados, dependendo do tipo de localização que você especificar para `geo`: ``` city = city, metro, subdivision, country metro = metro, subdivision, country subdivision = subdivision, country country = country ``` **Detalhes das principais localizações** O tipo de consulta `top locations details` retorna dados agrupados hora a hora. A consulta retorna os seguintes dados: `timestamp, current_service, current_fbl, best_ec2_fbl, best_ec2_region, best_cf_fbl` **Sugestões gerais de tráfego** O tipo de consulta `overall traffic suggestions` retorna dados agrupados hora a hora. A consulta retorna os seguintes dados: `current_aws_location, proposed_aws_location, average_fbl, traffic, optimized_traffic_excluding_cf, optimized_traffic_including_cf` **Detalhes das sugestões gerais de tráfego** O tipo de consulta `overall traffic suggestions details` retorna dados agrupados hora a hora. A consulta retorna os seguintes dados: `aws_location, city, metro, subdivision, country, asn, traffic, current_aws_location, fbl_data` **Sugestões de roteamento** O tipo de consulta `routing suggestions` retorna dados agrupados hora a hora. A consulta retorna os seguintes dados: `dns_resolver_ip, dns_resolver_asn, dns_resolver_isp, ipv4_prefixes, current_aws_location, current_latency, proposed_aws_location, proposed_latency` Quando você executa a operação da API `GetQueryResults`, o Monitor de Internet retorna o seguinte na resposta: + Uma *matriz de cadeia de dados* que contém os resultados que a consulta retorna. As informações são retornadas em matrizes alinhadas com o campo `Fields`, também retornadas pela chamada da API. Usando o campo `Fields`, você pode analisar as informações do repositório `Data` e, em seguida, filtrá-las ou classificá-las para seus objetivos. + Uma *matriz de campos* que lista os campos para os quais a consulta retornou dados (na resposta do campo `Data`). Cada item na matriz é um par nome-tipo de dados, como `availability_score`-`float`. ## Solução de problemas Caso sejam retornados erros quando você usar as operações da API da interface de consulta, verifique se você tem as permissões necessárias para usar o Monitor de Internet. Especificamente, certifique-se de que você tenha as seguintes permissões: ``` internetmonitor:StartQuery internetmonitor:GetQueryStatus internetmonitor:GetQueryResults internetmonitor:StopQuery ``` Essas permissões estão incluídas na política do AWS Identity and Access Management recomendada para usar o painel do Monitor de Internet no console. Para obter mais informações, consulte [Políticas gerenciadas pela AWS do Monitor de Internet](CloudWatch-IM-permissions.md).