Neste documento, explicamos como ler dados de métricas, também chamados de dados de série temporal,
usando o método timeSeries.list
na
API Monitoring.
Este documento explica como usar bibliotecas de cliente para chamar o método
timeSeries.list
.
Visão geral
Cada chamada do método timeSeries.list
pode retornar qualquer número de séries temporais de um único tipo de métrica. Por exemplo, se você estiver usando o Compute Engine, o tipo de métrica compute.googleapis.com/instance/cpu/usage_time
terá uma série temporal separada para cada uma de suas instâncias de VM.
Para ver uma introdução a métricas e série temporal, acesse Métricas, série temporal e recursos.
Forneça as seguintes informações ao método timeSeries.list
para especificar os dados de série temporal que você quer:
- Uma expressão de filtro que especifica o tipo de métrica. Como opção, o filtro seleciona um subconjunto da série temporal da métrica, especificando os recursos que produzem a série temporal ou os valores para determinados rótulos na série temporal.
- Um intervalo de tempo que limita a quantidade de dados retornados.
- Como opção, uma especificação de como combinar várias séries temporais para produzir um resumo agregado dos dados. Para mais informações e exemplos, consulte Como agregar dados.
Filtros da série temporal
Para especificar quais séries temporais você quer recuperar, transmita um
filtro da série temporal para o
método timeSeries.list
.
Veja a seguir os componentes de filtro comuns:
O filtro precisa especificar um único tipo de métrica. Exemplo:
metric.type = "compute.googleapis.com/instance/cpu/usage_time"
Para recuperar métricas definidas pelo usuário, altere o prefixo metric.type no campo filtrar para
custom.googleapis.com
ou outro prefixo, se usado.external.googleapis.com
é utilizado com frequência.O filtro pode especificar valores para os rótulos de dimensão da métrica. O tipo de métrica determina quais rótulos estão presentes. Exemplo:
(metric.label.instance_name = "your-instance-id" OR metric.label.instance_name = "your-other-instance-id")
Na expressão anterior,
label
está correto mesmo que o objeto de métrica real uselabels
como chave.O filtro pode selecionar apenas as séries temporais que contêm um tipo de recurso monitorado específico:
resource.type = "gce_instance"
Os componentes do filtro podem ser combinados em um único filtro de série temporal, como a seguir:
metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND
(metric.label.instance_name = "your-instance-id" OR
metric.label.instance_name = "your-other-instance-id")
Se você não especificar valores para todos os identificadores de métricas, o método list
retornará uma série temporal para cada combinação de valores nos identificadores
não especificados. O método retornará somente séries temporais que tenham dados.
Intervalos de tempo
Ao usar a API para ler dados, especifique os intervalos de tempo
para os quais você quer recuperar dados definindo os horários de início e término.
A API recupera dados do intervalo (start, end]
, ou seja,
após o horário de início até o horário de término.
O horário de início não pode ser posterior ao horário de término. Se você especificar um horário de início posterior ao horário de término, a API retornará um erro.
Se você quiser recuperar somente os dados com um carimbo de data/hora específico, defina o horário de início igual ao horário de término. Ou então, não defina o horário de início.
Formato de hora
Os horários de início e de término precisam ser especificados como strings no formato RFC 3339. Por exemplo:
2024-03-01T12:34:56+04:00 2024-03-01T12:34:56.992Z
O comando date -Iseconds
no Linux é útil para gerar carimbos de data e hora.
Operações básicas de listagem
O método timeSeries.list
pode ser usado para
retornar dados brutos simples ou
dados altamente processados. Esta seção ilustra como listar as séries temporais disponíveis e como extrair os valores de uma série temporal específica.
Exemplo: como listar séries temporais disponíveis
Neste exemplo, mostramos como listar apenas os nomes e as descrições da série temporal que correspondem a um filtro, em vez de retornar todos os dados disponíveis:
C#
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável de ambiente GOOGLE_CLOUD_UNIVERSE_DOMAIN
como s3nsapis.fr
.
Go
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável de ambiente GOOGLE_CLOUD_UNIVERSE_DOMAIN
como s3nsapis.fr
.
Java
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável de ambiente GOOGLE_CLOUD_UNIVERSE_DOMAIN
como s3nsapis.fr
.
Node.js
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável de ambiente GOOGLE_CLOUD_UNIVERSE_DOMAIN
como s3nsapis.fr
.
PHP
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável de ambiente GOOGLE_CLOUD_UNIVERSE_DOMAIN
como s3nsapis.fr
.
Python
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável de ambiente GOOGLE_CLOUD_UNIVERSE_DOMAIN
como s3nsapis.fr
.
Ruby
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável de ambiente GOOGLE_CLOUD_UNIVERSE_DOMAIN
como s3nsapis.fr
.
Se tiver dificuldade, consulte Resolver problemas na API Monitoring.
Exemplo: como receber dados de série temporal
Este exemplo retorna as medições de utilização da CPU registradas em um intervalo de 20 minutos para uma instância específica do Compute Engine. A quantidade de dados retornados depende da taxa de amostragem da métrica. Como a utilização da CPU é amostrada a cada minuto, os resultados dessa consulta são cerca de 20 pontos de dados. Quando vários pontos de dados são retornados para uma série temporal, a API retorna os pontos de dados em cada série temporal em ordem de tempo inversa. Essa ordem de pontos não causa modificações.
C#
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável de ambiente GOOGLE_CLOUD_UNIVERSE_DOMAIN
como s3nsapis.fr
.
Go
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável de ambiente GOOGLE_CLOUD_UNIVERSE_DOMAIN
como s3nsapis.fr
.
Java
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável de ambiente GOOGLE_CLOUD_UNIVERSE_DOMAIN
como s3nsapis.fr
.
Node.js
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável de ambiente GOOGLE_CLOUD_UNIVERSE_DOMAIN
como s3nsapis.fr
.
PHP
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável de ambiente GOOGLE_CLOUD_UNIVERSE_DOMAIN
como s3nsapis.fr
.
Python
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável de ambiente GOOGLE_CLOUD_UNIVERSE_DOMAIN
como s3nsapis.fr
.
Ruby
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável de ambiente GOOGLE_CLOUD_UNIVERSE_DOMAIN
como s3nsapis.fr
.
Se tiver dificuldade, consulte Resolver problemas na API Monitoring.
Como agregar dados
O método timeSeries.list
pode realizar agregações estatísticas e reduções nos dados de série temporal retornados. As seções a seguir demonstram dois exemplos.
Para saber mais, consulte
Filtragem e agregação: como manipular séries temporais.
Exemplo: como alinhar séries temporais
Neste exemplo, reduzimos as 20 medições de utilização individual em cada série temporal para apenas duas medições: a utilização média dos dois períodos de 10 minutos dentro do intervalo de 20 minutos. Os dados de cada série temporal são alinhados em períodos de 10 minutos. Depois, é feita a média dos valores em cada período de 10 minutos.
A operação de alinhamento tem duas vantagens: ela uniformiza os dados e alinha os dados de todas as séries temporais em limites exatos de 10 minutos. Os dados alinhados podem ser processados posteriormente.
C#
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável de ambiente GOOGLE_CLOUD_UNIVERSE_DOMAIN
como s3nsapis.fr
.
Go
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável de ambiente GOOGLE_CLOUD_UNIVERSE_DOMAIN
como s3nsapis.fr
.
Java
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável de ambiente GOOGLE_CLOUD_UNIVERSE_DOMAIN
como s3nsapis.fr
.
Node.js
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável de ambiente GOOGLE_CLOUD_UNIVERSE_DOMAIN
como s3nsapis.fr
.
PHP
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável de ambiente GOOGLE_CLOUD_UNIVERSE_DOMAIN
como s3nsapis.fr
.
Python
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável de ambiente GOOGLE_CLOUD_UNIVERSE_DOMAIN
como s3nsapis.fr
.
Ruby
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável de ambiente GOOGLE_CLOUD_UNIVERSE_DOMAIN
como s3nsapis.fr
.
Se tiver dificuldade, consulte Resolver problemas na API Monitoring.
Exemplo: como fazer a redução em séries temporais
Este exemplo é uma extensão do anterior. Ele combina a série temporal alinhada das três instâncias de VM em uma única série temporal que tem a utilização média de todas as instâncias.
C#
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável de ambiente GOOGLE_CLOUD_UNIVERSE_DOMAIN
como s3nsapis.fr
.
Go
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável de ambiente GOOGLE_CLOUD_UNIVERSE_DOMAIN
como s3nsapis.fr
.
Java
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável de ambiente GOOGLE_CLOUD_UNIVERSE_DOMAIN
como s3nsapis.fr
.
Node.js
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável de ambiente GOOGLE_CLOUD_UNIVERSE_DOMAIN
como s3nsapis.fr
.
PHP
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável de ambiente GOOGLE_CLOUD_UNIVERSE_DOMAIN
como s3nsapis.fr
.
Python
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável de ambiente GOOGLE_CLOUD_UNIVERSE_DOMAIN
como s3nsapis.fr
.
Ruby
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável de ambiente GOOGLE_CLOUD_UNIVERSE_DOMAIN
como s3nsapis.fr
.
Se tiver dificuldade, consulte Resolver problemas na API Monitoring.
A seguir
- Saiba mais sobre retenção e latência de dados de métricas.
- Saiba mais sobre Filtragem e agregação: como manipular séries temporais.