Geração de registros estruturados

No Cloud Logging, um objeto LogEntry pode armazenar um payload de registro como dados estruturados ou texto não estruturado. Uma entrada de registro estruturada armazena o payload como um objeto JSON no campo jsonPayload, enquanto uma entrada de registro não estruturada armazena o payload como uma string no campo textPayload.

Ao formatar o payload de registro como um objeto JSON, é possível consultar por caminhos JSON na Análise de registros, consultar campos individuais na página Análise de Observabilidade e indexar campos específicos para acelerar as consultas. Com registros não estruturados, é possível pesquisar a string de texto, mas não é possível consultar ou indexar chaves individuais.

Como os registros estruturados são gravados

A forma como as entradas de registro estruturadas são gravadas no Logging depende do seu ambiente e de como os registros são coletados:

• OpenTelemetry e a API Telemetry (OTLP): quando você envia registros de protocolo OpenTelemetry (OTLP) para o Logging, o Google Cloud Observability converte dados de registro estruturados no campo jsonPayload. Consulte Registro de registro do OTLP para mapeamento de entrada de registro.

• Agentes do Logging integrados: em ambientes de computação gerenciados (como o Google Kubernetes Engine e o Cloud Run), os agentes integrados analisam o JSON de linha única gravado em stdout ou stderr no campo jsonPayload. Consulte Escolher um framework de geração de registros.
• Agente de operações: nas VMs do Compute Engine, o agente grava registros estruturados quando coleta registros JSON ou analisa registros de texto. Consulte Configurar o Agente de Operações.

• Bibliotecas de cliente do Logging: essas bibliotecas gravam registros estruturados quando você transmite um objeto ou mapa JSON como payload ou quando elas geram JSON de linha única para stdout ou stderr. Consulte Como gravar registros estruturados.

• Google Cloud CLI ou a API Logging: é possível executar gcloud logging write com a flag --payload-type=json (exemplo) ou chamar o método da API entries.write com um objeto jsonPayload.

• BindPlane: esse serviço envia registros com payloads JSON de fontes locais ou híbridas para o Logging. Consulte o guia de início rápido do BindPlane.

Campos JSON especiais em payloads estruturados

Quando os agentes do Logging ingerem registros estruturados, eles podem mapear campos específicos nos dados de registro para campos de nível superior no objeto LogEntry em vez de deixá-los em jsonPayload:

• Agente de operações: para os campos JSON que o Agente de Operações mapeia automaticamente ao usar o processador parse_json ou os receptores tcp e fluent_forward, consulte Campos especiais em payloads estruturados.

• OpenTelemetry (OTLP): para informações sobre como o Google Cloud Observability mapeia registros de registro OTLP para campos LogEntry, consulte Mapeamento de registro de registro OTLP para entrada de registro.

• Agentes do Logging integrados (stdout e stderr): em plataformas de computação gerenciadas, como o Google Kubernetes Engine, o Cloud Run, o Cloud Run Functions e o App Engine, o agente do Logging integrado reconhece as seguintes chaves JSON de nível superior e move os valores delas para os campos LogEntry correspondentes:

  • severity: define o campo LogEntry.severity.
  • message: define a mensagem de registro principal exibida na Análise de Registros.
  • httpRequest: define o campo LogEntry.httpRequest.
  • time ou timestamp (ou timestampSeconds e timestampNanos): define o campo LogEntry.timestamp.
  • logging.googleapis.com/insertId: define o campo LogEntry.insertId.
  • logging.googleapis.com/labels: define pares de chave-valor LogEntry.labels definidos pelo usuário.
  • logging.googleapis.com/operation: define o campo LogEntry.operation.
  • logging.googleapis.com/sourceLocation: define o campo LogEntry.sourceLocation.
  • logging.googleapis.com/trace, logging.googleapis.com/spanId e logging.googleapis.com/trace_sampled: defina os campos trace, spanId e traceSampled para vincular registros com traces.

  Todos os campos restantes no registro JSON permanecem no campo LogEntry.jsonPayload.

A seguir

• Para escolher uma estratégia de instrumentação para sua plataforma de computação, consulte Escolher uma abordagem de instrumentação.

• Para consultar e visualizar entradas de registro, consulte Ver registros usando a Análise de registros.

• Para ler entradas de registro usando a CLI gcloud, consulte Como ler entradas de registro.

• Para ler entradas de registro usando a API Logging, consulte o método entries.list.