Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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

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 identificadores permitem que as métricas com base em registros contenham várias série temporal, uma para cada combinação de valores de identificador. 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 identificador das seguintes formas:

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

É possível extrair identificadores dos campos incorporados de LogEntry, como httpRequest.status, ou de um dos campos de payload textPayload, jsonPayload, ou protoPayload. No entanto, não é possível extrair o ID de um grupo de erros do campo errorGroups.

Para mais informações sobre expressões regulares, consulte Sintaxe RE2.

Não coloque informações sensíveis na expressão extratora e não extraia dados sensíveis para identificadores. Eles são tratados como dados de serviço.

Limitações de identificadores 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érie temporal 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 Google Cloud Observability. 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.

Identificadores padrão

A maioria das métricas com base em registros vêm com alguns identificadores pré-definidos:

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 identificadores são listados separadamente de outros identificadores de métricas no Cloud Monitoring, mas têm o mesmo efeito: eles criam série temporal 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 em métricas com base em registros do sistema.

Ver identificadores usando o Metrics Explorer

Para ver os identificadores em uma série temporal gerada para uma métrica com base em registros, faça o seguinte:

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.
Encontre a métrica que você quer visualizar e selecione Ver no Metrics Explorer no menu 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.
Para ver os identificadores disponíveis, expanda o campo Filtro. Você pode ver identificadores de recursos e identificadores de métricas. A lista de identificadores é específica para o tipo de recurso e o tipo de métrica. Exemplo:
- O tipo de recurso gce_instance tem três identificadores de recursos: project_id, instance_id e zone.
- O tipo de métrica logging/log_entry_count tem dois identificadores de métricas: log e severity. Os identificadores definidos pelo usuário também aparecem nessa seção.
Para verificar se um identificador definido pelo usuário está extraindo os dados corretos das entradas de registro, faça o seguinte:
1. Mude o elemento Agregação para Não agregado.
2. No gráfico, selecione Tabela ou Ambos.
3. Na barra de ferramentas, selecione Menu de exibição de colunas, e, em seguida, selecione seus identificadores. Esse menu mostra todos os identificadores para os quais há dados.
  
  Se você não encontrar um identificador criado, verifique o nome do campo e a expressão extratora.

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 identificador, especifique o campo na entrada de registro e defina uma expressão que extraia um valor do campo especificado.

Console

Ao criar uma métrica com base em registros, o painel Criar métrica com base em registros inclui uma opção para adicionar identificadores.
Clique em Adicionar identificador.

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.
Defina os seguintes campos na seção Rótulos:
1. Nome do identificador: digite um nome para o identificador. 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 identificador: escolha STRING, BOOLEAN ou INTEGER.
  
  Para mais informações sobre os vários tipos de dados que podem ser usados para criar métricas com base em registros, consulte Tipos de dados para métricas com base em registros.
4. Nome do campo: digite o nome do campo de entrada de 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 identificador contiver todo o conteúdo do campo, é possível deixá-lo vazio. Caso contrário, especifique um grupo de captura regexp que extraia o valor do identificador 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. Por exemplo, na expressão a seguir, os parênteses são um grupo de captura que identifica a parte do texto que será extraída:
```
The instance number is ([0-9]+); .*
```
  Para mais informações sobre expressões regulares, consulte Sintaxe RE2.
Clique em Concluído para criar o identificador. Para adicionar mais rótulos, repita esses passos.
Para concluir a criação da métrica, clique em Criar métrica.

gcloud

Para criar uma métrica com base em registros com identificadores personalizados, é necessário criar um arquivo que contenha uma representação da definição de LogMetric no formato JSON ou YAML, incluindo os identificadores personalizados. Em seguida, crie a métrica chamando o comando create com a flag --config-from-file, substituindo FILENAME pelo nome do arquivo JSON ou YAML:

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

Para mais informações, consulte gcloud logging metrics create.

API

Os rótulos são especificados como parte do LogMetric objeto no corpo de solicitação de chamadas para o projects.metrics.create método da API 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 identificador, é 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. A expressão do extrator pode ser uma das seguintes:
```
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 identificadores:

{
  ...
  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 LogMetric tipo.

Exemplos

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

Dicas:

É necessário usar um grupo de captura ao especificar uma expressão extratora.
Se você não especificar uma expressão extratora, todo o valor do campo será extraído.
Verifique se o conjunto de valores possíveis para qualquer identificador está restrito. Um pequeno conjunto de valores discretos (como "vermelho", "verde" e "azul") é a abordagem preferida. Por exemplo, se você extrair os valores RGB de 8 bits para um identificador 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érie temporal.

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 contiver caracteres especiais, você poderá usar o nome do campo no identificador da métrica com base em registros.

Por exemplo, para registros de auditoria, o protoPayload campo está em conformidade com a AuditLog estrutura. 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 extratora vazia.

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

Extrair valor de um campo com caracteres especiais

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

Por exemplo, para extrair todo o valor do identificador 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 de entradas de registro com o formato anterior, faça algo como:

Nome do campo: textPayload
Expressão extratora: ^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 rótulos, considere os campos repetidos como um conjunto e o extrator de rótulos como um iterador. Você fornece os critérios para a correspondência ao definir o identificador, e o extrator itera sobre o conjunto até que uma correspondência seja encontrada. 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 conta registros de auditoria. Antes de configurar o identificador, você analisa vários registros de auditoria e observa que o formato do protoPayload está em conformidade com a AuditLog estrutura. 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 identificador para sua métrica com base em registros que armazena informações do campo permission. Você observa que esses campos são formatados como io.k8s.xyz, em que xyz é uma string que fornece mais detalhes sobre a solicitação. Essa string pode ter um valor como get ou ela pode ter uma formatação mais complexa, como io.k8s.coordination.v1.leases.get.

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

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

protoPayload.authorizationInfo.permission

Por fim, crie a seguinte expressão regular:

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