Este documento explica como ler dados de métricas, também denominados dados de séries cronológicas, através do método timeSeries.list na API Monitoring.
Este documento explica como usar bibliotecas cliente para chamar o método
timeSeries.list.
Vista geral
Cada chamada ao método timeSeries.list pode devolver qualquer número de séries cronológicas de um único tipo de métrica. Por exemplo, se estiver a usar o Compute Engine, o tipo de métrica compute.googleapis.com/instance/cpu/usage_time tem uma série cronológica separada para cada uma das suas instâncias de VM.
Para uma introdução às métricas e às séries cronológicas,
consulte o artigo Métricas, séries cronológicas e recursos.
Especifique os dados de séries cronológicas que quer facultando as seguintes informações ao método timeSeries.list:
- Uma expressão de filtro que especifica o tipo de métrica. Opcionalmente, o filtro seleciona um subconjunto das séries cronológicas da métrica especificando os recursos que produzem as séries cronológicas ou especificando valores para determinadas etiquetas nas séries cronológicas.
- Um intervalo de tempo que limita a quantidade de dados devolvidos.
- Opcionalmente, uma especificação de como combinar várias séries cronológicas para produzir um resumo agregado dos dados. Para mais informações e exemplos, consulte o artigo Agregar dados.
Filtros de intervalos temporais
Especifica os intervalos temporais a obter transmitindo um filtro de intervalos temporais ao método timeSeries.list.
Segue-se uma lista dos componentes de filtro comuns:
O filtro tem de especificar um único tipo de métrica. Por exemplo:
metric.type = "compute.googleapis.com/instance/cpu/usage_time"Para obter métricas definidas pelo utilizador, altere o prefixo metric.type no filtro para
custom.googleapis.comou outro prefixo, se usado;external.googleapis.comé usado com frequência.O filtro pode especificar valores para as etiquetas de dimensões da métrica. O tipo de métrica determina as etiquetas presentes. Por 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 só pode selecionar as séries cronológicas que contêm um tipo de recurso monitorizado específico:
resource.type = "gce_instance"
Os componentes do filtro podem ser combinados num único filtro de série cronológica, 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 não especificar valores para todas as etiquetas de métricas, o método list devolve um intervalo temporal para cada combinação de valores nas etiquetas não especificadas. O método devolve apenas séries cronológicas com dados.
Intervalos de tempo
Quando usa a API para ler dados, especifica o intervalo de tempo para o qual quer obter dados definindo as horas de início e fim.
A API obtém dados do intervalo (start, end], ou seja, do período após a hora de início até à hora de fim.
A hora de início não deve ser posterior à hora de fim. Se especificar uma hora de início posterior à hora de fim, a API devolve um erro.
Se quiser obter apenas dados com uma data/hora específica, defina a hora de início igual à hora de fim ou, equivalentemente, não defina a hora de início.
Formato da hora
As horas de início e fim têm de ser especificadas 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 indicações de tempo.
Operações básicas de listas
O método timeSeries.list pode ser usado para devolver dados simples e não processados ou pode ser usado para devolver dados altamente processados. Esta secção ilustra como listar as séries cronológicas disponíveis e como obter os valores numa série cronológica específica.
Exemplo: listar intervalos temporais disponíveis
Este exemplo mostra como listar apenas os nomes e as descrições das séries cronológicas que correspondem a um filtro, em vez de devolver todos os dados disponíveis:
C#
Para se autenticar no Monitoring, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável GOOGLE_CLOUD_UNIVERSE_DOMAIN environment
como s3nsapis.fr.
Go
Para se autenticar no Monitoring, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável GOOGLE_CLOUD_UNIVERSE_DOMAIN environment
como s3nsapis.fr.
Java
Para se autenticar no Monitoring, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável GOOGLE_CLOUD_UNIVERSE_DOMAIN environment
como s3nsapis.fr.
Node.js
Para se autenticar no Monitoring, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável GOOGLE_CLOUD_UNIVERSE_DOMAIN environment
como s3nsapis.fr.
PHP
Para se autenticar no Monitoring, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável GOOGLE_CLOUD_UNIVERSE_DOMAIN environment
como s3nsapis.fr.
Python
Para se autenticar no Monitoring, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável GOOGLE_CLOUD_UNIVERSE_DOMAIN environment
como s3nsapis.fr.
Ruby
Para se autenticar no Monitoring, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável GOOGLE_CLOUD_UNIVERSE_DOMAIN environment
como s3nsapis.fr.
Se tiver dificuldades, consulte o artigo Resolva problemas da API Monitoring.
Exemplo: obter dados de intervalos temporais
Este exemplo devolve as medições de utilização da CPU que foram registadas durante um intervalo de 20 minutos para uma instância específica do Compute Engine. A quantidade de dados devolvidos depende da taxa de amostragem da métrica. Uma vez que a utilização do CPU é amostrada a cada minuto, os resultados desta consulta são cerca de 20 pontos de dados. Quando são devolvidos vários pontos de dados para uma série cronológica, a API devolve os pontos de dados em cada série cronológica por ordem cronológica inversa. Não existe nenhuma substituição para esta ordenação de pontos.
C#
Para se autenticar no Monitoring, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável GOOGLE_CLOUD_UNIVERSE_DOMAIN environment
como s3nsapis.fr.
Go
Para se autenticar no Monitoring, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável GOOGLE_CLOUD_UNIVERSE_DOMAIN environment
como s3nsapis.fr.
Java
Para se autenticar no Monitoring, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável GOOGLE_CLOUD_UNIVERSE_DOMAIN environment
como s3nsapis.fr.
Node.js
Para se autenticar no Monitoring, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável GOOGLE_CLOUD_UNIVERSE_DOMAIN environment
como s3nsapis.fr.
PHP
Para se autenticar no Monitoring, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável GOOGLE_CLOUD_UNIVERSE_DOMAIN environment
como s3nsapis.fr.
Python
Para se autenticar no Monitoring, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável GOOGLE_CLOUD_UNIVERSE_DOMAIN environment
como s3nsapis.fr.
Ruby
Para se autenticar no Monitoring, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável GOOGLE_CLOUD_UNIVERSE_DOMAIN environment
como s3nsapis.fr.
Se tiver dificuldades, consulte o artigo Resolva problemas da API Monitoring.
Agregação de dados
O método timeSeries.list
pode realizar agregações e reduções estatísticas nos dados de séries cronológicas devolvidos. As secções seguintes demonstram dois exemplos.
Para saber mais, consulte o artigo
Filtragem e agregação: manipular séries cronológicas.
Exemplo: alinhar séries cronológicas
Este exemplo reduz as 20 medições de utilização individuais em cada série temporal a 2 medições: a utilização média para os dois períodos de 10 minutos no intervalo de 20 minutos. Os dados de cada série cronológica são primeiro alinhados em períodos de 10 minutos e, em seguida, é calculada a média dos valores em cada período de 10 minutos.
A operação de alinhamento tem duas vantagens: suaviza os dados e alinha os dados de todos os dados de séries cronológicas em limites exatos de 10 minutos. Em seguida, os dados alinhados podem ser processados mais detalhadamente.
C#
Para se autenticar no Monitoring, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável GOOGLE_CLOUD_UNIVERSE_DOMAIN environment
como s3nsapis.fr.
Go
Para se autenticar no Monitoring, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável GOOGLE_CLOUD_UNIVERSE_DOMAIN environment
como s3nsapis.fr.
Java
Para se autenticar no Monitoring, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável GOOGLE_CLOUD_UNIVERSE_DOMAIN environment
como s3nsapis.fr.
Node.js
Para se autenticar no Monitoring, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável GOOGLE_CLOUD_UNIVERSE_DOMAIN environment
como s3nsapis.fr.
PHP
Para se autenticar no Monitoring, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável GOOGLE_CLOUD_UNIVERSE_DOMAIN environment
como s3nsapis.fr.
Python
Para se autenticar no Monitoring, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável GOOGLE_CLOUD_UNIVERSE_DOMAIN environment
como s3nsapis.fr.
Ruby
Para se autenticar no Monitoring, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável GOOGLE_CLOUD_UNIVERSE_DOMAIN environment
como s3nsapis.fr.
Se tiver dificuldades, consulte o artigo Resolva problemas da API Monitoring.
Exemplo: reduzir em várias séries cronológicas
Este exemplo expande o exemplo anterior combinando as séries cronológicas alinhadas das três instâncias de VM numa única série cronológica que mede a utilização média de todas as instâncias.
C#
Para se autenticar no Monitoring, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável GOOGLE_CLOUD_UNIVERSE_DOMAIN environment
como s3nsapis.fr.
Go
Para se autenticar no Monitoring, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável GOOGLE_CLOUD_UNIVERSE_DOMAIN environment
como s3nsapis.fr.
Java
Para se autenticar no Monitoring, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável GOOGLE_CLOUD_UNIVERSE_DOMAIN environment
como s3nsapis.fr.
Node.js
Para se autenticar no Monitoring, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável GOOGLE_CLOUD_UNIVERSE_DOMAIN environment
como s3nsapis.fr.
PHP
Para se autenticar no Monitoring, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável GOOGLE_CLOUD_UNIVERSE_DOMAIN environment
como s3nsapis.fr.
Python
Para se autenticar no Monitoring, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável GOOGLE_CLOUD_UNIVERSE_DOMAIN environment
como s3nsapis.fr.
Ruby
Para se autenticar no Monitoring, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.
Antes de executar exemplos de código, defina a variável GOOGLE_CLOUD_UNIVERSE_DOMAIN environment
como s3nsapis.fr.
Se tiver dificuldades, consulte o artigo Resolva problemas da API Monitoring.
O que se segue?
- Saiba mais acerca da retenção e da latência dos dados de métricas.
- Saiba mais sobre a filtragem e a agregação: manipular séries cronológicas.