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.
Há várias maneiras de chamar o método timeSeries.list
:
- Use as guias Protocolo nesta página para usar o APIs Explorer baseado em formulários.
- É possível usar uma biblioteca de cliente específica da linguagem.
- Você pode usar o Metrics Explorer.
Outra maneira de ler os dados de métricas é enviar um comando ao método
timeSeries.query
,
que exige a linguagem de consulta do Monitoring (MQL, na sigla em inglês). Este documento não descreve a MQL nem o método timeSeries.query
. Para informações sobre esses
tópicos, consulte
Como recuperar dados com timeSeries.query
.
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:
Protocolo
Abra a página de referência de
timeSeries.list
.No painel Testar este método, insira o seguinte:
-
name: insira o caminho do projeto.
projects/PROJECT_ID
-
filter: especifique o tipo de métrica.
metric.type = "compute.googleapis.com/instance/cpu/utilization"
- interval.endTime: insira o horário de término.
- interval.startTime: insira o horário de início e verifique se ele é 20 minutos antes do horário de término.
Clique em Mostrar parâmetros padrão e, em campos, insira o seguinte:
timeSeries.metric
-
name: insira o caminho do projeto.
Clique em Executar.
O exemplo de saída mostra séries temporais para duas instâncias de VM diferentes:
{
"timeSeries": [
{
"metric": {
"labels": {
"instance_name": "your-first-instance"
},
"type": "compute.googleapis.com/instance/cpu/utilization"
},
},
{
"metric": {
"labels": {
"instance_name": "your-second-instance"
},
"type": "compute.googleapis.com/instance/cpu/utilization"
},
}
]
}
Para visualizar a solicitação como um comando curl
, como uma
solicitação HTTP ou em JavaScript, clique em fullscreen Tela cheia
no APIs Explorer.
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.
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.
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.
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.
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.
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.
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.
Se tiver dificuldade, consulte Solução de problemas da 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.
Protocolo
O exemplo de protocolo limita ainda mais a saída para que os dados retornados sejam mais gerenciáveis na caixa de resposta:
- O valor filter limita a série temporal a uma única instância de VM.
- O valor de fields especifica somente o horário e o valor das medidas.
Essa configuração limita a quantidade de dados de séries temporais retornada no resultado.
Abra a página de referência de
timeSeries.list
.No painel Testar este método, insira o seguinte:
-
name: insira o caminho do projeto.
projects/PROJECT_ID
filter: especifique o tipo de métrica.
metric.type = "compute.googleapis.com/instance/cpu/utilization" AND metric.label.instance_name = "INSTANCE_NAME"
interval.endTime: insira o horário de término.
interval.startTime: insira o horário de início e verifique se ele é 20 minutos antes do horário de término.
Clique em Mostrar parâmetros padrão e, em campos, insira o seguinte:
timeSeries.points.interval.endTime,timeSeries.points.value
-
name: insira o caminho do projeto.
Clique em Executar.
A solicitação retorna um resultado como este:
{
"timeSeries": [
{
"points": [
{
"interval": {
"endTime": "2024-03-01T00:19:01Z"
},
"value": {
"doubleValue": 0.06763074536575005
}
},
{
"interval": {
"endTime": "2024-03-01T00:18:01Z"
},
"value": {
"doubleValue": 0.06886174467702706
}
},
...
{
"interval": {
"endTime": "2024-03-01T00:17:01Z"
},
"value": {
"doubleValue": 0.06929610064253211
}
}
]
}
]
}
Para visualizar a solicitação como um comando curl
, como uma
solicitação HTTP ou em JavaScript, clique em fullscreen Tela cheia
no APIs Explorer.
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.
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.
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.
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.
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.
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.
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.
Se tiver dificuldade, consulte Solução de problemas da 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.
Protocolo
Abra a página de referência de
timeSeries.list
.No painel Testar este método, insira o seguinte:
-
name: insira o caminho do projeto.
projects/PROJECT_ID
-
aggregation.alignmentPeriod: insira
600s
-
aggregation.perSeriesAligner: selecione
ALIGN_MEAN
-
filter: especifique o tipo de métrica.
metric.type = "compute.googleapis.com/instance/cpu/utilization"
- interval.endTime: insira o horário de término.
- interval.startTime: insira o horário de início e verifique se ele é 20 minutos antes do horário de término.
-
Clique em Mostrar parâmetros padrão e, em campos, insira o seguinte:
timeSeries.metric,timeSeries.points
-
name: insira o caminho do projeto.
Clique em Executar.
O filtro de uma única instância mostrado no exemplo anterior foi removido: essa consulta retorna muito menos dados. Portanto, há menos necessidade de restringi-la a uma instância de VM.
O resultado de exemplo a seguir tem uma série temporal para cada uma das três instâncias de VM. Cada série temporal tem dois pontos de dados, que é a utilização média dos períodos de alinhamento de 10 minutos:
{
"timeSeries": [
{
"metric": {
"labels": {"instance_name": "your-first-instance"},
"type": "compute.googleapis.com/instance/cpu/utilization"
},
"points": [
{
"interval": {
"startTime": "2024-03-01T00:20:00.000Z",
"endTime": "2024-03-01T00:20:00.000Z"
},
"value": { "doubleValue": 0.06688481346044381 }
},
{
"interval": {
"startTime": "2024-03-01T00:10:00.000Z",
"endTime": "2024-03-01T00:10:00.000Z"
},
"value": {"doubleValue": 0.06786652821310177 }
}
]
},
{
"metric": {
"labels": { "instance_name": "your-second-instance" },
"type": "compute.googleapis.com/instance/cpu/utilization"
},
"points": [
{
"interval": {
"startTime": "2024-03-01T00:20:00.000Z",
"endTime": "2024-03-01T00:20:00.000Z"
},
"value": { "doubleValue": 0.04144239874207415 }
},
{
"interval": {
"startTime": "2024-03-01T00:10:00.000Z",
"endTime": "2024-03-01T00:10:00.000Z"
},
"value": { "doubleValue": 0.04045793689050091 }
}
]
},
{
"metric": {
"labels": { "instance_name": "your-third-instance" },
"type": "compute.googleapis.com/instance/cpu/utilization"
},
"points": [
{
"interval": {
"startTime": "2024-03-01T00:20:00.000Z",
"endTime": "2024-03-01T00:20:00.000Z"
},
"value": { "doubleValue": 0.029650046587339607 }
},
{
"interval": {
"startTime": "2024-03-01T00:10:00.000Z",
"endTime": "2024-03-01T00:10:00.000Z"
},
"value": { "doubleValue": 0.03053874224715402 }
}
]
}
]
}
Para visualizar a solicitação como um comando curl
, como uma
solicitação HTTP ou em JavaScript, clique em fullscreen Tela cheia
no APIs Explorer.
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.
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.
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.
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.
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.
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.
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.
Se tiver dificuldade, consulte Solução de problemas da 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.
Protocolo
Abra a página de referência de
timeSeries.list
.No painel Testar este método, insira o seguinte:
-
name: insira o caminho do projeto.
projects/PROJECT_ID
-
aggregation.alignmentPeriod: insira
600s
-
aggregation.perSeriesAligner: selecione
ALIGN_MEAN
-
aggregation.crossSeriesReducer: selecione
REDUCE_MEAN
-
filter: especifique o tipo de métrica.
metric.type = "compute.googleapis.com/instance/cpu/utilization"
- interval.endTime: insira o horário de término.
- interval.startTime: insira o horário de início e verifique se ele é 20 minutos antes do horário de término.
-
Clique em Mostrar parâmetros padrão e, em campos, insira o seguinte:
timeSeries.metric,timeSeries.points
-
name: insira o caminho do projeto.
Clique em Executar.
O resultado da amostra a seguir tem apenas uma série temporal e dois pontos de dados. Cada ponto é a média da utilização entre as três instâncias de VM durante o período:
{
"timeSeries": [
{
"metric": {
"type": "compute.googleapis.com/instance/cpu/utilization"
},
"points": [
{
"interval": {
"startTime": "2024-03-01T00:20:00.000Z",
"endTime": "2024-03-01T00:20:00.000Z"
},
"value": {
"doubleValue": 0.045992419596619184
}
},
{
"interval": {
"startTime": "2024-03-01T00:10:00.000Z",
"endTime": "2024-03-01T00:10:00.000Z"
},
"value": {
"doubleValue": 0.04628773578358556
}
}
]
}
]
}
Para visualizar a solicitação como um comando curl
, como uma
solicitação HTTP ou em JavaScript, clique em fullscreen Tela cheia
no APIs Explorer.
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.
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.
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.
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.
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.
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.
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.
Se tiver dificuldade, consulte Solução de problemas da 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.