Este documento explica 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.
- 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
MQL ou 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 uma introdução a métricas e séries temporais,
consulte Métricas, séries temporais e recursos.
Para especificar os dados de série temporal que você quer, informe o seguinte:
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, altere o prefixo metric.type no filter como
custom.googleapis.com
ou 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,
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
podem ser usadas para retornar dados altamente processados. Esta seção ilustra
como listar as série temporal disponíveis e como conseguir 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:
Protocolo
Abra a página de referência do
timeSeries.list
.No painel Try this method, digite o seguinte:
-
name: insira o caminho para seu 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 anterior ao horário de término.
Clique em Mostrar parâmetros padrão e, nos campos, insira o valor o seguinte:
timeSeries.metric
-
name: insira o caminho para seu 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 Resolver problemas da 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, 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 na ordem inversa. Essa ordem de pontos não causa modificações.
Protocolo
O exemplo de protocolo limita ainda mais a saída, para tornar dados mais gerenciáveis na caixa de resposta:
- O valor de filter limita a série temporal a uma única instância de VM.
- O valor de fields especifica apenas o horário e o valor das medições.
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 Try this method, digite o seguinte:
-
name: insira o caminho para seu 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 anterior ao horário de término.
Clique em Mostrar parâmetros padrão e, nos campos, insira o valor o seguinte:
timeSeries.points.interval.endTime,timeSeries.points.value
-
name: insira o caminho para seu 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 um
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 Resolva 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 suaviza os dados e alinha os dados de todas as séries temporais em limites exatos de 10 minutos. Os dados alinhados podem então ser processados ainda mais.
Protocolo
Abra a página de referência de
timeSeries.list
.No painel Try this method, digite o seguinte:
-
name: insira o caminho para seu 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 anterior ao horário de término.
-
Clique em Mostrar parâmetros padrão e, nos campos, insira o valor
o seguinte:
timeSeries.metric,timeSeries.points
-
name: insira o caminho para seu 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 Resolver 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 do
timeSeries.list
.No painel Try this method, digite o seguinte:
-
name: insira o caminho para seu 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 anterior ao horário de término.
-
Clique em Mostrar parâmetros padrão e, nos campos, insira o valor
o seguinte:
timeSeries.metric,timeSeries.points
-
name: insira o caminho para seu 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 um
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 Resolver 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.