Rótulos de métrica com base em registros

Nesta página, discutimos rótulos padrão de métricas com base em registros e explicamos como criar e usar rótulos em métricas com base em registros.

Se você estiver familiarizado com rótulos, acesse diretamente 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 acompanham 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 Stackdriver Logging como extrair o valor do rótulo das entradas de registro. Especifique o valor como um destes:

  • todo o conteúdo de um campo nomeado na entrada de registro
  • parte de um campo nomeado que corresponde a uma expressão regular

Extraia rótulos de campos de entrada de registro internos, como httpRequest.status, ou dos campos de payload textPayload, jsonPayload ou protoPayload.

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

Os valores de rótulo extraídos não devem ser muito longos e não pode haver muitos valores diferentes para cada rótulo:

  • É 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, poderá haver 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 saber mais informações sobre o custo de métricas com base em registros, consulte Preços do Stackdriver. Para ver cotas e limites relacionados à métrica, consulte Cotas e limites e Solução de problemas.

Rótulos padrão

Todas as métricas com base em registros, incluindo as métricas de registro do sistema, recebem 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 CloudSQL, balanceadores de carga etc.

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

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

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

Exemplo

A seguinte captura de tela do Explorador de métricas 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:

Explorador de métricas

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

  • O Metrics Explorer está usando a série temporal da métrica logging/log_entry_count e o tipo de recurso gce_instance – instâncias da VM do Compute Engine.

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

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

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

Como criar um rótulo

Você cria rótulos definidos pelo usuário quando cria 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 do Logging

  1. Ao criar uma métrica com base em registros, parte do painel do Metrics Editor 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 o 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 esses passos.

API Logging

Os rótulos são especificados como parte do objeto LogMetric no corpo da solicitação de chamadas para o método projects.metrics.create da API Stackdriver Logging. Para saber mais 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, é preciso adicionar um segmento aos campos metricDescriptor e labelExtractors no 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])
    

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.

Cloud SDK

O comando "gcloud logging" atualmente não é compatível com a criação de métricas com base em registros com rótulos.

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Stackdriver Logging
Precisa de ajuda? Acesse nossa página de suporte.