Geração de registros estruturados

Neste documento, você verá o conceito de geração de registros estruturados e os métodos para adicionar uma estrutura aos campos de payload da entrada de registro. Quando o payload de registros é formatado como um objeto JSON e que está armazenado no campo jsonPayload, o registro entrada é chamado de registro estruturado. Para esses registros, é possível criar consultas que pesquisam caminhos JSON específicos e indexar campos específicos no payload do registro. Por outro lado, quando o payload do registro é formatado como uma string e armazenado no campo textPayload, a entrada de registro é não estruturada. É possível pesquisar o campo de texto, mas não é possível indexar o conteúdo dele.

Para criar entradas de registro estruturadas, faça o seguinte:

• Chame o método de API entries.write e forneça um LogEntry totalmente formatado.
• Use o comando gcloud logging write.

• Usar uma biblioteca de cliente do Cloud Logging que grava registros estruturados.

• Usar o serviço BindPlane.

• Use um agente para gravar registros:

  • Alguns serviços do Google Cloud contêm um agente do Logging integrado que envia os dados gravados em stdout ou stderr como registros no Cloud Logging. É possível usar essa abordagem para serviços do Google Cloud, como o Google Kubernetes Engine, o ambiente flexível do App Engine e as funções do Cloud Run.

  • Para máquinas virtuais (VMs) do Compute Engine, é possível instalar e configurar o Agente de operações ou o agente do Logging legado e, em seguida, use o agente instalado para enviar registros ao Cloud Logging.

Para mais informações sobre essas abordagens, consulte as seções a seguir.

Gravar registros usando bibliotecas de cliente ou a API

É possível gravar dados de registro usando o Bibliotecas de cliente do Cloud Logging, que chame a API Cloud Logging ou chame diretamente a API Cloud Logging. As bibliotecas de cliente podem simplificar o preenchimento dos campos JSON especiais capturando automaticamente algumas informações e fornecendo interfaces para preencher adequadamente os campos. No entanto, para ter controle total dos payloads, chame diretamente a API Cloud Logging e transmita a estrutura completa do LogEntry para a API Cloud Logging.

Para mais informações, consulte a referência de entries.write.

Para ver exemplos de código, consulte Como gravar registros estruturados.

Gravar registros usando a CLI gcloud

É possível gravar dados de registro usando a CLI gcloud. Interface dá suporte a registros estruturados e não estruturados. Quando você quer escrever um registro estruturado, forneça ao comando um objeto JSON serializado.

Para um guia de início rápido, consulte Gravar e consultar entradas de registro com a Google Cloud CLI.

Para exemplos de código, consulte a referência gcloud logging write.

Gravar registros usando o BindPlane

É possível usar o serviço BindPlane para enviar registros ao Logging. Para esses registros, os payloads estão em JSON e são estruturados de acordo com o sistema de origem. Para informações sobre encontrar e visualizar registros ingeridos usando o BindPlane, consulte a documentação Guia de início rápido.

Gravar registros usando um agente

Para acessar os registros das instâncias do Compute Engine, use o Agente de operações ou o agente legado do Cloud Logging. Ambos os agentes podem coletar métricas de aplicativos de terceiros e oferecem suporte à geração de registros estruturados:

• O Agente de operações é o agente recomendado para coletar telemetria das instâncias do Compute Engine. Esse agente combina geração de registros e métricas em um único agente, fornece um e tem recursos de geração de registros de alta capacidade de processamento.

  Para informações sobre como configurar o Agente de operações para oferecer suporte à geração de registros estruturados ou personalizar o formato de um registro estruturado, consulte Configurar o Agente de operações.

• O agente legado do Cloud Logging coleta ou de sistemas operacionais de contêineres. Esse agente não coleta outras formas de telemetria.

O restante desta seção é específico agente legado do Logging.

Agente de registro: campos JSON especiais

Alguns campos no objeto JSON são reconhecidos como especiais pelo agente do Logging legado e extraídos para Estrutura LogEntry. Esses campos JSON especiais podem ser usados para definir os seguintes campos no LogEntry:

• severity
• spanId
• labels definido pelo usuário.
• httpRequest

Como o JSON é mais preciso e versátil do que as linhas de texto, é possível usar objetos JSON para escrever mensagens de várias linhas e adicionar metadados.

Para criar entradas de registro estruturadas para seus aplicativos usando o formato simplificado, consulte a tabela a seguir, que lista os campos e seus valores em JSON:

Para criar entradas de registro no formato simplificado, crie uma representação JSON da entrada usando os campos. Todos os campos são opcionais.

Veja a seguir um exemplo de entrada de registro JSON simplificada:

{
  "severity":"ERROR",
  "message":"There was an error in the application.",
  "httpRequest":{
    "requestMethod":"GET"
  },
  "times":"2020-10-12T07:20:50.52Z",
  "logging.googleapis.com/insertId":"42",
  "logging.googleapis.com/labels":{
    "user_label_1":"value_1",
    "user_label_2":"value_2"
  },
  "logging.googleapis.com/operation":{
    "id":"get_data",
    "producer":"github.com/MyProject/MyApplication",
     "first":"true"
  },
  "logging.googleapis.com/sourceLocation":{
    "file":"get_data.py",
    "line":"142",
    "function":"getData"
  },
  "logging.googleapis.com/spanId":"000000000000004a",
  "logging.googleapis.com/trace":"projects/my-projectid/traces/06796866738c859f2f19b7cfb3214824",
  "logging.googleapis.com/trace_sampled":false
}

Veja a seguir um exemplo de entrada de registro resultante:

{
  "insertId": "42",
  "jsonPayload": {
    "message": "There was an error in the application",
    "times": "2020-10-12T07:20:50.52Z"
  },
  "httpRequest": {
    "requestMethod": "GET"
  },
  "resource": {
    "type": "k8s_container",
    "labels": {
      "container_name": "hello-app",
      "pod_name": "helloworld-gke-6cfd6f4599-9wff8",
      "project_id": "stackdriver-sandbox-92334288",
      "namespace_name": "default",
      "location": "us-west4",
      "cluster_name": "helloworld-gke"
    }
  },
  "timestamp": "2020-11-07T15:57:35.945508391Z",
  "severity": "ERROR",
  "labels": {
    "user_label_2": "value_2",
    "user_label_1": "value_1"
  },
  "logName": "projects/stackdriver-sandbox-92334288/logs/stdout",
  "operation": {
    "id": "get_data",
    "producer": "github.com/MyProject/MyApplication",
    "first": true
  },
  "trace": "projects/my-projectid/traces/06796866738c859f2f19b7cfb3214824",
  "sourceLocation": {
    "file": "get_data.py",
    "line": "142",
    "function": "getData"
  },
  "receiveTimestamp": "2020-11-07T15:57:42.411414059Z",
  "spanId": "000000000000004a"
}

Agente do Logging: configuração

O agente legado do Logging, google-fluentd, é um um empacotamento específico do Cloud Logging do Coletor de dados de registro Fluentd. Esse agente acompanha a configuração padrão do Fluentd e usa plug-ins de entrada dele para receber registros de evento de origens externas, como arquivos em disco, ou para analisar registros de entrada.

O Fluentd tem uma lista de analisadores compatíveis (em inglês) que extraem e convertem os registros em payloads (JSON) estruturados.

Ao configurar uma origem de registro com format [PARSER_NAME], é possível criar com base integrados fornecidos pelo Fluentd. Para informações sobre como configurar agente legado do Logging, consulte Configure o agente do Logging.

Os exemplos de código a seguir mostram a configuração do Fluentd, o registro de entrada e o payload estruturado de saída, que faz parte de uma entrada de registro do Cloud Logging:

• Configuração do Fluentd:

    <source>
      @type tail
  
      format syslog # This uses a predefined log format regex named
                    # `syslog`. See details at https://docs.fluentd.org/parser/syslog.
  
      path /var/log/syslog
      pos_file /var/lib/google-fluentd/pos/syslog.pos
      read_from_head true
      tag syslog
    </source>
  

• Registro (entrada):

    <6>Feb 28 12:00:00 192.168.0.1 fluentd[11111]: [error] Syslog test
  

• Payload estruturado (saída):

    jsonPayload: {
        "pri": "6",
        "host": "192.168.0.1",
        "ident": "fluentd",
        "pid": "11111",
        "message": "[error] Syslog test"
    }
  

Para mais informações sobre como o analisador syslog funciona, consulte a documentação detalhada do Fluentd (em inglês).

Agente do Logging: analisadores padrão ativados por padrão

A tabela a seguir mostra os analisadores padrão que serão incluídos no agente se você ativar a geração de registros estruturados:

Para instruções sobre como ativar a geração de registros estruturados ao instalar o agente legado do Logging, consulte a Seção Instalação.

Agente do Logging: instalação

Para ativar a geração de registros estruturados, você precisa alterar a configuração padrão de o agente legado do Logging ao instalá-lo ou reinstalá-lo. A ativação da geração de registros estruturados substitui os arquivos de configuração listados anteriormente mas não altera a operação do próprio agente.

Quando você ativa a geração de registros estruturados, os registros listados são convertidos em entradas de registro com formatos diferentes dos anteriores à ativação de registros estruturados. Se os registros estiverem sendo roteados para destinos fora do Logging, a alteração poderá afetar qualquer aplicativo pós-processamento. Por exemplo, se o roteamento de registros para o BigQuery, o BigQuery rejeita as novas entradas de registro para o restante do dia como tendo um esquema incorreto.

Para instruções sobre como instalar o agente do Logging legado e ativar a geração de registros estruturada, consulte Como instalar o agente do Logging.

Encontre os arquivos de configuração legados do agente do Logging em /etc/google-fluentd/config.d/, que agora precisa incluir o analisadores padrão ativados por padrão.

Agente do Logging: configurar o formato de registro de acesso do Apache

Por padrão, o agente do Logging legado armazena o acesso ao Apache dados de registro no campo jsonPayload. Exemplo:

{
  "logName": ...,
  "resource": ...,
  "httpRequest": ...,
  "jsonPayload": {
    "user"   : "some-user",
    "method" : "GET",
    "code"   : 200,
    "size"   : 777,
    "host"   : "192.168.0.1",
    "path"   : "/some-path",
    "referer": "some-referer",
    "agent"  : "Opera/12.0"
  },
  ...
}

Como alternativa, é possível configurar o agente do Logging legado para extrair determinados campos para o campo httpRequest; Exemplo:

{
  "logName": ...,
  "resource": ...,
  "httpRequest": {
    "requestMethod": "GET",
    "requestUrl": "/some-path",
    "requestSize": "777",
    "status": "200",
    "userAgent": "Opera/12.0",
    "serverIp": "192.168.0.1",
    "referrer":"some-referrer",
  },
  "jsonPayload": {
    "user":"some-user"
  },
  ...
}

Configurar o campo httpRequest, conforme mostrado no exemplo anterior, ajuda rastreamento: o console do Google Cloud apresenta todos os registros de uma determinada solicitação HTTP em uma hierarquia pai-filho.

Para configurar essa extração, adicione o seguinte ao final do /etc/google-fluentd/config.d/apache.conf:

<filter apache-access>
  @type record_transformer
  enable_ruby true
  <record>
    httpRequest ${ {"requestMethod" => record['method'], "requestUrl" => record['path'], "requestSize" => record['size'], "status" => record['code'], "userAgent" => record['agent'], "serverIp" => record['host'],
    "referer" => record['referer']} }
  </record>
  remove_keys method, path, size, code, agent, host, referer
</filter>

Para mais detalhes sobre como configurar suas entradas de registro, consulte Como modificar registros.

Agente do Logging: configurar o formato de registro de acesso nginx

Por padrão, o agente do Logging legado armazena o acesso nginx dados de registro no campo jsonPayload. Exemplo:

{
  "logName": ...,
  "resource": ...,
  "httpRequest": ...,
  "jsonPayload": {
    "remote":"127.0.0.1",
    "host":"192.168.0.1",
    "user":"some-user",
    "method":"GET",
    "path":"/some-path",
    "code":"200",
    "size":"777",
    "referrer":"some-referrer",
    "agent":"Opera/12.0",
    "http_x_forwarded_for":"192.168.3.3"
  },
  ...
}

Como alternativa, é possível configurar o agente do Logging legado para extrair determinados campos para o campo httpRequest; Exemplo:

{
  "logName": ...,
  "resource": ...,
  "httpRequest": {
    "requestMethod": "GET",
    "requestUrl": "/some-path",
    "requestSize": "777",
    "status": "200",
    "userAgent": "Opera/12.0",
    "remoteIp": "127.0.0.1",
    "serverIp": "192.168.0.1",
    "referrer":"some-referrer",
  },
  "jsonPayload": {
    "user":"some-user",
    "http_x_forwarded_for":"192.168.3.3"
  },
  ...
}

Configurar o campo httpRequest, conforme mostrado no exemplo anterior, ajuda rastreamento: o console do Google Cloud apresenta todos os registros de uma determinada solicitação HTTP em uma hierarquia pai-filho.

Para configurar essa extração, adicione o seguinte ao final do /etc/google-fluentd/config.d/nginx.conf:

<filter nginx-access>
  @type record_transformer
  enable_ruby true
  <record>
    httpRequest ${ {"requestMethod" => record['method'], "requestUrl" => record['path'], "requestSize" => record['size'], "status" => record['code'], "userAgent" => record['agent'], "remoteIp" => record['remote'], "serverIp" => record['host'], "referer" => record['referer']} }
  </record>
  remove_keys method, path, size, code, agent, remote, host, referer
</filter>

Para mais detalhes sobre como configurar suas entradas de registro, consulte Como modificar registros.

Criar seu próprio analisador

Se os registros não forem compatíveis com os analisadores padrão, será possível criar seus próprios. Os analisadores consistem em uma expressão regular usada para combinar registros e aplicar rótulos às partes.

Os exemplos de código a seguir mostram uma linha de registro no registro, um nome de com uma expressão regular que indica o formato da linha de registro, e o entrada de registro armazenada:

• Uma linha no registro:

  REPAIR CAR $500
  

• Uma configuração com uma expressão regular que indica o formato do a linha de registro:

  $ sudo vim /etc/google-fluentd/config.d/test-structured-log.conf
  $ cat /etc/google-fluentd/config.d/test-structured-log.conf
  <source>
    @type tail
  
    # Format indicates the log should be translated from text to
    # structured (JSON) with three fields, "action", "thing" and "cost",
    # using the following regex:
    format /(?<action>\w+) (?<thing>\w+) \$(?<cost>\d+)/
    # The path of the log file.
    path /tmp/test-structured-log.log
    # The path of the position file that records where in the log file
    # we have processed already. This is useful when the agent
    # restarts.
    pos_file /var/lib/google-fluentd/pos/test-structured-log.pos
    read_from_head true
    # The log tag for this log input.
    tag structured-log
  </source>
  

• A entrada de registro resultante:

  {
  insertId:  "eps2n7g1hq99qp"
  jsonPayload: {
    "action": "REPAIR"
    "thing": "CAR"
    "cost": "500"
  }
  labels: {
    compute.googleapis.com/resource_name:  "add-structured-log-resource"
  }
  logName:  "projects/my-sample-project-12345/logs/structured-log"
  receiveTimestamp:  "2023-03-21T01:47:11.475065313Z"
  resource: {
    labels: {
      instance_id:  "3914079432219560274"
      project_id:  "my-sample-project-12345"
      zone:  "us-central1-c"
    }
    type:  "gce_instance"
  }
  timestamp:  "2023-03-21T01:47:05.051902169Z"
  }
  

Resolver problemas

Para solucionar problemas comuns encontrados na instalação ou interação com o agente legado do Logging, consulte Como solucionar problemas do agente.

A seguir

• Para consultar e exibir entradas de registro, acesse Veja os registros usando a Análise de registros.

• Para ler entradas de registro usando a Google Cloud CLI, consulte Como ler entradas de registro.

• Para ler entradas de registro por meio da API Logging, consulte o método entries.list.