Registro estructurado

En este documento, se analiza el concepto de registro estructurado y los métodos para agregar estructura a los campos de carga útil de las entrada de registro. Cuando la carga útil de registro tiene el formato de un objeto JSON y ese objeto se almacena en el campo jsonPayload, la entrada de registro se denomina registro estructurado. Para estos registros, puedes crear consultas que busquen rutas de acceso JSON específicas y puedes indexar campos específicos en la carga útil de registro. Por el contrario, cuando la carga útil de registro tiene el formato de una cadena y se almacena en el campo textPayload, la entrada de registro no está estructurada. Puedes buscar en el campo de texto, pero no puedes indexar su contenido.

Para crear entradas de registro estructuradas, haz cualquiera de las siguientes acciones:

  • Llama al método de la API de entries.write y proporciona un LogEntry con formato completo.
  • Usa el comando gcloud logging write.
  • Usa una biblioteca cliente de Cloud Logging que escriba registros estructurados.
  • Usa el servicio de BindPlane.

  • Usa un agente para escribir registros:

    • Algunos Google Cloud servicios contienen un agente de registro integrado que envía los datos escritos en stdout o stderr como registros a Cloud Logging. Puedes usar este enfoque para Google Cloud servicios como Google Kubernetes Engine, el entorno flexible de App Engine y las funciones de Cloud Run.

    • En el caso de las máquinas virtuales (VM) de Compute Engine, puedes instalar y configurar el Agente de operaciones o el agente de Logging heredado y, luego, usar el agente instalado para enviar registros a Cloud Logging.

Para obtener más información sobre estos enfoques, consulta las siguientes secciones.

Escribe registros con bibliotecas cliente o la API

Puedes escribir datos de registro con las bibliotecas cliente de Cloud Logging, que llaman a la API de Cloud Logging, o llamando directamente a la API de Cloud Logging. Las bibliotecas cliente pueden simplificar la propagación de los campos JSON especiales, ya que capturan información de forma automática y proporcionan interfaces para propagar correctamente los campos. Sin embargo, para tener un control total sobre la estructura de tus cargas útiles, llama directamente a la API de Cloud Logging y pasa la estructura LogEntry completa a la API de Cloud Logging.

Para obtener más información, consulta la referencia de entries.write.

Para ver ejemplos de código, consulta Escribe registros estructurados.

Escribe registros con gcloud CLI

Puedes escribir datos de registro con gcloud CLI. La interfaz admite registros no estructurados y registros estructurados. Cuando quieras escribir un registro estructurado, proporciona al comando un objeto JSON serializado.

Para obtener una guía de inicio rápido, consulta Escribe y consulta entradas de registro con Google Cloud CLI.

Para ver ejemplos de código, consulta la gcloud logging write referencia.

Escribe registros con BindPlane

Puedes usar el servicio de BindPlane para enviar registros a Logging. Para estos registros, las cargas útiles están en formato JSON y se estructuran según el sistema de origen. Para obtener información sobre cómo buscar y ver registros transferidos con BindPlane, consulta la guía de inicio rápido de BindPlane.

Escribe registros con un agente

Para obtener registros de tus instancias de Compute Engine, puedes usar el Agente de operaciones o el agente de Cloud Logging heredado. Ambos agentes pueden recopilar métricas de aplicaciones de terceros y proporcionan compatibilidad con el registro estructurado:

  • El Agente de operaciones es el agente recomendado para recopilar la telemetría de tus instancias de Compute Engine. Este agente combina el registro y las métricas en un solo agente, proporciona una configuración basada en YAML y cuenta con registros de alta capacidad de procesamiento.

    Para obtener información sobre cómo configurar el Agente de operaciones para admitir el registro estructurado o personalizar la forma de un registro estructurado, consulta Configura el Agente de operaciones.

  • El agente de Cloud Logging heredado recopila registros. Este agente no recopila otras formas de telemetría.

El resto de esta sección es específico del agente de Logging heredado.

Agente de Logging: campos JSON especiales

El agente de Logging heredado reconoce algunos campos del objeto JSON como especiales y los extrae en la LogEntry estructura. Estos campos JSON especiales se pueden usar para configurar los siguientes campos en LogEntry:

  • severity
  • spanId
  • labels definido por el usuario
  • httpRequest

Debido a que JSON es más preciso y versátil que las líneas de texto, puedes usar objetos JSON para escribir mensajes de varias líneas y agregar metadatos.

Para crear entradas de registro estructuradas para tus aplicaciones con el formato simplificado, consulta la siguiente tabla, que enumera los campos y sus valores en JSON:

Campo de registro JSON LogEntry campo Función del agente de Cloud Logging Valor de ejemplo
severity severity El agente de Logging intenta hacer coincidir una variedad de cadenas de gravedad común, que incluye la lista de cadenas LogSeverity reconocidas por la API de Logging. "severity":"ERROR"
message textPayload (o parte de jsonPayload) El mensaje que aparece en la línea de entrada de registro en el Explorador de registros. "message":"There was an error in the application."

Nota: El valor message se guarda como textPayload si es el único campo restante después de que el agente de Logging mueve los otros campos de propósito especial y si detect_json no se habilitó; de lo contrario, message permanece en jsonPayload. El valor detect_json no es aplicable a entornos de registro administrados como Google Kubernetes Engine. Si la entrada de registro contiene un seguimiento de pila de excepciones, debes establecerlo en este campo de registro JSON message para que se pueda analizar y guardar en Error Reporting.
log (solo Google Kubernetes Engine heredado) textPayload Solo se aplica a Google Kubernetes Engine heredado. Si después de mover los campos con propósito especial solo queda un campo log, ese campo se guarda como textPayload.
httpRequest httpRequest Un registro estructurado en el formato del campo LogEntry HttpRequest. "httpRequest":{"requestMethod":"GET"}
campos relacionados con la hora timestamp Para obtener más información, consulta Campos relacionados con la hora. "time":"2025-10-12T07:20:50.52Z"
logging.googleapis.com/insertId insertId Para obtener más información, consulta insertId en la página LogEntry. "logging.googleapis.com/insertId":"42"
logging.googleapis.com/labels labels El valor de este campo debe ser un registro estructurado. Para obtener más información, consulta labels en la página LogEntry. "logging.googleapis.com/labels": {"user_label_1":"value_1","user_label_2":"value_2"}
logging.googleapis.com/operation operation El Explorador de registros también usa el valor de este campo para agrupar entradas de registro relacionadas. Para obtener más información, consulta operation en la página LogEntry. "logging.googleapis.com/operation": {"id":"get_data","producer":"github.com/MyProject/MyApplication", "first":"true"}
logging.googleapis.com/sourceLocation sourceLocation Información de ubicación de código fuente asociada a la entrada de registro, si es que existe. Para obtener más información, consulta LogEntrySourceLocation en la página LogEntry. "logging.googleapis.com/sourceLocation": {"file":"get_data.py","line":"142","function":"getData"}
logging.googleapis.com/spanId spanId Es el ID de intervalo dentro del seguimiento asociado a la entrada de registro. Para obtener más información, consulta spanId en la página LogEntry. "logging.googleapis.com/spanId":"000000000000004a"
logging.googleapis.com/trace trace Es el nombre del recurso del seguimiento asociado a una entrada de registro, si es que existe. Para obtener más información, consulta trace en la página LogEntry. "logging.googleapis.com/trace":"[TRACE_ID]"
"logging.googleapis.com/trace":"projects/my-projectid/traces/[TRACE_ID]"

Nota: Si no escribes en stdout o stderr, da formato a este campo como [TRACE_ID] o usa el formato heredado projects/[PROJECT_ID]/traces/[TRACE_ID]. Ambos formatos permiten que el Explorador de registros y el Explorador de seguimiento correlacionen los datos de registro y seguimiento. Si autoformat_stackdriver_trace es verdadero y [V] coincide con el formato de el campo traceId en el objeto ResourceTrace, el campo trace de LogEntry tiene el valor projects/[PROJECT_ID]/traces/[V].
logging.googleapis.com/trace_sampled traceSampled El valor de este campo debe ser true o false. Para obtener más información, consulta traceSampled en la página LogEntry. "logging.googleapis.com/trace_sampled": false

Para crear entradas de registro en el formato simplificado, crea una representación JSON de la entrada con los campos. Todos los campos son opcionales.

A continuación, se muestra un ejemplo de una entrada de registro JSON simplificada:

{
  "severity":"ERROR",
  "message":"There was an error in the application.",
  "httpRequest":{
    "requestMethod":"GET"
  },