Estrutura de séries temporais

Esta página é uma continuação detalhada da discussão e dos exemplos apresentados em Métricas, séries temporais e recursos e Componentes do modelo de métrica. Para aproveitar ao máximo esta página, leia essas páginas primeiro.

Esta página é destinada a leitores que buscam uma compreensão mais profunda do tempo e a implementação da métrica do Cloud Monitoring especialmente os leitores que usam a API Monitoring. Isso inclui usuários de métricas personalizadas (definidas pelo usuário).

  • Nesta página, mapeamos o modelo de métrica geral para a API Cloud Monitoring. Portanto, ela é útil para qualquer pessoa que use a API Monitoring. Os usuários que interagem principalmente com o console do Google Cloud provavelmente não precisam desse nível de detalhamento.

  • Ele também é útil para qualquer pessoa que use uma integração de terceiros, como OpenTelemetry (link em inglês). Conforme os dados de uma fonte externa chegam ao Cloud Monitoring por meio de uma integração, eles são mapeados para o modelo de métrica do Cloud Monitoring e tratados como qualquer outro dado de métrica.

Para saber mais 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.

    Estrutura de uma série temporal.

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. Veja 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:

  • Os registros do campo metric

    • 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 com 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 neste campo são descritas em mais detalhes em Objetos de recurso monitorado.

  • Os campos metricKind e valueType mostram como interpretar os valores. Para mais informações, consulte Tipos e tipos 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 do 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 para o 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"
        }
      }

Esta instância de um recurso monitorado é do tipo gce_instance. Ele 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 chamado de 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 usar a API Cloud Monitoring para recuperar os descritores de recursos monitorados no projeto do Google Cloud. Veja, por exemplo, as páginas de referência dos métodos monitoredResourceDescriptors.list e monitoredResourceDescriptors.get.

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

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

  2. No painel Try this method, digite o seguinte:

    • nome: projects/PROJECT_ID/monitoredResourceDescriptors/gce_instance

      Substitua PROJECT_ID pelo ID do projeto do Google Cloud.

  3. Clique em Executar.

A solicitação retorna o descritor anterior.

Para exemplos de uso dos métodos da API Monitoring, consulte Listar tipos de métricas e recursos.

Métrica

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ção e informações específicas sobre essas medições. Para uma definição da estrutura de dados do objeto de métrica, consulte Metric. Por exemplo, este é o objeto "metric" extraídos da série temporal 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 de medidas. 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.

Confira 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 ativo: se você tiver um projeto do Google Cloud, poderá recuperar esse usando o widget do APIs Explorer da seguinte maneira:

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

  2. No painel Testar este método, insira o seguinte:

    • name: projects/PROJECT_ID/metricDescriptors/logging.googleapis.com/log_entry_count Substitua PROJECT_ID pelo ID do seu projeto do Google Cloud.
  3. Clique em Executar.

A solicitação retorna o descritor anterior.

Para exemplos de uso dos 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 campos que costumam precisar de mais explicações são o tipo de métrica e o tipo de valor, que são descritos em Tipos de métricas.

O Cloud Monitoring tem aproximadamente 6.500 tipos de métricas integradas. Consulte a lista de métricas para saber detalhes. Você também pode crie sua própria métrica descritores para capturar métricas personalizadas. Para mais informações, consulte Visão geral das métricas definidas pelo usuário.