Esta página foi traduzida pela API Cloud Translation.

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 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 de extração 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

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

Exemplo: usar o Metrics Explorer

A seguinte captura de tela do Metrics Explorer mostra os identificadores 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 identificadores às métricas com base em registros do sistema.

Console

Ao criar uma métrica com base em registros, o painel Criar registros inclui uma opção para adicionar identificadores.
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.
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 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 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 saber mais informações sobre expressões regulares, consulte Sintaxe RE2.
Clique em Concluído para criar o rótulo. 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 rótulos personalizados, é preciso criar um arquivo que contém uma representação da definição de LogMetric no nos formatos JSON ou YAML, incluindo os rótulos 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 ver mais informações, consulte 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. 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 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.