O método timeSeries.list na
API Monitoring permite recuperar, filtrar e agregar dados de séries temporais brutos ou
processados em um intervalo de tempo especificado. É possível invocar
timeSeries.list usando uma biblioteca de cliente específica da linguagem.
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 uma introdução às métricas e série temporal,
consulte Métricas, série temporal e recursos.
Para especificar os dados de série temporal que você quer, forneça as seguintes informações ao método timeSeries.list:
- 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, mude o prefixo
metric.typeno filtro paracustom.googleapis.comou outro prefixo, se usado.external.googleapis.comé usado 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,
labelestá correto mesmo que o objeto de métrica real uselabelscomo 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 o seguinte:
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 ou
altamente processados. Nesta seção, mostramos
como listar as séries temporais disponíveis e como receber os valores
em 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 os 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 os 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 os 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 os 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 os 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 os 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 os exemplos de código, defina a variável de ambiente GOOGLE_CLOUD_UNIVERSE_DOMAIN como s3nsapis.fr.
Se tiver dificuldades, 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 que foram 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, o resultado dessa consulta é de 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 cronológica inversa. Não há substituição para essa ordenação de pontos.
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 os 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 os 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 os 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 os 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 os 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 os 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 os exemplos de código, defina a variável de ambiente GOOGLE_CLOUD_UNIVERSE_DOMAIN como s3nsapis.fr.
Se tiver dificuldades, consulte Resolver problemas na API Monitoring.
Agregação de dados
O método timeSeries.list
pode realizar agregações e reduções estatísticas nos dados de série temporal
retornados. As seções a seguir mostram 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 suaviza os dados e os alinha de todas as série temporal 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 os 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 os 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 os 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 os 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 os 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 os 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 os exemplos de código, defina a variável de ambiente GOOGLE_CLOUD_UNIVERSE_DOMAIN como s3nsapis.fr.
Se tiver dificuldades, 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 os 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 os 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 os 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 os 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 os 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 os 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 os exemplos de código, defina a variável de ambiente GOOGLE_CLOUD_UNIVERSE_DOMAIN como s3nsapis.fr.
Se tiver dificuldades, consulte Resolver problemas na API Monitoring.
A seguir
- Saiba mais sobre retenção e latência de dados de métricas.
- Aprenda mais sobre filtragem e agregação: como manipular séries temporais.