Configurar rótulos em métricas com base em registros

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Neste documento, falamos sobre identificadores de métricas com base em registros e explicamos como criar e usar identificadores em métricas de registro.

Se você tiver familiaridade com identificadores, vá direto para Criar um identificador nesta página.

Visão geral dos identificadores de métricas com base em registros

Os rótulos permitem que as métricas com base em registros contenham várias séries temporais, uma para cada combinação de valores de rótulo. Todas as métricas com base em registros vêm com alguns identificadores 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 identificador 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 mais informações sobre expressões regulares, consulte Sintaxe RE2 (em inglês).

Não coloque informações sensíveis na expressão do extrator e não extraia dados sensíveis em rótulos. Eles são tratados como dados de serviço.

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.

• Depois de criar um identificador, não é possível excluí-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á 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 identificador, inclusive identificadores 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 sujeitas a cobrança. 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

A maioria das métricas com base em registros vêm com alguns rótulos predefinidos:

• Identificadores 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 identificadores. Exemplos de tipos de recursos incluem instâncias de VM, bancos de dados do Cloud SQL e balanceadores de carga.

  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. O identificador de gravidade é fornecido por padrão somente nas métricas com base em registros do sistema.

Conferir rótulos usando o Metrics Explorer

Para conferir os rótulos em uma série temporal gerada para uma métrica com base em registros, faça o seguinte:

1. No Google Cloud console, acesse a página Métricas com base em registros:

   Acessar Métricas com base em registros

   Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Logging.

2. Encontre a métrica que você quer visualizar e selecione Ver no Metrics Explorer no menu more_vert Mais da métrica.

   Antes de continuar, aguarde até que o gráfico mostre os dados, o que pode levar vários minutos quando você cria uma métrica com base em registros.

3. Para conferir os identificadores disponíveis, abra o campo Filtro. Talvez você veja rótulos de recursos e de métricas. A lista de rótulos é específica para o tipo de recurso e de métrica. Exemplo:

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

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

4. Para verificar se um rótulo definido pelo usuário está extraindo os dados corretos das suas entradas de registro, faça o seguinte:

   1. Mude o elemento Aggregation para Unaggregated.

   2. No gráfico, selecione Tabela ou Ambos.

   3. Na barra de ferramentas, selecione view_column Menu de exibição de colunas e, em seguida, selecione os rótulos. Esse menu mostra todos os rótulos com dados.

      Se você não encontrar um rótulo que criou, verifique o nome do campo e a expressão do extrator.

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 identificadores às métricas com base em registros do sistema.

Para criar um rótulo, especifique o campo na entrada de registro e, em seguida, defina uma expressão que extraia um valor do campo especificado.

gcloud logging metrics create METRIC_NAME --config-from-file FILENAME

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

{
  ...
  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)",
  },
}

Exemplos

Esta seção apresenta alguns exemplos que podem ajudar você a começar a criar rótulos nas métricas com base em registros definidas pelo usuário. Depois de criar um rótulo, recomendamos que você verifique os rótulos usando o Metrics Explorer.

Dicas:

• É necessário usar um grupo de captura ao especificar uma expressão de extrator.
• Se você não especificar uma expressão de extrator, o valor inteiro do campo será extraído.

• Verifique se o conjunto de valores possíveis para qualquer rótulo está limitado. A abordagem recomendada é ter um pequeno conjunto de valores distintos (como "vermelho", "verde" e "azul"). Se você extrair os valores RGB de 8 bits de um rótulo de cor, poderá ter mais de 16 milhões de valores diferentes. Isso significa que você pode ter mais de 16 milhões de séries temporais.

  Não extraia valores de alta resolução, como carimbos de data/hora, qualquer tipo de identificador exclusivo, IDs de usuários, endereços IP, URLs não parametrizados e assim por diante.

Extrair o código de status de um registro de auditoria

Se um campo não tiver caracteres especiais, use o nome do campo no rótulo da métrica baseada em registros.

Por exemplo, para registros de auditoria, o campo protoPayload está em conformidade com a estrutura AuditLog. Portanto, para extrair o campo status de um registro de auditoria, defina o nome do campo como protoPayload.status.code e deixe a expressão do extrator vazia.

Se você quiser extrair apenas o primeiro dígito do código de erro, defina a expressão do extrator como (\d)\d\d.

Extrair valor de um campo com caracteres especiais

Se um campo em uma entrada de registro tiver caracteres especiais, coloque-o entre aspas duplas.

Por exemplo, para extrair o valor inteiro do rótulo k8s-pod/k8s-app, defina o nome do campo como labels."k8s-pod/k8s-app" e deixe a expressão vazia.

Extrair um valor de um payload de texto

Considere uma entrada de registro com o seguinte formato:

textPayload: "unfinished_task_instance_count.py:61 Unfinished task instance count metric value 0 for state: deferred"

Para extrair o valor do estado, como deferred, das entradas de registro com o formato anterior, faça o seguinte:

• Nome do campo: textPayload
• Expressão do extrator: ^unfinished.*state: ([a-z]+)

Extrair valor de um campo repetido

Uma entrada de registro pode conter um campo com campos repetidos. No JSON, esses campos são mostrados usando colchetes ([]). Do ponto de vista dos identificadores, considere os campos repetidos como um conjunto e o extrator de identificadores como um iterador. Você fornece os critérios para a correspondência ao definir o rótulo, e o extrator itera sobre o conjunto até encontrar uma correspondência. A primeira correspondência é sempre retornada, mesmo quando vários membros do conjunto correspondem aos critérios.

Você decide criar uma métrica com base em registros que conte os registros de auditoria. Antes de configurar o rótulo, você analisa vários registros de auditoria e observa que o formato do protoPayload está de acordo com a estrutura AuditLog. A seguir, ilustramos uma parte de uma entrada de registro de auditoria.

{
  ...
  protoPayload: {
    @type: "type.googleapis.com/google.cloud.audit.AuditLog"
    authenticationInfo: {1}
    authorizationInfo: [
      0: {
        granted: true
        permission: "io.k8s.coordination.v1.leases.get"
        resource: "coordination.k8s.io/v1/namespaces/kube-system/leases/maintenance-controller"
      }
    ]
    requestMetadata: {2}
    status: {1}
    ...
  }
  ...
}

Você decide criar um rótulo para a métrica baseada em registros que armazena informações do campo permission. Esses campos são formatados como io.k8s.xxx, em que xxx é uma string que fornece mais detalhes sobre a solicitação. Essa string pode ter um valor como get ou uma formatação mais complexa, como io.k8s.coordination.v1.leases.get.

Para minimizar o número de valores de rótulo, não extraia as informações detalhadas. Você só quer armazenar valores como get ou coordination no rótulo. Além disso, você decide que não quer incluir o prefixo comum, io.k8s., no valor do rótulo.

Em seguida, configure o rótulo. Como o campo permission é um campo repetido, com o campo pai sendo authorizationInfo, defina o nome do campo da seguinte maneira:

protoPayload.authorizationInfo.permission

Por fim, crie a seguinte expressão regular:

io.k8s.([a-z]+).*