Estrutura de séries temporais

A API Cloud Monitoring representa o modelo de métrica do Cloud Monitoring usando TimeSeries, Metric, MonitoredResource e objetos descritores. Entender essa estrutura ajuda você a usar a API Monitoring diretamente, criar métricas personalizadas e integrar fontes externas, como o OpenTelemetry, cujos dados são mapeados para o mesmo modelo. Se você interage com o Monitoring principalmente pelo console do Google Cloud , provavelmente não precisa desse nível de detalhe.

Antes de ler este documento, conheça as Métricas, série temporal e recursos e os Componentes do modelo de métrica. Para mais informações sobre como coletar suas próprias métricas, consulte Visão geral das métricas definidas pelo usuário.

Revisão do modelo de métrica

Um pré-requisito para entender a estrutura da série temporal é a familiaridade com o modelo de métrica usado pelo Cloud Monitoring. Esse modelo é descrito em Métricas, séries temporais e recursos. Esta seção oferece uma breve revisão.

Em termos gerais, os dados de monitoramento são registrados em séries temporais. Cada série temporal inclui três informações relevantes para essa discussão:

  • Um conjunto de pontos de dados com carimbo de data/hora.
  • Uma referência ao tipo de métrica que informa como interpretar os pontos de dados.
  • Uma referência ao recurso monitorado de origem dos dados.
Time series:

    Points: [(value1, time1), (value2, time2), ...]
    Metric type information: integer? incremental?
    Monitored resource: project? location? method?

Cada série temporal contém as medidas de uma única origem física ou lógica. Se o ambiente tiver centenas de recursos, cada um contribuirá com pelo menos uma série temporal. Na verdade, se o tipo de métrica e o tipo de recurso monitorado tiverem rótulos, você receberá uma série temporal por combinação de valores de rótulos. Consulte Cardinalidade para mais informações.

Uma amostra de série temporal

Uma série temporal é representada como uma instância de um objeto TimeSeries. Confira a seguir uma instância completa de uma única série temporal:

    {
      "metric": {
        "labels": {
          "log": "kubelet",
          "severity": "DEFAULT"
        },
        "type": "logging.googleapis.com/log_entry_count"
      },
      "resource": {
        "type": "gce_instance",
        "labels": {
          "instance_id": "5106847938295940291",
          "zone": "us-central1-a",
          "project_id": "a-gcp-project"
        }
      },
      "metricKind": "DELTA",
      "valueType": "INT64",
      "points": [
        {
          "interval": {
            "startTime": "2019-12-20T20:25:38Z",
            "endTime": "2019-12-20T20:26:38Z"
          },
          "value": {
            "int64Value": "20"
          }
        }
      ]
    }

A maioria das séries temporais inclui vários outros pontos de dados, mas este abrange um intervalo de um minuto. Todas as séries temporais têm a mesma estrutura, com os seguintes campos:

  • O campo metric registra:

    • Os valores de métrica-rótulo para essa série temporal específica, representando uma combinação de valores de rótulo.
    • O tipo de métrica a que os dados estão associados. O tipo de métrica especifica os rótulos disponíveis e descreve o que os pontos de dados representam.

    As informações neste campo são descritas em mais detalhes em Métricas.

  • O campo resource registra:

    • os valores de rótulo de recurso para essa série temporal específica, representando uma combinação de valores de rótulo;
    • O recurso monitorado específico de onde os dados foram coletados.

    As informações nesse campo são descritas em mais detalhes em Objetos de recursos monitorados.

  • Os campos metricKind e valueType mostram como interpretar os valores. Para mais informações, consulte Tipos de valor e de métricas.

  • O campo points é uma matriz de valores com carimbo de data/hora. O tipo de métrica informa o que os valores representam. A série temporal de amostra tem uma matriz com um único ponto de dados. Na maioria das séries temporais, a matriz tem vários outros valores.

Para ver um exemplo ativo que recupera dados de série temporal, consulte Série temporal: dados de um recurso monitorado.

O restante desta página analisa as informações nos campos metric e resource em mais detalhes.

Recursos monitorados

O Cloud Monitoring coleta dados de recursos monitorados e os registra em séries temporais. Cada série temporal criada inclui uma descrição do recurso monitorado de onde os dados foram coletados.

Objetos de recursos monitorados

Um recurso monitorado é representado por uma instância de um objeto MonitoredResource. O recurso monitorado descreve a origem dos valores em uma série temporal. O objeto MonitoredResource é incorporado à série temporal e identifica uma instância específica de um tipo de recurso monitorado conhecido pelo Monitoring: ele aponta para uma entidade física ou lógica.

Por exemplo, veja um objeto de recurso monitorado que descreve uma instância específica do Compute Engine, extraída da série temporal de amostra:

      "resource": {
        "type": "gce_instance",
        "labels": {
          "instance_id": "5106847938295940291",
          "zone": "us-central1-a",
          "project_id": "a-gcp-project"
        }
      }

Essa instância de um recurso monitorado é do tipo gce_instance e tem um valor instance_id específico (5106847938295940291) no projeto a-gcp-project. A instância está localizada nos EUA. Outra série temporal pode se originar de uma instância diferente desse recurso monitorado. Cada combinação de valores de rótulo identifica um recurso exclusivo de onde os dados são coletados.

Diferentes conjuntos de rótulos fazem sentido para diferentes recursos. O conjunto de rótulos de um recurso é determinado pelo descritor de recurso monitorado para esse tipo.

Descritores de recursos monitorados

As informações sobre um tipo de recurso monitorado são mantidas em uma estrutura de dados chamada descritor de recurso monitorado. Para uma definição dessa estrutura de dados, consulte MonitoredResourceDescriptor.

Um descritor de recurso monitorado é como um esquema ou uma especificação de uma estrutura de registros. Ele não inclui os dados sobre uma instância específica do recurso monitorado, mas informa como descrever um recurso monitorado de um tipo específico. Por exemplo, veja o descritor de recurso monitorado para o recurso gce_instance:

{
  "type": "gce_instance",
  "displayName": "VM Instance",
  "description": "A virtual machine instance hosted in Compute Engine.",
  "name": "projects/[PROJECT_ID]/monitoredResourceDescriptors/gce_instance",
  "labels": [
    {
      "key": "project_id",
      "description": "The identifier of the GCP project associated with this resource, such as \"my-project\"."
    },
    {
      "key": "instance_id",
      "description": "The numeric VM instance identifier assigned by Compute Engine."
    },
    {
      "key": "zone",
      "description": "The Compute Engine zone in which the VM is running."
    }
  ]
}

Compare esse descritor de recurso monitorado com a instância específica de um recurso gce_instance mostrado em Objetos de recurso monitorado. Esse descritor não descreve um recurso monitorado específico. Em vez disso, o descritor especifica os rótulos e cada combinação de valores de rótulo identifica um recurso monitorado específico.

É possível recuperar os descritores de recursos monitorados no projeto do Google Cloud usando a API Cloud Monitoring. Por exemplo, consulte as páginas de referência dos métodos monitoredResourceDescriptors.list e monitoredResourceDescriptors.get.

Exemplo ao vivo:se você tiver um projeto do Google Cloud , poderá recuperar esse descritor usando o widget APIs Explorer da seguinte maneira:

  1. Abra a página de referência monitoredResourceDescriptors.list.

  2. No painel Teste este método, no campo nome, insira o seguinte depois de substituir PROJECT_ID pelo ID do projeto do Google Cloud :

    projects/PROJECT_ID/monitoredResourceDescriptors/gce_instance

  3. Clique em Executar.

A solicitação retorna o descritor anterior.

Para exemplos que usam os métodos da API Monitoring, consulte Listar tipos de métricas e recursos.

Métricas

Cada série temporal criada pelo Cloud Monitoring registra um conjunto de pontos de dados, além de informações sobre a organização e o significado desses pontos de dados.

Objetos de métrica

Cada série temporal inclui uma referência à descrição dos dados que estão sendo registrados em um objeto de métrica.

O objeto de métrica contido em uma série temporal especifica o tipo de medições e as informações específicas da métrica sobre essas medições. Para uma definição da estrutura de dados do objeto de métrica, consulte Metric. Por exemplo, este é o objeto de métrica extraído da série temporal em Uma amostra de série temporal:

    {
      "metric": {
        "labels": {
          "log": "kubelet",
          "severity": "DEFAULT"
        },
        "type": "logging.googleapis.com/log_entry_count"
      }

Esse objeto informa que a série temporal contém logging.googleapis.com/log_entry_count medições. Os valores de rótulo informam que essa série temporal específica conta apenas entradas de registro de gravidade DEFAULT no arquivo de registro chamado kubelet.

Há uma série temporal para cada combinação de valores de rótulo. Portanto, as entradas INFO para o mesmo arquivo de registro aparecem em uma série temporal diferente.

O conjunto de rótulos coletados em um objeto de métrica é especificado no descritor desse tipo de métrica.

Descritores de métrica

As informações sobre um tipo de métrica são mantidas em uma estrutura de dados chamada descritor de métrica. Para uma definição dessa estrutura de dados, consulte MetricDescriptor.

Um descritor de métrica é um esquema ou uma especificação de uma estrutura de registro. Ele não inclui os dados sobre uma determinada métrica. Em vez disso, ele informa como interpretar dados associados a um tipo de métrica específico.

Veja um exemplo de descritor de métrica:

{
  "type": "logging.googleapis.com/log_entry_count",
  "name": "projects/a-gcp-project/metricDescriptors/logging.googleapis.com/log_entry_count",
  "labels": [
    {
      "key": "log",
      "description": "Name of the log."
    },
    {
      "key": "severity",
      "description": "Severity of the log entry."
    }
  ],
  "metricKind": "DELTA",
  "valueType": "INT64",
  "unit": "1",
  "description": "Number of log entries that contributed to user-defined metrics.",
  "displayName": "Log entries",
  "metadata": {
    "launchStage": "GA",
    "samplePeriod": "60s"
  },
  "launchStage": "GA"
}

Compare esse descritor de métrica com o objeto de métrica mostrado em Objetos de métrica. O descritor informa o significado dos valores dos rótulos e como interpretar os valores dos pontos de dados.

É possível recuperar descritores de métrica usando a API Cloud Monitoring. Veja, por exemplo, as páginas de referência dos métodos metricDescriptors.list e metricDescriptors.get.

Exemplo ao vivo:se você tiver um projeto do Google Cloud , poderá recuperar esse descritor usando o widget APIs Explorer da seguinte maneira:

  1. Abra a página de referência de metricDescriptors.list.

  2. No painel Teste este método, no campo nome, insira o seguinte depois de substituir PROJECT_ID pelo ID do projeto do Google Cloud :

    projects/PROJECT_ID/metricDescriptors/logging.googleapis.com/log_entry_count

  3. Clique em Executar.

A solicitação retorna o descritor anterior.

Para exemplos que usam os métodos da API Monitoring, consulte Listar tipos de métricas e recursos.

A maioria dos campos no descritor de métrica é autoexplicativa. Os dois que provavelmente precisam de mais explicações são o tipo de métrica e o tipo de valor, que são descritos em Tipos de valor e de métricas.

O Cloud Monitoring tem aproximadamente 6.500 tipos de métricas integrados. Consulte a Lista de métricas para mais detalhes. Também é possível criar seus próprios descritores de métricas para capturar métricas personalizadas. Para mais informações, consulte Visão geral das métricas definidas pelo usuário.