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 registro é formatado como um objeto JSON e esse objeto é 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 de registro. Por outro lado, quando o payload de 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 indexar o conteúdo dele.

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

  • Chame o método da API entries.write e forneça um LogEntry totalmente formatado.
  • Use o comando gcloud logging write.
  • Use uma biblioteca de cliente do Cloud Logging que grava registros estruturados.
  • Use o serviço BindPlane.

  • Use um agente para gravar registros:

    • Alguns Google Cloud serviços contêm um agente de geração de registros integrado que envia os dados gravados em stdout ou stderr como registros para o Cloud Logging. É possível usar essa abordagem para Google Cloud serviços 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, usar 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 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 adequadamente os campos. No entanto, para ter controle total sobre a estrutura dos payloads, chame diretamente a API Cloud Logging e transmita a estrutura LogEntry completa para a API Cloud Logging.

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

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 oferece suporte a registros não estruturados e estruturados. Quando você 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 gcloud logging write referência.

Gravar registros usando o BindPlane

É possível usar o serviço BindPlane para enviar registros ao Logging. Para esses registros, os payloads estão no formato JSON e são 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, é possível usar o Agente de operações ou o agente do Cloud Logging legado. Os dois agentes podem coletar métricas de aplicativos externos e oferecem suporte à geração de registros estruturados:

  • O Agente de operações é o agente recomendado para coletar telemetrias das instâncias do Compute Engine. Esse agente combina a geração de registros e as métricas em um único agente, fornece uma configuração baseada em YAML e apresenta a 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 para personalizar o formulário de um registro estruturado, consulte Configurar o Agente de operações.

  • O agente do Cloud Logging legado 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 LogEntry estrutura. Esses campos especiais do JSON 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 LogEntry campo 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 na Análise 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":"2025-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":"[TRACE_ID]"
"logging.googleapis.com/trace":"projects/my-projectid/traces/[TRACE_ID]"

Observação: se não estiver gravando em stdout ou stderr, formate esse campo como [TRACE_ID] ou use o formato legado projects/[PROJECT_ID]/traces/[TRACE_ID]. Os dois formatos permitem que a Análise de registros e o Trace Explorer correlacionem dados de registro e trace. Se autoformat_stackdriver_trace for verdadeiro e [V] corresponder ao formato do campo traceId no objeto ResourceTrace, o campo trace do LogEntry terá 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"
  },
  "time":"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",
    "time": "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-10-12T07:20:50.52Z",
  "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-10-12T07:20:57.52Z",
  "spanId": "000000000000004a"
}

Agente do Logging: configuração

O agente do Logging legado, google-fluentd, é um empacotamento específico do Cloud Logging para o coletor de dados de registro do Fluentd. O agente do Logging vem com a configuração padrão do Fluentd e usa plug-ins de entrada do Fluentd para extrair logs de eventos de origens externas, como arquivos em disco, ou para analisar registros de entrada.

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

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

As amostras 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 syslog analisador funciona, consulte a documentação detalhada do Fluentd.

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

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

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

Por padrão, o agente do Logging legado 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 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 exibido na amostra anterior, auxilia no rastreamento: o Google Cloud console 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 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 exibido na amostra anterior, auxilia no rastreamento: o Google Cloud console 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.

Estes 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 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