Almacenamiento de registros estructurado

En este documento se explica el concepto de registro estructurado y los métodos para añadir estructura a los campos de carga útil de las entradas de registro. Cuando la carga útil del 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. En estos registros, puede crear consultas que busquen rutas JSON específicas e indexar campos concretos en la carga útil del registro. Por el contrario, si la carga útil del 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 lo siguiente:

• Llama al método de API entries.write y proporciona un LogEntry con el formato completo.
• Usa el comando gcloud logging write.

• Usa una biblioteca de cliente de Cloud Logging que escriba registros estructurados.

• Usar el servicio 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 de Compute Engine, puede instalar y configurar el agente de operaciones o el agente de Logging antiguo y, a continuación, usar el agente instalado para enviar registros a Cloud Logging.

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

Escribir registros mediante bibliotecas de cliente o la API

Puedes escribir datos de registro mediante las bibliotecas de cliente de Cloud Logging, que llaman a la API de Cloud Logging, o llamando directamente a la API de Cloud Logging. Las bibliotecas de cliente pueden simplificar el proceso de rellenar los campos JSON especiales. Para ello, capturan automáticamente cierta información y proporcionan interfaces para rellenar los campos de forma adecuada. Sin embargo, para tener un control total sobre la estructura de tus cargas útiles, llama directamente a la API Cloud Logging y transfiere la estructura LogEntry completa a la API Cloud Logging.

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

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

Escribir registros con gcloud CLI

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

Para ver una guía de inicio rápido, consulta Escribir y consultar entradas de registro con la CLI de Google Cloud.

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

Escribir registros con BindPlane

Puedes usar el servicio BindPlane para enviar registros a Logging. En 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 encontrar y ver los registros insertados mediante BindPlane, consulta la guía de inicio rápido de BindPlane.

Escribir registros con un agente

Para obtener los registros de tus instancias de Compute Engine, puedes usar el agente de Ops o el agente de Cloud Logging antiguo. Ambos agentes pueden recoger métricas de aplicaciones de terceros y admiten el registro estructurado:

• El Agente de operaciones es el agente recomendado para recoger 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 ofrece un registro de alto rendimiento.

  Para obtener información sobre cómo configurar el agente de operaciones para que admita el registro estructurado o para personalizar el formato de un registro estructurado, consulta Configurar el agente de operaciones.

• El agente de Cloud Logging antiguo recoge registros. Este agente no recoge otras formas de telemetría.

El resto de esta sección se refiere específicamente al agente de Logging antiguo.

Agente de Logging: campos JSON especiales

El agente de registro antiguo reconoce algunos campos del objeto JSON como especiales y los extrae en la estructura LogEntry. Estos campos JSON especiales se pueden usar para definir 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 añadir metadatos.

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

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

A continuación, se muestra un ejemplo de la 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 de Logging: configuración

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

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

Si configuras una fuente de registro con format [PARSER_NAME], puedes usar los analizadores integrados que proporciona Fluentd. Para obtener información sobre cómo configurar el agente de Logging antiguo, consulta el artículo Configurar el agente de Logging.

En los siguientes ejemplos de código se muestran la configuración de Fluentd, el registro de entrada y la carga útil estructurada de salida, que forma 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 detallada de Fluentd.

Agente de registro: analizadores estándar habilitados de forma predeterminada

En la siguiente tabla se incluyen los analizadores estándar que se incluyen en el agente si habilita el registro estructurado:

Para obtener instrucciones sobre cómo habilitar el registro estructurado al instalar el agente de registro antiguo, consulta la sección Instalación.

Agente de Logging: instalación

Para habilitar el registro estructurado, debes cambiar la configuración predeterminada del agente de Logging antiguo al instalarlo o reinstalarlo. Si habilitas el registro estructurado, se sustituirán los archivos de configuración que se han indicado anteriormente, pero no cambiará el funcionamiento del agente.

Cuando habilitas el registro estructurado, los registros de la lista se convierten en entradas de registro con formatos diferentes a los que tenían antes de habilitar el registro estructurado. Si los registros se están enviando a destinos que no son de Logging, el cambio podría afectar a cualquier aplicación de posprocesamiento. Por ejemplo, si enruta los registros a BigQuery, BigQuery rechaza las nuevas entradas de registro durante el resto del día porque tienen un esquema incorrecto.

Para obtener instrucciones sobre cómo instalar el agente de Logging antiguo y habilitar el registro estructurado, consulta el artículo Instalar el agente de Logging.

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

Agente de Logging: configurar el formato del registro de acceso de Apache

De forma predeterminada, el agente de registro antiguo 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"
  },
  ...
}

También puedes configurar el agente de Logging antiguo para que extraiga determinados 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 en el ejemplo anterior, ayuda a la monitorización: Google Cloud la consola presenta todos los registros de una solicitud HTTP determinada en una jerarquía de elementos principales y secundarios.

Para configurar esta extracción, añade 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 información sobre cómo configurar las entradas de registro, consulta Modificar registros.

Agente de Logging: configurar el formato del registro de acceso de nginx

De forma predeterminada, el agente de registro antiguo 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"
  },
  ...
}

También puedes configurar el agente de Logging antiguo para que extraiga determinados 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 en el ejemplo anterior, ayuda a la monitorización: Google Cloud la consola presenta todos los registros de una solicitud HTTP determinada en una jerarquía de elementos principales y secundarios.

Para configurar esta extracción, añade 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 información sobre cómo configurar las entradas de registro, consulta Modificar registros.

Escribir tu propio analizador

Si los analizadores estándar no admiten tus registros, puedes escribir tu propio analizador. Los analizadores constan de una expresión regular que se usa para buscar coincidencias en los registros de registro y aplicar etiquetas a las partes.

En los siguientes ejemplos de código se muestra una línea de registro en el registro, una configuración con una expresión regular que indica el formato de la línea de registro y la entrada de registro almacenada:

• Una línea de registro en el registro:

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

Solucionar problemas

Para solucionar problemas habituales que se producen al instalar o interactuar con el agente de Logging antiguo, consulta Solucionar problemas del agente.

Siguientes pasos

• Para consultar y ver entradas de registro, consulta Ver registros con el Explorador de registros.

• Para leer entradas de registro con Google Cloud CLI, consulta el artículo sobre cómo leer entradas de registro.

• Para leer entradas de registro mediante la API Logging, consulta el método entries.list.