Como gerar registros estruturados

No Stackdriver Logging, os registros estruturados se referem a entradas de registro que usam o campo jsonPayload para adicionar estrutura aos respectivos payloads. Se você usar a API do Stackdriver Logging ou o utilitário de linha de comando, gcloud logging, será possível controlar a estrutura dos payloads. Se você usar o agente do Stackdriver Logging para receber entradas de registro, poderá especificar que o agente do Logging converta os payloads em formato JSON. Consulte LogEntry para mais informações sobre formatos de payload diferentes.

Aqui está um exemplo de uma entrada de registro, com o payload 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 da geração de registros estruturadas

O agente do Logging google-fluentd é uma versão modificada do coletor de dados de registro Fluentd. Esse agente acompanha a configuração padrão Fluentd e usa plug-ins de entrada Fluentd para extrair registros de evento de origens externas, como arquivos em disco, ou para analisar registros de entrada.

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

Configurando uma origem de registro com format [PARSER_NAME], é possível aproveitar os analisadores internos fornecidos por Fluentd.

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

  • Configuração de Fluentd:

      <source>
        @type tail
    
        format syslog # <--- This uses a predefined log format regex named
                      # `syslog`. See details at https://docs.fluentd.org/v1.0/articles/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:

        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 do Fluentd.

Analisadores padrão ativados por padrão

A tabela abaixo inclui os analisadores padrão incluídos no agente, caso você ative a geração de registros estruturada:

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

Consulte a seção Instalação abaixo para instruções sobre como ativar geração de registros estruturada ao instalar o agente do Stackdriver Logging.

Instalação

Para ativar a geração de registros estruturada, você precisa alterar a configuração padrão do agente do Stackdriver Logging ao instalar (ou reinstalá-lo). A ativação da geração de registros estruturada 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ê ativar a geração de registros estruturada, os registros listados serão convertidos em entradas de registro com formatos diferentes do que tinham antes de ativar registros estruturados. Se os registros estivessem sendo exportados do Stackdriver Logging, a alteração poderia afetar todos os aplicativos de pós-processamento. No caso de exportações do BigQuery, o BigQuery rejeitará as novas entradas de registro pelo restante do dia como tendo um esquema incorreto.

Estas são as instruções para instalar o agente com a geração de registros estruturada 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.

Veja os arquivos de configuração do agente do Stackdriver Logging em /etc/google-fluentd/config.d/, que já precisam incluir os analisadores ativados por padrão.

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 os 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 no 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, conforme mostrado acima, auxilia no rastreamento: o Console do GCP 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 de /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 no 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, conforme mostrado acima, auxilia no rastreamento: o Console do GCP 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 de /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 aceitos pelos analisadores padrão, você poderá escrever os próprios. Os analisadores consistem em uma expressão regular usada para corresponder 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 visualizar entradas de registro com o Visualizador de registros, consulte Como visualizar registros.

Para ler entradas de registro usando o SDK ou a API, consulte Como ler entradas de registro.

Como resolver problemas

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

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Stackdriver Logging
Precisa de ajuda? Acesse nossa página de suporte.