Registro estructurado

En Stackdriver Logging, los registros estructurados se refieren a las entradas de registro que usan el campo jsonPayload para agregar estructura a su carga útil. Si usas la API de Stackdriver Logging o la utilidad de línea de comandos, gcloud logging, puedes controlar la estructura de tu carga útil. Si usas el agente de Stackdriver Logging para obtener tus entradas de registro, puedes especificar que el agente de Logging convierta tus cargas útiles en formato JSON. Consulta LogEntry para obtener información sobre diferentes formatos de carga útil.

Aquí hay un ejemplo de una entrada de registro, con la carga útil estructura resaltada en negrita:


        {
         insertId:  "1m9mtk4g3mwilhp"
         "jsonPayload: {
          code:  "structured-log-code"
          message:  "This is a log from the log file at test-structured-log.log"
         }
         labels: {
          compute.googleapis.com/resource_name:  "add-structured-log-resource"
         }
         logName:  "projects/my-sample-project-12345/logs/structured-log"
         receiveTimestamp:  "2018-03-21T01:53:41.118200931Z"
         resource: {
          labels: {
           instance_id:  "5351724540900470204"
           project_id:  "my-sample-project-12345"
           zone:  "us-central1-c"
          }
          type:  "gce_instance"
         }
         timestamp:  "2018-03-21T01:53:39.071920609Z"
        }

Operaciones de registro estructurado

El agente de Logging google-fluentd es una versión modificada del recolector de datos de registro Fluentd. El agente de Logging viene con la configuración Fluentd predeterminada y usa los complementos de entrada Fluentd para extraer registros de eventos desde 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 (JSON) estructuradas.

Mediante la configuración de una fuente de registro con format [PARSER_NAME], puedes aprovechar los analizadores integrados que proporciona Fluentd.

En los ejemplos de código a continuación, se muestran la configuración Fluentd, el registro de entrada y la carga útil estructura de salida, que es parte de una entrada de registro de Stackdriver Logging:

  • Configuración Fluentd:

      <source>
        @type tail
    
        format syslog # <--- This uses a predefined log format regex named
                      # `syslog`. See details at https://docs.fluentd.org/v1.0/articles/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:

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

Analizadores estándar habilitados de forma predeterminada

En la tabla debajo, 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

Consulta la sección Instalación debajo para obtener instrucciones sobre cómo habilitar el registro estructurado cuando se instala el agente de Logging.

Instalación

Para habilitar el registro estructurado, debes cambiar la configuración predeterminada del agente de Logging cuando lo instalas o lo reinstalas. Si habilitas el registro estructurado, obtienes la versión más reciente del agente y se reemplazan los archivos de configuración enumerados antes. No hay cambios en la operación del agente en sí.

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

A continuación, se brindan las instrucciones para instalar el agente con el registro estructurado habilitado:

  1. Abre una conexión de terminal en tu instancia de VM con SSH o una herramienta similar.

  2. Descarga la secuencia de comandos de instalación del agente de Logging mediante la ejecución del siguiente comando en tu instancia de VM:

        curl -sSO "https://dl.google.com/cloudagents/install-logging-agent.sh"
    
  3. Ejecuta la secuencia de comandos de instalación con el siguiente comando:

        sudo bash install-logging-agent.sh --structured
    
  4. Para verificar que la instalación se realizó con éxito, busca la entrada de registro de prueba del agente en el visor de registros.

  5. Puedes borrar la secuencia de comandos de instalación una vez que se ejecute de forma correcta.

Puedes encontrar los archivos de configuración del agente de Logging en /etc/google-fluentd/config.d/, que ahora deberían incluir Analizadores estándar habilitados de forma predeterminada.

Para obtener más información, consulta Instala el agente de Logging.

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"
  },
  ...
}

De modo alternativo, puedes configurar el agente de Logging para extraer ciertos campos al 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 se muestra arriba, contribuye al seguimiento: GCP Console presenta todos los registros para una solicitud HTTP dada 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"
    },
    ...
  }

De modo alternativo, puedes configurar el agente de Logging para extraer ciertos campos al 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 se muestra arriba, contribuye al seguimiento: GCP Console presenta todos los registros para una solicitud HTTP dada 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 de una expresión regular usada para unir los 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 visualizar sus entradas con el visor de registros, consulta Visualiza registros.

Para leer entradas de registro con el SDK o la API, consulta Lee entradas de registro.

Solución de problemas

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

¿Te sirvió esta página? Envíanos tu opinión:

Enviar comentarios sobre…

Stackdriver Logging
¿Necesitas ayuda? Visita nuestra página de asistencia.