Geração de registros estruturados

No Cloud Logging, registros estruturados se referem a entradas de registro que usam o campo jsonPayload para adicionar estrutura a seus payloads. Se você usa a Cloud Logging API ou a ferramenta de linha de comando gcloud, é possível controlar a estrutura dos seus payloads. Se você usar o agente do Cloud Logging para obter suas entradas de registro, poderá especificar que o agente do Logging converta seus payloads em formato JSON.

Se você usar o serviço BindPlane para ingerir os registros, seus payloads estarão no formato JSON e estruturados de acordo com o sistema de origem. Para informações sobre como localizar e visualizar registros ingeridos por meio do BindPlane, consulte a documentação dessa solução em Como encontrar dados do registro (em inglês).

Para mais informações sobre diferentes formatos de payload, consulte LogEntry.

Veja um exemplo de uma entrada de registro, com o payload estruturado destacado em negrito:


            {
             insertId:  "1m9mtk4g3mwilhp"
             jsonPayload: {
              code:  "structured-log-code"
              message:  "This is a log from the log file at test-structured-log.log"
             }
             labels: {
              compute.googleapis.com/resource_name:  "add-structured-log-resource"
             }
             logName:  "projects/my-sample-project-12345/logs/structured-log"
             receiveTimestamp:  "2018-03-21T01:53:41.118200931Z"
             resource: {
              labels: {
               instance_id:  "5351724540900470204"
               project_id:  "my-sample-project-12345"
               zone:  "us-central1-c"
              }
              type:  "gce_instance"
             }
             timestamp:  "2018-03-21T01:53:39.071920609Z"
            }

    

Operações

O agente do Logging, google-fluentd, é uma versão modificada do coletor de dados de registro fluentd (em inglês). 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 aproveitar os analisadores integrados fornecidos pelo Fluentd.

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).

Analisadores padrão já ativados

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:

Nome do analisador Arquivo de configuração
syslog /etc/google-fluentd/config.d/syslog.conf
nginx /etc/google-fluentd/config.d/nginx.conf
apache2 /etc/google-fluentd/config.d/apache.conf
apache_error /etc/google-fluentd/config.d/apache.conf

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

Instalação

Para ativar a geração de registros estruturados, você precisa alterar a configuração padrão do agente do Logging ao instalá-lo (ou reinstalá-lo). A ativação da geração de registros estruturados fornece a versão mais recente do agente e substitui os arquivos de configuração listados anteriormente. Não há alteração na 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 exportados do Cloud Logging, a alteração poderá afetar os aplicativos de pós-processamento. No caso de exportações do BigQuery, essa ferramenta rejeita as novas entradas de registro para o restante do dia como se tivesse um esquema incorreto.

Veja a seguir as instruções para instalar o agente com a geração de registros estruturados ativada:

  1. Abra uma conexão de terminal para a instância de VM usando SSH ou uma ferramenta semelhante.

  2. Faça o download do script de instalação do agente do Logging executando o seguinte comando na instância de VM:

        curl -sSO "https://dl.google.com/cloudagents/install-logging-agent.sh"
        
  3. Execute o script de instalação com o seguinte comando:

        sudo bash install-logging-agent.sh --structured
        
  4. Para verificar se a instalação foi bem-sucedida, procure a entrada de registro de teste do agente no Visualizador de registros.

  5. Exclua o script de instalação depois que ele for executado com sucesso.

É possível encontrar os arquivos de configuração do agente do Logging em /etc/google-fluentd/config.d/, que agora precisam incluir os analisadores padrão já ativados.

Para mais detalhes, consulte Como instalar o agente do Logging.

Configurar o formato do registro de acesso do Apache

Por padrão, o agente do Logging armazena dados do registro de acesso do Apache 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 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"
      },
      ...
    }
    

A configuração do campo httpRequest, como exibida na amostra anterior, auxilia no rastreamento: o Console do 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.

Configurar o formato de registro de acesso nginx

Por padrão, o agente do Logging armazena dados de registro de acesso nginx 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 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"
        },
        ...
      }
    

A configuração do campo httpRequest, como exibida na amostra anterior, auxilia no rastreamento: o Console do 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.

Como escrever o 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.

Estes três exemplos mostram uma linha no registro, uma configuração com uma expressão regular que indica o formato da linha de registro e a entrada de registro ingerida:

  • Uma linha no registro:

    REPAIR CAR $500
        
  • Uma configuração com uma expressão regular que indica o formato da 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:  "2018-03-21T01:47:11.475065313Z"
          resource: {
            labels: {
              instance_id:  "3914079432219560274"
              project_id:  "my-sample-project-12345"
              zone:  "us-central1-c"
            }
            type:  "gce_instance"
          }
          timestamp:  "2018-03-21T01:47:05.051902169Z"
         }
        

Como visualizar registros estruturados

Para pesquisar registros e usar o visualizador de registros do Console do Cloud, consulte esta página.

Para ler entradas de registro usando a ferramenta de linha de comando gcloud ou a API, consulte esta página.

Resolver problemas

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