Configure etiquetas em métricas baseadas em registos

Este documento aborda as etiquetas de métricas baseadas em registos e explica como criar e usar etiquetas em métricas de registos.

Se já conhece as etiquetas, pode aceder diretamente a Criar uma etiqueta nesta página.

Vista geral das etiquetas para métricas baseadas em registos

As etiquetas permitem que as métricas baseadas em registos contenham várias séries temporais, uma para cada combinação de valores de etiquetas. Todas as métricas baseadas em registos incluem algumas etiquetas predefinidas.

Pode criar etiquetas definidas pelo utilizador adicionais em métricas do tipo contador e do tipo distribuição especificando expressões de extrator. Uma expressão de extrator indica ao Cloud Logging como extrair o valor da etiqueta das entradas de registo. Pode especificar o valor da etiqueta como qualquer uma das seguintes opções:

• Todo o conteúdo de um campo com nome no objeto LogEntry.
• Uma parte de um campo com nome que corresponde a uma expressão regular (regex).

Pode extrair etiquetas dos campos incorporados LogEntry, como httpRequest.status, ou de um dos campos de carga útil textPayload, jsonPayload ou protoPayload. No entanto, não pode extrair o ID de um grupo de erros do campo errorGroups.

Para obter informações sobre expressões regulares, consulte o artigo Sintaxe RE2.

Não coloque informações confidenciais na expressão do extrator e não extraia dados confidenciais para etiquetas. Estes são tratados como dados do serviço.

Nota: crie etiquetas apenas quando precisar de identificar valores para categorizar ou resumir os dados das métricas. Não use etiquetas para dar nomes a campos de dados.

Limitações das etiquetas definidas pelo utilizador

Aplicam-se as seguintes limitações às etiquetas definidas pelo utilizador:

• Pode criar até 10 etiquetas definidas pelo utilizador por métrica.

• Depois de criar uma etiqueta, não a pode eliminar.

  • Pode modificar a expressão do extrator e a descrição da etiqueta que já criou.

  • Não pode alterar o nome nem o tipo de valor de uma etiqueta que já tenha criado.

• Apenas os primeiros 1024 carateres de um valor de etiqueta são mantidos.

• Cada métrica baseada em registos está limitada a cerca de 30 000 séries cronológicas ativas, o que depende do número de valores possíveis para cada etiqueta, incluindo etiquetas predefinidas.

  Por exemplo, se as entradas do registo provierem de 100 recursos, como instâncias de VMs, e definir uma etiqueta com 20 valores possíveis,pode ter até 2000 séries cronológicas para a sua métrica.

Aviso: nunca extraia um valor de etiqueta que seja exclusivo para cada entrada de registo, como os campos insertId ou timestamp completos. Terá tantas séries cronológicas quantas entradas de registo, cada uma contendo um ponto.

Se tiver demasiadas séries cronológicas ou demasiados pontos de dados, os custos aumentam e a sua atividade pode ser limitada. Para mais informações sobre o custo das métricas baseadas em registos, consulte o artigo Métricas faturáveis. Para obter informações sobre os limites aplicáveis às métricas baseadas em registos, consulte os artigos Quotas e limites: métricas baseadas em registos e Resolva problemas com métricas baseadas em registos.

Etiquetas predefinidas

A maioria das métricas baseadas em registos inclui algumas etiquetas predefinidas:

• Etiquetas de recursos: todas as métricas usam um objeto de recurso monitorizado para identificar a origem dos dados de séries cronológicas. Cada tipo de recurso inclui um nome de tipo e uma ou mais etiquetas. Alguns exemplos de tipos de recursos incluem instâncias de VMs, bases de dados do Cloud SQL e equilibradores de carga.

  O recurso e as respetivas etiquetas são apresentados separadamente das outras etiquetas de métricas no Cloud Monitoring, mas têm o mesmo efeito: criam séries cronológicas adicionais na métrica. Para mais informações, consulte o artigo Métricas, séries cronológicas e recursos.

• log: esta etiqueta contém o valor da parte LOG_ID do campo logName nas entradas do registo.

• severity: esta etiqueta contém o valor do campo severity nas entradas do registo. A etiqueta de gravidade é fornecida por predefinição apenas em métricas baseadas em registos do sistema.

Veja etiquetas através do explorador de métricas

Para ver as etiquetas num intervalo temporal gerado para uma métrica baseada em registos, faça o seguinte:

1. Na Google Cloud consola, aceda à página Métricas baseadas em registos:

   Aceda a Métricas baseadas em registos

   Se usar a barra de pesquisa para encontrar esta página, selecione o resultado cuja legenda é Registo.

2. Encontre a métrica que quer ver e, de seguida, selecione Ver no explorador de métricas no menu Mais da métrica.

   Antes de continuar, aguarde até que o gráfico apresente dados, o que pode demorar vários minutos quando cria uma métrica baseada em registos.

3. Para ver as etiquetas disponíveis, expanda o campo Filtro. Pode ver etiquetas de recursos e etiquetas de métricas. A lista de etiquetas é específica do tipo de recurso e do tipo de métrica. Por exemplo:

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

   • O tipo de métrica logging/log_entry_count tem duas etiquetas de métricas: log e severity. As etiquetas definidas pelo utilizador também aparecem nesta secção.

4. Para verificar se uma etiqueta definida pelo utilizador está a extrair os dados corretos das entradas do registo, faça o seguinte:

   1. Altere o elemento Agregação para Não agregado.

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

   3. Na barra de ferramentas, selecione Menu de apresentação de colunas e, de seguida, selecione as suas etiquetas. Este menu apresenta todas as etiquetas para as quais existem dados.

      Se não vir uma etiqueta que criou, verifique o nome do campo e a expressão do extrator.

Crie um marcador

Cria etiquetas definidas pelo utilizador quando cria a métrica. As métricas de contador e as métricas de distribuição podem ter etiquetas. Não pode adicionar etiquetas às métricas baseadas em registos do sistema.

Para criar uma etiqueta, especifica o campo na entrada do registo e, em seguida, define uma expressão que extrai um valor do campo especificado.

Consola

1. Quando cria uma métrica baseada em registos, o painel Criar métrica de registos inclui uma opção para adicionar etiquetas.

2. Clique em Adicionar etiqueta.

   Dica: para ver os campos e os valores numa entrada do registo, faça o seguinte:

   1. Na secção Seleção de filtros, clique em Pré-visualizar registos.
   2. No painel Ver registos, escolha uma entrada de registo e clique no expansor junto à mesma.
   3. Clique em Expandir campos aninhados.

3. Defina os seguintes campos na secção Etiquetas:

   1. Nome da etiqueta: introduza um nome para a etiqueta. Por exemplo, ID.
      

      O nome tem de cumprir os seguintes critérios:

      • Não pode ter mais de 100 carateres.
      • Corresponde à expressão regular [a-zA-Z][a-zA-Z0-9_]*.
      • Consistir em mais do que apenas a string "log".

   2. Descrição: descreva a etiqueta. Tente ser o mais específico possível acerca do formato dos valores de registos esperados. Por exemplo, Instance number.

   3. Tipo de etiqueta: escolha String, Booleano ou Número inteiro.

   4. Nome do campo: introduza o nome do campo de entrada do registo que contém o valor da etiqueta. São-lhe oferecidas opções à medida que escreve. Neste exemplo, o campo é:

      labels."compute.googleapis.com/resource_id"
      

   5. Expressão regular: se o valor da etiqueta consistir em todo o conteúdo do campo, pode deixar este campo vazio. Caso contrário, especifique um grupo de captura de regexp que extraia o valor da etiqueta do valor do campo.

      Por exemplo, suponha que o campo contém normalmente texto como o seguinte:

      The instance number is 0123456789; the ID is my-test-instance22
      

      Se quiser que o valor da etiqueta seja o número da instância, existem muitas expressões regulares que extraem o número correto. Por exemplo, na expressão seguinte, os parênteses são um grupo de captura que identifica a parte do texto que vai ser extraída:

      The instance number is ([0-9]+); .*
      

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

4. Clique em Concluído para criar a etiqueta. Pode adicionar mais etiquetas repetindo estes passos.

5. Para concluir a criação da métrica, clique em Criar métrica.

gcloud

Para criar uma métrica baseada em registos com etiquetas personalizadas, tem de criar um ficheiro que contenha uma representação da sua definição de LogMetric no formato JSON ou YAML, incluindo as etiquetas personalizadas. Em seguida, crie a métrica chamando o comando create com a flag --config-from-file, substituindo FILENAME pelo nome do seu ficheiro JSON ou YAML:

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

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

API

As etiquetas são especificadas como parte do objeto LogMetric no corpo do pedido de chamadas para o método projects.metrics.create da API Logging. Para informações sobre as chamadas de métodos completos, consulte Criar métricas de contador ou Criar métricas de distribuição.

Para cada etiqueta, tem de adicionar um segmento aos campos metricDescriptor e labelExtractors no elemento 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 da etiqueta como uma string.
• VALUE_TYPE: o tipo da etiqueta: STRING, BOOL ou INT64.
• LABEL_DESCRIPTION: uma descrição da etiqueta.

• EXTRACTOR_EXPRESSION: uma string que combina o nome do campo de entrada do registo com uma expressão regular opcional. A expressão do extrator pode ser uma das seguintes:

  EXTRACT(FIELD)
  

  REGEXP_EXTRACT(FIELD, REGEXP)
  

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

Segue-se um exemplo com duas etiquetas:

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

Exemplos

Esta secção oferece alguns exemplos que podem ajudar a começar a criar etiquetas nas suas métricas baseadas em registos definidas pelo utilizador. Depois de criar uma etiqueta, recomendamos que valide as etiquetas através do Explorador de métricas.

Dicas:

• Tem de usar um grupo de captura quando especifica uma expressão de extrator.
• Se não especificar uma expressão de extrator, é extraído o valor completo do campo.

• Certifique-se de que o conjunto de valores possíveis para qualquer etiqueta está restrito. Um pequeno conjunto de valores discretos (como "vermelho", "verde" e "azul") é a abordagem preferencial. Se, por exemplo, extrair os valores RGB de 8 bits para uma etiqueta de cor, pode ter mais de 16 milhões de valores diferentes. Isto significa que pode ter mais de 16 milhões de séries cronológicas.

  Não extraia valores de alta resolução, como datas/horas, qualquer tipo de identificador único, IDs de utilizadores, endereços IP, URLs sem parâmetros, etc.

Extraia o código de estado de um registo de auditoria

Se um campo não contiver carateres especiais, pode usar o nome do campo na etiqueta da métrica baseada em registos.

Por exemplo, para os registos de auditoria, o campo protoPayload está em conformidade com a estrutura AuditLog. Por conseguinte, para extrair o campo status de um registo de auditoria, pode definir o nome do campo como protoPayload.status.code e deixar a expressão do extrator vazia.

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

Extraia o valor de um campo com carateres especiais

Se um campo numa entrada de registo contiver carateres especiais, coloque o campo entre aspas duplas.

Por exemplo, para extrair o valor completo da etiqueta k8s-pod/k8s-app, defina o nome do campo como labels."k8s-pod/k8s-app" e deixe a expressão vazia.

Extraia um valor de uma carga útil de texto

Nota: para garantir que o conjunto de valores possíveis para a etiqueta está restrito, especifique sempre uma expressão do extrator para campos de carga útil de texto.

Considere uma entrada de registo 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 do registo com o formato anterior, pode fazer algo como:

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

Extraia o valor de um campo repetido

Uma entrada de registo pode conter um campo com campos repetidos. No JSON, estes campos são apresentados com parênteses retos ([]). Do ponto de vista das etiquetas, considere os campos repetidos como um conjunto e o extrator de etiquetas como um iterador. Fornece os critérios para a correspondência quando define a etiqueta, e o extrator itera sobre o conjunto até encontrar uma correspondência. A primeira correspondência é sempre devolvida, mesmo quando vários membros do conjunto correspondem aos critérios.

Decide criar uma métrica baseada em registos que contabiliza registos de auditoria. Antes de configurar a etiqueta, reveja vários registos de auditoria e repare que o formato de protoPayload está em conformidade com a estrutura AuditLog. A imagem seguinte ilustra uma parte de uma entrada do registo 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}
    ...
  }
  ...
}

Decide criar uma etiqueta para a sua métrica baseada em registos que armazena informações do campo permission. Repara que estes campos estão formatados como io.k8s.xyz, em que xyz é uma string que fornece mais detalhes sobre o pedido. Esta 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 etiquetas, não quer extrair as informações detalhadas. Só quer armazenar valores como get ou coordination na etiqueta. Além disso, decide que não quer incluir o prefixo comum, io.k8s., no valor da etiqueta.

Em seguida, configure a etiqueta. Uma vez que o campo permission é um campo repetido, com o campo authorizationInfo como principal, define o nome do campo da seguinte forma:

protoPayload.authorizationInfo.permission

Por último, cria a seguinte expressão regular:

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