Esta página se ha traducido con Cloud Translation API.
Switch to English

Registro estructurado

En Cloud Logging, los registros estructurados hacen referencia a entradas de registro que usan el campo jsonPayload para agregar estructura a sus cargas útiles.

Si usas la API de Cloud Logging o la herramienta de línea de comandos de gcloud, puedes controlar la estructura de tus cargas útiles. Consulta Escribe registros estructurados para ver ejemplos.

Si usas el agente de Cloud Logging para obtener tus entradas de registro, puedes especificar que el agente de Logging convierta tus cargas útiles en formato JSON.

Si usas el servicio de BindPlane para transferir registros, las cargas útiles estarán en formato JSON y estarán estructuradas según el sistema de origen. Para obtener información sobre cómo buscar y ver registros transferidos a través de BindPlane, consulta la documentación de BindPlane sobre cómo buscar datos de registro.

Usa campos especiales en cargas útiles JSON para estructurar los registros con el agente de Logging

Puedes escribir registros estructurados en Logging de las siguientes maneras:

  • Envía la estructura LogEntry completa con un jsonPayload a la API de Cloud Logging
  • Proporciona objetos JSON serializados al agente de Logging

Si usas Google Kubernetes Engine o el entorno flexible de App Engine, puedes escribir registros estructurados como objetos JSON serializados en una sola línea en stdout o stderr. Luego, el agente de Logging envía los registros estructurados a Cloud Logging como jsonPayload de la estructura LogEntry.

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

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

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

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

Campo de registro JSON LogEntry Función del agente de Cloud Logging Valor de ejemplo
severity severity El agente de Logging intenta que coincidan una variedad de strings de gravedad comunes, que incluye la lista de strings de 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: message se guarda comotextPayload Si es el único campo restante después de que el agente de Logging borre los otros campos de propósito especial.como detect_json no se habilitó; de otra maneramessage sigue enjsonPayload las rutas "a GCP". Si tu entrada de registro contiene un seguimiento de pila de excepciones, esa pila se debe establecer en este campo de registro JSON message para que se pueda analizar y guardar en Error Reporting. las rutas "a GCP".
log (solo para Google Kubernetes Engine heredado) textPayload Solo se aplica a Google Kubernetes Engine heredado: si, después de borrar campos con propósito especial, solo queda un campo de registro, ese registro 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. "times":"2020-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 del código fuente asociada con la entrada de registro, si corresponde. 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 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 Nombre del recurso del seguimiento asociado a la entrada de registro, si corresponde. Para obtener más información, consulta trace en la página LogEntry. "logging.googleapis.com/trace":"projects/my-projectid/traces/0679686673a"

Nota: Si no se escribe en stdout o stderr, el valor de este campo debe su formato es projects/[PROJECT-ID]/traces/[TRACE-ID], por lo que el Explorador de registros y el lector de seguimiento lo pueden usar para agrupar entradas de registro y mostrarlas alineadas con seguimientos. Siautoformat_stackdriver_trace es verdadero y[V] coincide con el formato deSeguimiento de recursos traceId la LogEntrytrace tiene el valor . projects/[PROJECT-ID]/traces/[V] por error.
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. El siguiente es un ejemplo de una 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"
}

El siguiente es un ejemplo de una entrada de registro resultante:

{
  "insertId": "42",
  "jsonPayload": {
    "message": "There was an error in the application",
    "times": "2019-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 de Logging

El agente de Logging google-fluentd es un empaquetado específico de Cloud Logging del colector de datos de registro de Fluentd. El agente de Logging viene con la configuración de Fluentd predeterminada y usa los complementos de entrada de Fluentd para extraer registros de eventos de fuentes externas, como archivos en disco, o analizar los registros entrantes.

Fluentd tiene una lista de analizadores compatibles que extraen registros y los convierten en cargas útiles estructuradas (JSON).

Si configuras una fuente del archivo de registro con format [PARSER_NAME], puedes aprovechar los analizadores integrados que proporciona Fluentd.

En las siguientes muestras de código, se observa la configuración de Fluentd, el registro de entrada y la carga útil estructurada de salida, que es parte de una entrada de registro de Cloud Logging:

  • Configuración de 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
    
  • Carga útil estructurada (salida):

        jsonPayload: {
            "pri": "6",
            "host": "192.168.0.1",
            "ident": "fluentd",
            "pid": "11111",
            "message": "[error] Syslog test"
        }
    

Para obtener más información sobre cómo funciona el analizador syslog, consulta la documentación de Fluentd.

Analizadores estándar habilitados de forma predeterminada

En la siguiente tabla, se incluyen los analizadores estándar incluidos en el agente si habilitas el registro estructurado:

Nombre del analizador Archivo de configuración
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

Si deseas obtener instrucciones para habilitar el registro estructurado cuando se instala el agente de Logging, consulta la sección sobre instalación.

Instalación

Para habilitar el registro estructurado, debes cambiar la configuración predeterminada del agente de Logging cuando lo instalas o lo reinstalas. Con la habilitación del registro estructurado, se reemplazan los archivos de configuración enumerados con anterioridad. No hay cambios en la operación del agente en sí.

Cuando habilitas el registro estructurado, los registros de la lista se convierten en entradas de registro con formatos distintos a los que tenían antes de que habilitaras los registros estructurados. Si los registros se exportan fuera de Cloud Logging, el cambio puede afectar a algunas aplicaciones de procesamiento posterior. En el caso de las exportaciones de BigQuery, BigQuery rechazará las entradas de registro nuevas durante el resto del día como si tuviesen un esquema incorrecto.

Si deseas obtener instrucciones para instalar el agente de Logging y habilitar el registro estructurado, consulta Instala el agente de Logging.

Puedes buscar los archivos de configuración del agente de Logging en /etc/google-fluentd/config.d/, que ahora debe incluir los analizadores estándar habilitados de forma predeterminada.

Configura el formato de registro de acceso de Apache

De forma predeterminada, el agente de Logging almacena los datos de registro de acceso de Apache en el campo jsonPayload. Por ejemplo:

{
  "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, puedes configurar el agente de Logging para que extraiga ciertos campos en el campo httpRequest. Por ejemplo:

{
  "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 el campo httpRequest, como en el ejemplo anterior, ayuda al seguimiento: Cloud Console presenta todos los registros para una determinada solicitud HTTP en una jerarquía superior-secundario.

Para configurar esta extracción, agrega lo siguiente al final de tu /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 obtener más detalles sobre cómo configurar tus entradas de registro, consulta Modifica los registros.

Configura el formato de registro de acceso de nginx

De forma predeterminada, el agente de Logging almacena los datos de registro de acceso de nginx en el campo jsonPayload. Por ejemplo:

  {
    "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, puedes configurar el agente de Logging para que extraiga ciertos campos en el campo httpRequest. Por ejemplo:

  {
    "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 el campo httpRequest, como en el ejemplo anterior, ayuda al seguimiento: Cloud Console presenta todos los registros para una determinada solicitud HTTP en una jerarquía superior-secundario.

Para configurar esta extracción, agrega lo siguiente al final de tu /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 obtener más detalles sobre cómo configurar tus entradas de registro, consulta Modifica los registros.

Escribe tu propio analizador

Si tus registros no son compatibles con los analizadores estándar, puedes escribir el tuyo. Los analizadores consisten en una expresión regular usada para unir registros y aplicar etiquetas a las partes.

En los siguientes 3 códigos de ejemplo, se muestra una línea de registro en este, una configuración con una expresión regular que indica el formato de la línea de registro y la entrada de registro transferida:

  • Una línea de registro en este:

    REPAIR CAR $500
    
  • Una configuración con una expresión regular que indica el formato de la línea 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>
    
  • La 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:  "2018-03-21T01:47:11.475065313Z"
      resource: {
        labels: {
          instance_id:  "3914079432219560274"
          project_id:  "my-sample-project-12345"
          zone:  "us-central1-c"
        }
        type:  "gce_instance"
      }
      timestamp:  "2018-03-21T01:47:05.051902169Z"
     }
    

Visualiza registros estructurados

Para buscar registros y ver entradas de registro con el Explorador de registros de Cloud Console, consulta Usa el Explorador de registros.

Para leer entradas de registro con la API o la herramienta de línea de comandos de gcloud, consulta la sección sobre cómo leer entradas de registro.

Soluciona problemas

Para solucionar problemas comunes encontrados cuando se instala o se interactúa con el agente de Logging, consulta Soluciona problemas del agente.