Rótulos de métricas com base em registros

Nesta página, você verá rótulos padrão de métricas com base em registros. Além disso, você aprenderá a criá-los e usá-los em métricas desse tipo.

Se já tiver familiaridade com rótulos, vá diretamente para Como criar um rótulo nesta página.

Visão geral

Os rótulos permitem que as métricas com base em registros contenham várias séries temporais, uma para cada valor de rótulo. Todas as métricas com base em registros vêm com alguns rótulos padrão.

Crie mais rótulos definidos pelo usuário em métricas de contagem e de distribuição, por meio de especificações de expressões extratoras. Uma expressão extratora informa ao Cloud Logging como extrair o valor do rótulo das entradas de registro. É possível especificar o valor do rótulo das seguintes formas:

  • Todo o conteúdo de um campo nomeado no objeto LogEntry.
  • Uma parte de um campo nomeado que corresponde a uma expressão regular (regexp).

É possível extrair rótulos dos campos incorporados de LogEntry, como httpRequest.status, ou de um dos campos de payload textPayload, jsonPayload ou protoPayload.

Para saber mais informações sobre expressões regulares, consulte Sintaxe RE2 (em inglês).

Limitações de rótulos definidos pelo usuário

As limitações a seguir se aplicam a rótulos definidos pelo usuário:

  • É possível criar até 10 rótulos definidos pelo usuário por métrica.

  • Um rótulo não pode ser excluído após ser criado.

    • Não é possível modificar a expressão extratora e a descrição do rótulo que você já tenha criado.

    • Não é possível alterar o nome ou o tipo de valor de um rótulo que você já tenha criado.

  • Somente os primeiros 1.024 caracteres de um valor de rótulo são mantidos.

  • Cada métrica com base em registros é limitada a cerca de 30.000 séries temporais ativas, que depende do número de valores possíveis para cada rótulo, inclusive rótulos padrão.

    Por exemplo, se as entradas de registro vierem de 100 recursos, como instâncias de VM, e você definir um rótulo com 20 valores possíveis, talvez haja até 2.000 séries temporais para a métrica.

Se você tiver muitas séries temporais ou muitos pontos de dados, os custos aumentarão, e a atividade poderá ser limitada. Para mais informações sobre o custo das métricas com base em registros, consulte Sistema de preços do Cloud Logging. Para ver limites e cotas relacionados à métrica, consulte Cotas e limites e Como solucionar problemas.

Rótulos padrão

Todas as métricas com base em registros, incluindo as do sistema, vêm com alguns rótulos predefinidos:

  • Rótulos de recursos: todas as métricas usam um objeto de recurso monitorado para identificar a fonte de dados da série temporal. Cada tipo de recurso inclui um nome de tipo e um ou mais rótulos. Exemplos de tipos de recursos incluem instâncias de VM, bancos de dados do Cloud SQL, balanceadores de carga etc.

    O recurso e seus rótulos são listados separadamente de outros rótulos de métricas no Cloud Monitoring, mas têm o mesmo efeito: eles criam séries temporais adicionais na métrica. Para saber mais informações, consulte Métricas, séries temporais e recursos.

  • log: esse rótulo contém o valor da parte LOG_ID do campo logName nas entradas de registro.

  • severity: esse rótulo contém o valor do campo severity nas entradas de registro.

Exemplo

A seguinte captura de tela do Metrics Explorer mostra os rótulos em uma das métricas com base em registros do sistema. Para ver a lista de rótulos, clique dentro da caixa de texto Filtro:

Metrics Explorer

A captura de tela mostra as seguintes informações:

  • O Metrics Explorer usa séries temporais da métrica logging/log_entry_count e do tipo de recurso gce_instance: instâncias de VM do Compute Engine.

    Essa métrica também contém séries temporais de outros tipos de recursos, mas o Metrics Explorer permite que você veja apenas um tipo de recurso por vez.

  • O tipo de recurso gce_instance tem três rótulos de recursos: project_id, instance_id e zone.

  • A métrica tem dois rótulos de métricas: log e severity. Os rótulos definidos pelo usuário também aparecem nessa seção.

Como criar um rótulo

Os rótulos definidos pelo usuário são criados com a métrica. Tanto as métricas de contagem quanto as de distribuição podem ter rótulos. Não é possível adicionar rótulos às métricas com base em registros do sistema.

Console

  1. Ao criar uma métrica com base em registros, parte do painel do Editor de métricas inclui uma opção para adicionar rótulos:

    Menu de rótulos

  2. Clique em Adicionar item. Você verá o seguinte formulário (este já está preenchido) para descrever seu rótulo:

    Criar rótulo

    Dica: para ver todos os campos e valores dentro das suas entradas de registro, escolha uma entrada de registro, clique no ícone de expansão ao lado e em Expandir tudo.

  3. Preencha os seguintes campos no formulário do Rótulo:

    1. Nome: escolha um nome para o rótulo. Por exemplo, ID.

      O nome precisa atender aos seguintes critérios:

      • Não pode ter mais de 100 caracteres de comprimento.
      • Precisa corresponder à expressão regular [a-zA-Z] [a-zA-Z0-9_] *.
      • Precisa consistir em mais do que apenas a string "log".
    2. Descrição: descreva o rótulo. Seja o mais específico possível sobre o formato dos valores de registros esperado. Por exemplo, Instance number.

    3. Tipo de rótulo: escolha String, Booleano ou Inteiro.

    4. Nome do campo: digite o nome do campo de entrada do registro que contém o valor do rótulo. Conforme você digita, aparecem opções. Nesta amostra, o campo é:

      labels."compute.googleapis.com/resource_id"
          
    5. Expressão regular de extração: se o valor do rótulo contiver todo o conteúdo do campo, você poderá deixá-lo vazio. Caso contrário, especifique uma expressão regular (regexp) que extraia o valor do rótulo do valor do campo. Por exemplo, vamos supor que o campo geralmente contenha um texto como o seguinte:

      The instance number is 0123456789; the ID is my-test-instance22
          

      Se você quer que o valor do rótulo seja o número da instância, há muitas expressões regulares para extrair o número correto. Esta é uma delas:

      The instance number is ([0-9]+); .*
          

      Os parênteses, conhecidos como um grupo de captura regexp, identificam a parte da correspondência de texto que será extraída. Para saber mais informações sobre expressões regulares, consulte Sintaxe RE2.

  4. Clique em Concluído para criar o rótulo. Para adicionar mais rótulos, repita essas etapas.

API Logging

Os rótulos são especificados como parte do objeto LogMetric no corpo de solicitação de chamadas para o método project.metrics.create da API do Logging. Para informações sobre as chamadas de método completas, consulte Como criar métricas de contador ou Como criar métricas de distribuição.

Para cada rótulo, é necessário adicionar um segmento aos campos metricDescriptor e labelExtractors em LogMetric.

A sintaxe é a esta:

{
      ...
      metricDescriptor: {
          labels: [
            { key: [LABEL_NAME], valueType: [LABEL_TYPE],
              description: [LABEL_DESCRIPTION] },
            ...
          ]
      },
      labelExtractors: {
        [LABEL_NAME]: [EXTRACTOR_EXPRESSION],
        ...
      },
    }
    

Os elementos de sintaxe têm o seguinte significado:

  • [LABEL_NAME]: o nome do rótulo como uma string.
  • [VALUE_TYPE]: o tipo do rótulo: STRING, BOOL ou INT64.
  • [LABEL_DESCRIPTION]: uma descrição do rótulo.
  • [EXTRACTOR_EXPRESSION]: uma string que combina o nome do campo de entrada de registro com uma expressão regular opcional. Opções:

    EXTRACT([FIELD])
        REGEXP_EXTRACT([FIELD], [REGEXP])
        

Para saber mais informações sobre expressões regulares, consulte Sintaxe RE2 (em inglês).

Veja a seguir um exemplo com dois rótulos:

{
      ...
      metricDescriptor: {
          labels: [
            { key: "label_name_a", valueType: STRING },
            { key: "label_name_b", valueType: INT64 },
          ]
      },
      labelExtractors: {
        "label_name_a":
          "REGEXP_EXTRACT(jsonPayload.field_a, \"before ([a-zA-Z ]+) after\"",
        "label_name_b": "EXTRACT(jsonPayload.field_b)",
      },
    }
    

Para mais detalhes, consulte o tipo LogMetric.

gcloud

Para acessar instruções sobre como criar uma métrica baseada em registros com rótulos usando a ferramenta de linha de comando gcloud, vá para gcloud beta logging metrics create.