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 do registro é formatado como um objeto JSON e armazenado no campo jsonPayload, a entrada de registro é chamada 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. Você pode pesquisar o campo de texto, mas não é possível indexar o conteúdo dele.

Para criar entradas de registro estruturadas, siga um destes procedimentos:

  • Chame o método de API entries.write e forneça um LogEntry totalmente formatado.
  • Usar uma biblioteca de cliente do Cloud Logging que grava registros estruturados.
  • Use o comando gcloud logging write.
  • Use 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 para o Cloud Logging. Use essa abordagem para serviços do Google Cloud, como o Google Kubernetes Engine, o ambiente flexível do App Engine e o Cloud Functions.

    • 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, usar o agente instalado para enviar registros ao Cloud Logging.

Para saber mais sobre essas abordagens, consulte as próximas seções.

Gravar registros usando bibliotecas de cliente ou a API

É possível gravar dados de registro usando as bibliotecas de cliente do Cloud Logging, que chamam a API Cloud Logging, ou chamando 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 os campos adequadamente. No entanto, para ter controle total sobre a estrutura dos seus payloads, chame diretamente a API Cloud Logging e transmita a estrutura LogEntry completa para ela.

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

Para 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. A interface dá suporte a registros não estruturados e estruturados. Quando quiser gravar 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 para o Logging. Para esses registros, os payloads estão no formato JSON e estruturados de acordo com o sistema de origem. Para informações sobre como encontrar e visualizar registros ingeridos usando o BindPlane, consulte o Guia de início rápido do BindPlane.

Gravar registros usando um agente

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

  • O Agente de operações é 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 uma configuração baseada em YAML e apresenta geração de registros de alta capacidade.

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

  • O agente legado do Cloud Logging coleta registros. Esse agente não coleta outras formas de telemetria.

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

Agente do Logging: campos JSON especiais

Alguns campos no objeto JSON são reconhecidos como especiais pelo agente do Logging legado e extraídos para a estrutura LogEntry. Esses campos JSON especiais podem ser usados para definir os seguintes campos em 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:

Campo do registro JSON Campo LogEntry Função do agente do Cloud Logging Valor de exemplo
severity severity O agente do Logging tenta corresponder diversas strings de gravidade comum, que incluem a lista de strings LogSeverity reconhecida pela API Logging. "severity":"ERROR"
message textPayload (ou parte de jsonPayload) A mensagem que aparece na linha de entrada do registro no Explorador de registros. "message":"There was an error in the application."

Observação: message é salvo como textPayload se for o único campo restante depois que o agente do Logging remover os outros campos de finalidade especial e detect_json não tiver sido ativado. Caso contrário, message permanecerá em jsonPayload. detect_json não é aplicável a ambientes de geração de registros gerenciados, como o Google Kubernetes Engine. Se a entrada de registro tiver um rastreamento de pilha de exceção, o rastreamento precisa ser definido neste campo de registro JSON message para que o rastreamento de pilha de exceção possa ser analisado e salvo no Error Reporting.
log (somente Google Kubernetes Engine legado) textPayload Aplica-se somente ao Google Kubernetes Engine legado: se, após a remoção de campos de finalidade especial, apenas um campo log permanecer, então o campo será salvo como textPayload.
httpRequest httpRequest Um registro estruturado no formato do campo LogEntry HttpRequest. "httpRequest":{"requestMethod":"GET"}
campos relacionados ao tempo timestamp Para mais informações, consulte Campos relacionados ao tempo. "time":"2020-10-12T07:20:50.52Z"
logging.googleapis.com/insertId insertId Para mais informações, consulte insertId na página LogEntry. "logging.googleapis.com/insertId":"42"
logging.googleapis.com/labels labels O valor desse campo precisa ser um registro estruturado. Para mais informações, consulte labels na página LogEntry. "logging.googleapis.com/labels": {"user_label_1":"value_1","user_label_2":"value_2"}
logging.googleapis.com/operation operation O valor desse campo também é usado pelo Explorador de registros para agrupar entradas de registro relacionadas. Para mais informações, consulte operation na página LogEntry. "logging.googleapis.com/operation": {"id":"get_data","producer":"github.com/MyProject/MyApplication", "first":"true"}
logging.googleapis.com/sourceLocation sourceLocation Informações do local do código-fonte associadas à entrada do registro, se houver. Para mais informações, consulte LogEntrySourceLocation na página LogEntry. "logging.googleapis.com/sourceLocation": {"file":"get_data.py","line":"142","function":"getData"}
logging.googleapis.com/spanId spanId O ID do período dentro do trace associado à entrada de registro. Para mais informações, consulte spanId na página LogEntry. "logging.googleapis.com/spanId":"000000000000004a"
logging.googleapis.com/trace trace Nome do recurso do trace associado à entrada de registro, se houver. Para mais informações, consulte trace na página LogEntry. "logging.googleapis.com/trace":"projects/my-projectid/traces/0679686673a"

Observação: se não for gravando em stdout ou stderr, o valor deste campo deverá ser formatado como projects/[PROJECT-ID]/traces/[TRACE-ID] para que possa ser usado pelo Explorador de registros e pelo Visualizador de Trace para agrupar entradas de registro e exibi-las alinhadas aos traces. Se autoformat_stackdriver_trace for verdadeiro e [V] corresponder ao formato traceId do ResourceTrace, o campo trace do LogEntry tem o valor projects/[PROJECT-ID]/traces/[V].
logging.googleapis.com/trace_sampled traceSampled O valor desse campo precisa ser true ou false. Para mais informações, consulte traceSampled na página LogEntry. "logging.googleapis.com/trace_sampled": false

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 pacote específico do Cloud Logging 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], você pode criar com base nos analisadores integrados fornecidos pelo Fluentd. Para informações sobre como configurar o agente do Logging legado, consulte Configurar o agente do Logging.

Os exemplos de código a seguir 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 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:

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 legado, 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 do agente do Logging legado 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.

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

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

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

A configuração do campo httpRequest, como mostrado no exemplo anterior, auxilia no 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: configure o formato do registro de acesso nginx

Por padrão, o agente legado 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 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"
  },
  ...
}

A configuração do campo httpRequest, como mostrado no exemplo anterior, auxilia no 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 no registro, uma configuração com uma expressão regular que indica o formato da linha e a entrada de registro armazenada:

  • 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:  "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 na interação com o agente do Logging legado, consulte Como solucionar problemas do agente.

A seguir