Nesta página, 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.
Nesta página, não discutimos a linguagem de consulta do Monitoring (MQL) e o método timeSeries.query
. Para ver essas informações, consulte Como usar a MQL da API Monitoring.
Há várias maneiras de usar o método timeSeries.list
:
Para executar o método
list
sem gravar códigos, a API Explorer baseada em formulários é usada nos exemplos das guias PROTOCOLO nesta página. Consulte API Explorer para ver mais informações sobre essa ferramenta.Para saber como usar o método
list
nas linguagens de programação selecionadas, consulte as amostras de códigos executáveis nesta página. Não há suporte para o SDK do Cloud para usar a ferramenta de linha de comandogcloud
para ler dados de métricas.-
Para visualizar as métricas de um recurso monitorado usando o Metrics Explorer, siga estas instruções:
- No Console do Google Cloud, acesse Monitoring ou use o botão
Acessar Monitoring - No painel de navegação do Monitoring, clique em
Metrics Explorer.
- Digite o nome do recurso monitorado na caixa de texto Find resource type and metric.
- No Console do Google Cloud, acesse Monitoring ou use o botão
Para ver uma introdução a métricas e séries temporais, acesse Métricas, séries temporais e recursos.
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.
Forneça o seguinte para especificar quais dados de série temporal 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, consulte Como agregar dados para alguns exemplos.
Filtros da série temporal
Para especificar quais séries temporais você quer recuperar, passe um filtro da série temporal para o método list
. Veja a seguir os componentes de filtro comumente fornecidos:
O filtro precisa especificar um único tipo de métrica. Por exemplo:
metric.type = "compute.googleapis.com/instance/cpu/usage_time"
Para recuperar métricas personalizadas, 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. Por exemplo:
(metric.label.instance_name = "your-instance-id" OR metric.label.instance_name = "your-other-instance-id")
Observe que
label
está correto, embora o objeto de métrica real uselabels
como chave.O filtro pode limitar as séries temporais às que contêm um tipo de recurso monitorado específico:
resource.type = "gae_app"
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 rótulos de métricas, o método list
retornará uma série temporal para cada combinação de valores no(s) rótulo(s) não especificado(s). O método retornará somente séries temporais que tenham dados.
Intervalos de tempo
É necessário especificar interval.startTime e interval.endTime ao chamar o método timeSeries.list
. O período resultante inclui o horário de término, mas não o horário de início, a menos que ambos sejam iguais. Isso pode ser confuso. Por exemplo, considere estes exemplos de intervalos (start, end]
:
(T, T+1]
- Esse intervalo não contém T.
(T-1, T]
- Esse intervalo contém T.
(T, T]
- Sendo um caso especial e incomum, esse intervalo inclui apenas o tempo T. Se você omitir o horário de início, esse será o intervalo recebido.
Valores em intervalos de tempo
Os horários de início e de término precisam ser especificados como strings no formato RFC 3339. Por exemplo:
2018-05-11T12:34:56+04:00 2018-05-11T12:34:56.992Z
O comando date -Iseconds
no Linux é útil para gerar carimbos de data e hora.
Extensão dos intervalos de tempo
Um intervalo de tempo é especificado por um horário de início e término, mas o horário de início não é exigido pela API. Se um horário de início não for especificado, ele será definido por padrão para o horário de término. Isso faz sentido semanticamente apenas para as métricas GAUGE
, que avaliam períodos.
Se a métrica for CUMULATIVE
ou DELTA
, ela avaliará um acúmulo ou alteração ao longo do tempo. Para métricas "ao longo do tempo", é necessário fornecer os horários de início e término do intervalo, e o de início precisa ser anterior ao de término.
Consulte Tipos de métricas para ver mais informações.
Operações básicas de listagem
O método timeSeries.list
pode ser usado para retornar dados brutos simples ou pode ser usado para retornar dados altamente processados. Nesta seção, ilustramos alguns usos básicos.
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
Estes são os parâmetros de amostra para timeSeries.list
:
- name:
projects/[PROJECT_ID]
- filter:
metric.type = "compute.googleapis.com/instance/cpu/utilization"
- interval.start_time:
2018-05-11T00:00:00Z
- interval.end_time:
2018-05-11T00:20:00Z
- fields:
timeSeries.metric
Antes de clicar no botão Executar, altere [PROJECT_ID]
para o código do seu projeto.
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"
},
}
]
}
C#
Go
Java
Node.js
PHP
Python
Ruby
Consulte Solução de problemas de chamadas da API se tiver dificuldade.
Exemplo: como receber dados de série temporal
Neste exemplo, retornamos todas as informações disponíveis para a solicitação timeSeries.list
das instâncias do Compute Engine nos últimos 20 minutos. Isso inclui os dados de métrica.
Protocolo
O exemplo de protocolo limita ainda mais a saída para que os dados retornados sejam mais gerenciáveis na caixa de resposta. São usados valores de campo diferentes neste exemplo:
- O valor de filter agora limita a série temporal a uma única instância de VM.
- O valor de fields agora especifica somente o horário e o valor das medidas.
Isso limita a quantidade de dados de séries temporais retornada no resultado.
Estes são os parâmetros de amostra para timeSeries.list
:
- name:
projects/[PROJECT_ID]
- filter:
metric.type = "compute.googleapis.com/instance/cpu/utilization" AND metric.label.instance_name = "[YOUR_INSTANCE_NAME]"
- interval.start_time:
2018-05-11T00:00:00Z
- interval.end_time:
2018-05-11T00:20:00Z
- fields:
timeSeries.points.interval.endTime,timeSeries.points.value
Antes de clicar no botão Executar, altere [PROJECT_ID]
e [YOUR_INSTANCE_NAME
para os valores no seu projeto. Além disso, defina o horário de término como um momento recente e o de início para 20 minutos antes.
A solicitação retorna um resultado como este:
{
"timeSeries": [
{
"points": [
{
"interval": {
"endTime": "2018-05-T00:19:01Z"
},
"value": {
"doubleValue": 0.06763074536575005
}
},
{
"interval": {
"endTime": "2018-05-11T00:18:01Z"
},
"value": {
"doubleValue": 0.06886174467702706
}
},
...
{
"interval": {
"endTime": "2018-05-11T00:17:01Z"
},
"value": {
"doubleValue": 0.06929610064253211
}
}
]
}
]
}
C#
Go
Java
Node.js
PHP
Python
Ruby
Os dados retornados incluem 20 pontos de dados em cada série temporal durante o período de 20 minutos. Isso porque as métricas do Compute Engine são coletadas a cada minuto. Para mais informações, consulte Retenção e latência dos dados de métricas. 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.
Consulte Solução de problemas de chamadas da API se tiver dificuldade.
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. Consulte a documentação do método para ver mais opções.
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 (600 segundos). Depois, é feita a média dos valores em cada período de 10 minutos.
Neste exemplo, reduzimos as medições por série temporal de 20 para 2. Essa operação tem duas vantagens: uniformiza os dados e alinha os dados de todas as séries temporais em limites exatos de 10 minutos. Os dados podem então ser processados posteriormente.
Protocolo
Estes são os parâmetros de amostra para timeSeries.list
:
- name:
projects/[PROJECT_ID]
- aggregation.alignmentPeriod:
600s
- aggregation.perSeriesAligner:
ALIGN_MEAN
- filter:
metric.type = "compute.googleapis.com/instance/cpu/utilization"
- interval.start_time:
2018-05-11T00:00:00Z
- interval.end_time:
2018-05-11T00:20:00Z
- fields:
timeSeries.metric,timeSeries.points
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.
Antes de clicar no botão Executar, altere [PROJECT_ID]
para o código do seu projeto. Além disso, ajuste o horário de término como um momento recente e o de início para 20 minutos antes.
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": "2018-05-04T14:00:00.000Z",
"endTime": "2018-05-04T14:00:00.000Z"
},
"value": { "doubleValue": 0.06688481346044381 }
},
{
"interval": {
"startTime": "2018-05-04T13:50:00.000Z",
"endTime": "2018-05-04T13:50:00.000Z"
},
"value": {"doubleValue": 0.06786652821310177 }
}
]
},
{
"metric": {
"labels": { "instance_name": "your-second-instance" },
"type": "compute.googleapis.com/instance/cpu/utilization"
},
"points": [
{
"interval": {
"startTime": "2018-05-04T14:00:00.000Z",
"endTime": "2018-05-04T14:00:00.000Z"
},
"value": { "doubleValue": 0.04144239874207415 }
},
{
"interval": {
"startTime": "2018-05-04T13:50:00.000Z",
"endTime": "2018-05-04T13:50:00.000Z"
},
"value": { "doubleValue": 0.04045793689050091 }
}
]
},
{
"metric": {
"labels": { "instance_name": "your-third-instance" },
"type": "compute.googleapis.com/instance/cpu/utilization"
},
"points": [
{
"interval": {
"startTime": "2018-05-04T14:00:00.000Z",
"endTime": "2018-05-04T14:00:00.000Z"
},
"value": { "doubleValue": 0.029650046587339607 }
},
{
"interval": {
"startTime": "2018-05-04T13:50:00.000Z",
"endTime": "2018-05-04T13:50:00.000Z"
},
"value": { "doubleValue": 0.03053874224715402 }
}
]
}
]
}
C#
Go
Java
Node.js
PHP
Python
Ruby
Consulte Solução de problemas de chamadas da API se tiver dificuldade.
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
Veja a seguir os parâmetros de amostra para timeSeries.list
, aggregation.crossSeriesReducer:
- nome:
projects/[PROJECT_ID]
- aggregation.alignmentPeriod:
600s
- aggregation.crossSeriesReducer:
REDUCE_MEAN
- aggregation.perSeriesAligner:
ALIGN_MEAN
- filter:
metric.type = "compute.googleapis.com/instance/cpu/utilization"
- interval.start_time:
2018-05-11T00:00:00Z
- interval.end_time:
2018-05-11T00:20:00Z
- fields:
timeSeries.metric,timeSeries.points
Antes de clicar no botão Executar, altere [PROJECT_ID]
para o código do seu projeto. Além disso, ajuste o horário de término como um momento recente e o de início para 20 minutos antes.
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": "2018-05-04T14:00:00.000Z",
"endTime": "2018-05-04T14:00:00.000Z"
},
"value": {
"doubleValue": 0.045992419596619184
}
},
{
"interval": {
"startTime": "2018-05-04T13:50:00.000Z",
"endTime": "2018-05-04T13:50:00.000Z"
},
"value": {
"doubleValue": 0.04628773578358556
}
}
]
}
]
}
C#
Go
Java
Node.js
PHP
Python
Ruby
Consulte Solução de problemas de chamadas da API se tiver dificuldade.