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:

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

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