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 você estiver familiarizado com os rótulos, acesse diretamente 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).

Você pode extrair rótulos dos campos integrados do 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.

  • Não é possível excluir um rótulo depois de criá-lo.

    • 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á criou.

  • 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 Preços do Cloud Monitoring: métricas faturáveis. Para informações sobre os limites que se aplicam às métricas com base em registros, consulte Cotas e limites: métricas com base em registros e Solução de problemas de métricas com base em registros.

Rótulos padrão

Todas as métricas com base em registros 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 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.

Criar um marcador

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 Criar métrica de registros inclui uma opção para adicionar rótulos.

  2. Clique em Adicionar rótulo.

    Dica: para ver os campos e valores dentro de uma entrada de registro, faça o seguinte:

    1. Na seção Seleção de filtro, clique em Visualizar registros.
    2. No painel Ver registros, escolha uma entrada de registro e clique no expansor ao lado dele.
    3. Clique em Expandir campos aninhados.
  3. Defina os seguintes campos na seção Rótulos:

    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 (em inglês).

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

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 logging metrics create.

API

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 seguinte:

{
  ...
  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 ver mais detalhes, consulte o tipo LogMetric.