Configura el agente

En esta página, se proporcionan detalles sobre las opciones de configuración personalizada y predeterminada del agente de Cloud Logging.

La mayoría de los usuarios no necesitan leer esta página. Lee esta página en los casos siguientes:

  • Si estás interesado en conocer los detalles técnicos específicos de la configuración del agente de Cloud Logging

  • Si deseas cambiar la configuración del agente de Cloud Logging

Configuración predeterminada

El agente de Logging google-fluentd es una versión modificada del recopilador de datos de registro fluentd. El agente de Logging viene con una configuración predeterminada; en la mayoría de los casos, no se necesita una configuración adicional.

En la configuración predeterminada, el agente de Logging transmite registros, como los que se incluyen en la lista de registros predeterminados, hacia Cloud Logging. Puedes configurar el agente a fin de que transmita registros adicionales. Para obtener más información, consulta Personaliza la configuración del agente de Logging, en esta página.

Cómo funciona el agente de Logging

El agente de Logging usa complementos de entrada fluentd para recuperar y extraer registros de eventos de fuentes externas (como archivos en un disco) o analizar registros entrantes. Los complementos de entrada se agrupan con el agente o se pueden instalar por separado como gemas Ruby; consulta la lista de complementos agrupados.

El agente lee los registros almacenados en archivos de registro en la instancia de VM mediante el complemento integrado in_tail de fluentd. Cada registro se convierte en una estructura de entrada de registro para Cloud Logging. El contenido de cada registro se registra en la carga útil de las entradas de registro, que también contienen elementos estándar como la marca de tiempo y la gravedad. El agente de Logging exige que todos los registros se etiqueten con una etiqueta de formato de string. Todas las consultas y los complementos de salida coinciden con un conjunto específico de etiquetas. Por lo general, el nombre de registro tiene el formato projects/[PROJECT-ID]/logs/[TAG]. Por ejemplo, este nombre de registro incluye la etiqueta structured-log:

    projects/my-sample-project-12345/logs/structured-log

El complemento de salida transforma cada mensaje estructurado interiorizado en una entrada de registro en Cloud Logging. La carga útil se convierte en el texto o carga útil de JSON.

En las secciones siguientes de esta página, se analiza la configuración predeterminada en detalle.

Definiciones de la configuración predeterminada

En las secciones siguientes, se describen las definiciones de configuración predeterminadas para syslog, el complemento de entrada directa, la configuración de entrada de los registros de aplicaciones de terceros (como los de la lista de registros predeterminados) y nuestro complemento de salida fluentd de Google Cloud.

Ubicación del archivo de configuración raíz

  • Linux: /etc/google-fluentd/google-fluentd.conf

    Este archivo de configuración raíz también importa todos los archivos de configuración de la carpeta /etc/google-fluentd/config.d.

  • Windows: C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf

    Si ejecutas un agente de Logging anterior a la versión v1-5, la ubicación es: C:\GoogleStackdriverLoggingAgent\fluent.conf

Configuración de syslog

  • Ubicaciones del archivo de configuración: /etc/google-fluentd/config.d/syslog.conf

  • Descripción: En este archivo, se incluye la configuración para especificar syslog como entrada de registro.

  • Consulta el repositorio de configuración.

Nombre de la configuración Tipo Predeterminado Descripción
format string /^(?<message>(?<time>[^ ]*\s*[^ ]* [^ ]*) .*)$/ El formato del syslog.
path string /var/log/syslog La ruta del archivo syslog.
pos_file string /var/lib/google-fluentd/pos/syslog.pos La ruta del archivo de posición para esta entrada de registro. fluentd registra la posición que se detectó por última vez en este archivo. Consulta la documentación de fluentd detallada.
read_from_head booleano true Especifica si se deben comenzar a leer los registros desde el encabezado del archivo en vez de hacerlo desde el final. Consulta la documentación de fluentd detallada.
tag string syslog La etiqueta del registro para esta entrada de registro.

Configuración del complemento de entrada in_forward

  • Ubicaciones del archivo de configuración:/etc/google-fluentd/config.d/forward.conf

  • Descripción: En este archivo, se incluyen opciones de configuración para el complemento de entrada in_forward fluentd. El complemento de entrada in_forward te permite pasar registros a través de un socket TCP.

  • Consulta la documentación de fluentd detallada para este complemento y el repositorio de configuración.

Nombre de la configuración Tipo Predeterminado Descripción
port int 24224 El puerto que se debe supervisar.
bind string 127.0.0.1 La dirección de vínculo que se debe supervisar. Por configuración predeterminada, solo se aceptan las conexiones de localhost. Para abrirlo, la configuración tiene que cambiar a 0.0.0.0.

Configura la entrada de registro de aplicaciones de terceros

  • Ubicaciones del archivo de configuración: /etc/google-fluentd/config.d/[APPLICATION_NAME].conf

  • Descripción: En este directorio, se incluyen archivos de configuración para especificar los archivos de registro de las aplicaciones de terceros como entradas de registro. Cada archivo, excepto syslog.conf y forward.conf, representa una aplicación (p. ej., apache.conf para la aplicación Apache).

  • Consulta el repositorio de configuración.

Nombre de la configuración Tipo Predeterminado Descripción
format string Varía por aplicación El formato del registro. Consulta la documentación de fluentd detallada.
path string Varía por aplicación La ruta del archivo de registro. Se pueden especificar varias rutas, separadas por ‘,’. *, y el formato strftime se puede incluir para agregar o quitar el archivo de visualización de manera dinámica. Consulta la documentación de fluentd detallada.
pos_file string Varía por aplicación La ruta del archivo de posición para esta entrada de registro. fluentd registra la posición que se detectó por última vez en este archivo. Consulta la documentación de fluentd detallada.
read_from_head booleano true Especifica si se deben comenzar a leer los registros desde el encabezado del archivo en vez de hacerlo desde el final. Consulta la documentación de fluentd detallada.
tag string Varía; el nombre de la aplicación. La etiqueta del registro para esta entrada de registro.

Configura el complemento de salida fluentd de Google Cloud

  • Ubicaciones del archivo de configuración:

    • Linux: /etc/google-fluentd/google-fluentd.conf
    • Windows: C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf

      Si ejecutas un agente de Logging antes de la v1-5, la ubicación es: C:\GoogleStackdriverLoggingAgent\fluent.conf

  • Descripción: En este archivo se incluyen opciones de configuración para controlar el comportamiento del complemento de salida fluentd de Google Cloud.

  • Ve al repositorio de configuración.

Nombre de la configuración Tipo Predeterminado Descripción
buffer_chunk_limit string 512KB A medida que ingresan los registros, aquellos que no se pueden escribir en componentes descendentes lo suficientemente rápido se envían a una cola de fragmentos. Esta configuración establece el límite de tamaño de cada fragmento. De forma predeterminada, establecemos el límite de los fragmentos a fin de evitar exceder el tamaño recomendado para los fragmentos, que es 5 MB por solicitud de escritura en la API de Logging. Las entradas de registro en la solicitud a la API pueden ser entre 5 y 8 veces más grandes que el tamaño de registro original con todos los metadatos adicionales adjuntos. Un fragmento de búfer se limpia si se cumplen una o más de las siguientes condiciones:
1. Se activa flush_interval.
2. El tamaño del búfer alcanza buffer_chunk_limit.
flush_interval string 5s A medida que ingresan los registros, aquellos que no se pueden escribir en componentes descendentes lo suficientemente rápido se envían a una cola de fragmentos. La configuración establece cuánto tiempo tenemos antes de que se limpie un búfer de fragmento. Un fragmento de búfer se limpia si se cumplen una o más de las siguientes condiciones:
1. Se activa flush_interval.
2. El tamaño del búfer alcanza buffer_chunk_limit.
disable_retry_limit booleano false Aplica un límite en la cantidad de reintentos de limpiezas fallidas de los fragmentos de búfer. Consulta las especificaciones detalladas en retry_limit, retry_wait y max_retry_wait.
retry_limit número entero 3 Cuando falla la limpieza de un fragmento de búfer, fluentd vuelve a intentarlo más tarde de forma predeterminada. Esta configuración establece cuántos reintentos se deben realizar antes de descartar un fragmento de búfer problemático.
retry_wait número entero 10s Cuando falla la limpieza de un fragmento de búfer, fluentd vuelve a intentarlo más tarde de forma predeterminada. Esta configuración establece el intervalo de espera en segundos antes del primer reintento. El intervalo de espera se duplica en cada reintento siguiente (20 s, 40 s, etc.) hasta que se alcance retry_ limit o max_retry_wait.
max_retry_wait número entero 300 Cuando falla la limpieza de un fragmento de búfer, fluentd vuelve a intentarlo más tarde de forma predeterminada. El intervalo de espera se duplica en cada reintento siguiente (20 s, 40 s, etc.). Esta configuración establece el máximo de intervalos de espera en segundos. Si el intervalo de espera alcanza ese límite, la duplicación se detiene.
num_threads int 8 La cantidad de limpiezas de registro simultáneas que se pueden procesar por el complemento de salida.
use_grpc booleano true Especifica si se debe usar gRPC en vez de REST o JSON para comunicarte con la API de Logging. Con gRPC habilitado, el uso de la CPU en general es más bajo.
partial_success booleano true Si es compatible con el éxito parcial de la transferencia de registros. Si es true, las entradas de registro no válidas de un conjunto completo se descartan y las válidas se transfieren de manera correcta a la API de Logging. Si es false, el conjunto completo se descarta si contiene entradas de registro no válidas.
enable_monitoring booleano true Cuando se configura como true, el agente de Logging expone dos métricas: una métrica del recuento de solicitudes que registra el número de entradas de registro solicitadas para enviar a Cloud Logging y un recuento de entradas transferidas que registra el número real de entradas de registro que Cloud Logging transfirió de forma correcta. Cuando es false, estas métricas no se exponen.
monitoring_type string prometheus El tipo de supervisión. La única opción en la actualidad es prometheus, pero es posible que se admitan otras opciones en el futuro. Si enable_monitoring es true y monitoring_type es prometheus, el agente de Logging expone algunas métricas locales en formato Prometheus en localhost:24231/metrics. Consulta los detalles.
autoformat_stackdriver_trace booleano true Cuando se establece en true, el seguimiento se vuelve a formatear si el valor del campo de carga útil estructurada logging.googleapis.com/trace coincide con el formato traceId de ResourceTrace. Para obtener más información sobre el formateo automático, consulta Campos especiales en cargas útiles estructuradas, en esta página.

Procesa cargas útiles

La mayoría de los registros compatibles en la configuración predeterminada del agente de Logging son de archivos de registro y se transfieren como cargas útiles sin estructura (de texto) en las entradas de registro.

La única excepción es que el complemento de entrada in_forward, que también está habilitado de forma predeterminada, solo acepta registros estructurados y los transfiere como cargas útiles estructuradas (JSON) en las entradas de registro. Para obtener más información, consulta Transmite registros estructurados (JSON) a través del complemento in_forward, en esta página.

Cuando la línea de registro es un objeto JSON serializado y la opción detect_json está habilitada, el complemento de salida transforma la entrada de registro en una carga útil estructurada (JSON). Esta opción está habilitada de forma predeterminada en las instancias de VM que se ejecutan en el entorno flexible de App Engine y en Google Kubernetes Engine. Esta opción no está habilitada de forma predeterminada en las instancias de VM que se ejecutan en el entorno estándar de App Engine. Cualquier JSON analizado con la opción detect_json habilitada siempre se transfiere como jsonPayload.

Puedes personalizar la configuración del agente a fin de que sea compatible con la transferencia de registros estructurados de recursos adicionales. Consulta Transmite registros estructurados (JSON) a Cloud Logging para obtener más detalles.

La carga útil de los registros transmitidos por un agente de Logging con configuración personalizada puede ser un solo mensaje de texto no estructurado (textPayload) o un mensaje JSON estructurado (jsonPayload).

Campos especiales en cargas útiles estructuradas

Cuando el agente de Logging recibe un registro estructurado, trata a los campos siguientes de manera especial y te permite establecer campos específicos en el objeto LogEntry que se escribe en la API de Logging.

Todos los campos de la siguiente tabla se quitan de la carga útil si están presentes.

Campo de registro JSON Campo LogEntry Función del agente de Logging
severity severity El agente de Logging intenta que coincidan una variedad de strings de gravedad comunes. Eso incluye la lista de strings LogSeverity reconocidas por la API de Logging.
message textPayload (o parte de jsonPayload) message se guarda como textPayload si es el único campo restante después de que el agente de Logging borre los otros campos de propósito especial y si detect_json no se habilitó; de lo contrario, message permanece en jsonPayload. 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.
log (solo Google Kubernetes Engine heredado) textPayload Solo se aplica a Google Kubernetes Engine heredado: si después de quitar los campos con propósito especial solo queda un campo log, log se guarda como textPayload.
httpRequest httpRequest Este es un registro estructurado en el formato del campo LogEntry HttpRequest.
campos relacionados con la hora timestamp Para obtener más información, consulta los campos relacionados con la hora en esta página.
logging.googleapis.com/insertId insertId
logging.googleapis.com/labels labels El valor de este campo debe ser un registro estructurado.
logging.googleapis.com/operation operation El visor de registros también usa el valor de este campo para agrupar entradas de registro relacionadas.
logging.googleapis.com/sourceLocation sourceLocation Este es un registro estructurado en el formato del campo LogEntry LogEntrySourceLocation.
logging.googleapis.com/spanId spanId
logging.googleapis.com/trace trace El valor de este campo debe tener el formato projects/[PROJECT-ID]/traces/[TRACE-ID], de modo que el visor de registros y el lector de seguimiento lo puedan usar para agrupar entradas de registro y mostrarlas alineadas con seguimientos. Si autoformat_stackdriver_trace es true y [V] coincide con el formato traceId de 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 tener el formato true o false.

Los demás campos de registro estructurado formarán parte de jsonPayload. En el caso de que no exista detect_json, si solo queda un campo message, el valor de ese campo se almacena como textPayload en la entrada de registro.

Campos relacionados con la hora

El agente de Logging puede recibir y procesar campos relacionados con la hora en varios formatos JSON. Si alguna de las representaciones de marca de tiempo JSON siguientes está presente en un registro estructurado, el agente de Logging borra los campos de jsonPayload y los contrae en una sola representación en el campo timestamp en el objeto LogEntry:

  • jsonPayload contiene un campo timestamp que incluye los campos seconds y nanos, estos representan un número firmado de segundos del ciclo de entrenamiento UTC y un número no negativo de segundos fraccionarios:

    {
      "timestamp": {
        "seconds": CURRENT_SECONDS,
        "nanos": CURRENT_NANOS
      }
    }
    
  • jsonPayload contiene los campos timestampSeconds y timestampNanos:

    {
       "timestampSeconds": CURRENT_SECONDS,
       "timestampNanos": CURRENT_NANOS
    }
    
  • jsonPayload contiene un campo time que contiene la misma información de segundos, escrita como una string, como se define en RFC 3339:

    {
        "time": CURRENT_TIME_RFC3339
    }
    

Una vez que el agente de Logging detecta una representación de marca de tiempo, no se produce ninguna operación de borrado más relacionada con marcas de tiempo, aun si existieran representaciones de formatos aceptables adicionales en el registro estructurado.

Personaliza la configuración del agente

Además de la lista de registros predeterminados que el agente de Logging transmite según la configuración predeterminada, puedes personalizar el agente de Logging para enviar registros adicionales a Logging o con el fin de ajustar la configuración del agente mediante más parámetros de configuración de entrada.

Las definiciones de configuración en estas secciones se aplican solo al complemento de salida fluent-plugin-google-cloud y especifican cómo los registros se transforman y se transfieren a Cloud Logging.

  • Ubicaciones del archivo de configuración principal:

    • Linux: /etc/google-fluentd/google-fluentd.conf
    • Windows: C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf

      Si ejecutas un agente de Logging antes de la v1-5, la ubicación es: C:\GoogleStackdriverLoggingAgent\fluent.conf

  • Descripción: este archivo incluye opciones de configuración para controlar el comportamiento del complemento de salida fluent-plugin-google-cloud.

  • Consulta el repositorio de configuración.

Transmite registros desde salidas adicionales

Puedes personalizar el agente de Logging para que envíe registros adicionales a Logging cuando agrega configuraciones de entrada.

Transmite registros sin estructura (texto) por medio de archivos de registro

  1. Crea un archivo de registro desde el símbolo del sistema de Linux:

    touch /tmp/test-unstructured-log.log
    
  2. Crea un nuevo archivo de configuración con la etiqueta test-unstructured-log.conf en el directorio de configuración de terceros /etc/google-fluentd/config.d:

    sudo tee /etc/google-fluentd/config.d/test-unstructured-log.conf <<EOF
    <source>
        @type tail
        # Format 'none' indicates the log is unstructured (text).
        format none
        # The path of the log file.
        path /tmp/test-unstructured-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-unstructured-log.pos
        read_from_head true
        # The log tag for this log input.
        tag unstructured-log
    </source>
    EOF
    

    Si no deseas crear un archivo nuevo, una alternativa es agregar la información de configuración a un archivo de configuración existente.

  3. Reinicia el agente para aplicar los cambios en la configuración:

    sudo service google-fluentd restart
    
  4. Genera un registro en el archivo de registro:

    echo 'This is a log from the log file at test-unstructured-log.log' >> /tmp/test-unstructured-log.log
    
  5. Verifica el visor de registros para ver la entrada de registro transferida:

      {
       insertId:  "eps2n7g1hq99qp"
       labels: {
        compute.googleapis.com/resource_name:  "add-unstructured-log-resource"
       }
       logName:  "projects/my-sample-project-12345/logs/unstructured-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"
       }
       textPayload:  "This is a log from the log file at test-unstructured-log.log"
       timestamp:  "2018-03-21T01:47:05.051902169Z"
      }
    

Transmite registros estructurados (JSON) por medio de archivos de registro

Puedes configurar el agente de Logging para que le exija a cada entrada de registro que determinadas entradas estén estructuradas. También puedes personalizar el agente de Logging para transferir el contenido con formato JSON desde un archivo de registro. Cuando el agente está configurado para transferir el contenido JSON, la entrada debe formatearse a fin de que cada objeto JSON esté en una línea nueva:

    {"name" : "zeeshan", "age" : 28}
    {"name" : "reeba", "age" : 15}

Para configurar el agente de Logging a fin de transferir el contenido con formato JSON, haz lo siguiente:

  1. Crea un archivo de registro desde el símbolo del sistema de Linux:

    touch /tmp/test-structured-log.log
    
  2. Crea un nuevo archivo de configuración con la etiqueta test-structured-log.conf en el directorio de configuración de terceros /etc/google-fluentd/config.d:

    sudo tee /etc/google-fluentd/config.d/test-structured-log.conf <<EOF
    <source>
        @type tail
        # Format 'JSON' indicates the log is structured (JSON).
        format json
        # 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>
     EOF
    

    Si no deseas crear un archivo nuevo, una alternativa es agregar la información de configuración a un archivo de configuración existente.

  3. Reinicia el agente para aplicar los cambios en la configuración:

    sudo service google-fluentd restart
    
  4. Genera un registro en el archivo de registro:

    echo '{"code": "structured-log-code", "message": "This is a log from the log file at test-structured-log.log"}' >> /tmp/test-structured-log.log
    
  5. Verifica el visor de registros para ver la entrada de registro transferida:

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

    En el visor de registros, filtra por tipo de recurso y por el logName structured-log.

A fin de obtener más opciones para personalizar el formato de entrada de registro en aplicaciones de terceros comunes, consulta Formatos de registro comunes y cómo analizarlos.

Transmite registros estructurados (JSON) a través del complemento in_forward

Además, puedes enviar registros a través del complemento fluentd in_forward. fluentd-cat es una herramienta integrada que ayuda a enviar registros al complemento in_forward con facilidad. La documentación de fluentd contiene más detalles sobre esta herramienta.

Para enviar registros mediante el complemento fluentd in_forward, lee las siguientes instrucciones:

  1. Ejecuta el siguiente comando en la VM con el agente de Logging instalado:

     $ echo '{"code": "send-log-via-fluent-cat", "message": "This is a log from in_forward plugin."}' | /opt/google-fluentd/embedded/bin/fluent-cat log-via-in-forward-plugin
    
  2. Verifica el visor de registros para ver la entrada de registro transferida:

      {
       insertId:  "1kvvmhsg1ib4689"
       jsonPayload: {
        code:  "send-log-via-fluent-cat"
        message:  "This is a log from in_forward plugin."
       }
       labels: {
        compute.googleapis.com/resource_name:  "add-structured-log-resource"
       }
       logName:  "projects/my-sample-project-12345/logs/log-via-in-forward-plugin"
       receiveTimestamp:  "2018-03-21T02:11:27.981020900Z"
       resource: {
        labels: {
         instance_id:  "5351724540900470204"
         project_id:  "my-sample-project-12345"
         zone:  "us-central1-c"
        }
        type:  "gce_instance"
       }
       timestamp:  "2018-03-21T02:11:22.717692494Z"
      }
    

Transmite registros estructurados (JSON) desde el código de aplicación

Puedes habilitar los conectores en varios lenguajes a fin de enviar registros estructurados desde el código de la aplicación. Para obtener más información, revisa la documentación de fluentd. Estos conectores se compilan en función del complemento in_forward.

Configura etiquetas de entrada de registro

Las siguientes opciones de configuración te permiten anular las etiquetas LogEntry y MonitoredResource cuando transfieres registros a Cloud Logging. Todas las entradas de registro se asocian con recursos supervisados. Para obtener más información, consulta la lista de tipos de recursos supervisados de Cloud Logging.

Nombre de la configuración Tipo Predeterminado Descripción
label_map hash nil label_map (especificado como un objeto JSON) es un conjunto desordenado de nombres de campo fluentd cuyos valores se envían como etiquetas en lugar de hacerlo como parte de la carga útil estructurada. Cada entrada en el mapa es un par {field_name: label_name}. Cuando se encuentra field_name (como lo analiza el complemento de entrada), se agrega una etiqueta con el label_name correspondiente a la entrada del registro. El valor del campo se usa como el valor de la etiqueta. El mapa te brinda flexibilidad adicional a fin de especificar nombres de etiquetas, incluida la capacidad de usar caracteres que no se permiten como parte de los nombres de campo fluentd. Si deseas ver un ejemplo, ve a Configura etiquetas en entradas de registro estructuradas.
labels hash nil labels (especificado como objeto JSON) es un conjunto de etiquetas personalizadas que se proporcionan en el momento de la configuración. Te permite incorporar información ambiental adicional en cada mensaje o personalizar etiquetas que de otro modo se detectan de forma automática. Cada entrada en el mapa es un par {label_name: label_value}.

El complemento de salida del agente de Logging es compatible con tres formas de configurar etiquetas LogEntry:

Configura etiquetas en entradas de registro estructuradas

Supongamos que escribes una carga útil de entrada de registro estructurada como la que se muestra a continuación:

{ "message": "This is a log message", "timestamp": "Aug 10 20:07:00", "env": "production" }

Supongamos también que deseas traducir el campo de la carga útil env a una etiqueta de metadatos environment. Para ello, debes agregar lo siguiente a la configuración del complemento de salida en el archivo de configuración principal (/etc/google-fluentd/google-fluentd.conf en Linux o C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf en Windows):

  # Configure all sources to output to Cloud Logging
  <match **>
    type google_cloud
    label_map {
      "env": "environment"
    }
    ...
  </match>

La configuración label_map aquí reemplaza la etiqueta env en la carga útil por environment, por lo que la entrada de registro resultante tendrá una etiqueta environment con el valor production.

Configura etiquetas de manera estática

Si no tienes esta información en la carga útil y solo quieres agregar una etiqueta de metadatos estática llamada environment, agrega lo siguiente a la configuración del complemento en el archivo de configuración principal (/etc/google-fluentd/google-fluentd.conf en Linux o C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf en Windows):

  # Configure all sources to output to Cloud Logging
  <match **>
    type google_cloud
    labels {
      "environment": "production"
    }
    ...
  </match>

En este caso, en lugar de usar un mapa para reemplazar una etiqueta por otra, usamos una configuración labels a fin de adjuntar una etiqueta con un valor literal dado a una entrada de registro, sin importar si la entrada ya tiene una etiqueta o no. Este método se puede usar aun si envías registros sin estructura.

Para obtener más información sobre cómo configurar labels, label_map y otras opciones de configuración del agente de Logging, consulta Configura etiquetas de entrada de registro.

Modifica los registros

Fluentd proporciona complementos de filtro integrados que se pueden usar para modificar las entradas de registro.

El complemento de filtro que más se usa es filter_record_transformer. Te permite ejecutar las siguientes acciones:

  • Agregar campos nuevos a entradas de registro
  • Actualizar campos en entradas de registro
  • Borrar campos de entradas de registro

Algunos complementos de salida también te permiten modificar las entradas de registro. El complemento de salida fluent-plugin-record-reformer proporciona una funcionalidad similar al complemento de filtro filter_record_transformer, excepto que también te permite modificar etiquetas de registro. Se espera un uso de recursos mayor con este complemento: cada vez que se actualiza una etiqueta de registro, se genera una entrada de registro nueva con una etiqueta nueva. Ten en cuenta que el campo tag de la configuración es obligatorio; también recomendamos que modifiques este campo para evitar ingresar en un bucle muerto.

El complemento de salida fluent-plugin-detect-exceptions analiza una transmisión de registro no estructurada (texto) o registros con formato JSON, para seguimientos de pila de excepciones de varias líneas. Si una secuencia consecutiva de entradas de registro forma un seguimiento de pila de excepción, las entradas de registro se reenvían como un mensaje de registro único y combinado. De lo contrario, la entrada de registro se reenvía como en el estado en que se estaba.

Definiciones de configuración avanzadas (no predeterminadas)

Si deseas personalizar la configuración de tu agente de Logging, en lugar de usar su configuración predeterminada, continúa leyendo esta página.

Las siguientes opciones de configuración te permiten ajustar el mecanismo interno de almacenamiento en búfer del agente de Logging.

Nombre de la configuración Tipo Predeterminado Descripción
buffer_type string buf_memory Los registros que no se pueden escribir en la API de Logging lo suficientemente rápido se envían a un búfer. El búfer se puede encontrar en la memoria o en archivos reales. Valor recomendado: buf_file. El valor predeterminado buf_memory es rápido, pero no persistente. Existe un riesgo de perder registros. Si buffer_type es buf_file, también se debe especificar buffer_path.
buffer_path string Especificado por el usuario La ruta en la que están almacenados los fragmentos de búfer. Este parámetro es obligatorio si buffer_type es file. Esta configuración debe ser única para evitar una condición de carrera.
buffer_queue_limit int 64 Especifica la longitud del límite de la cola del fragmento. Cuando la cola de búfer alcanza esta cantidad de fragmentos, el comportamiento del búfer se controla mediante buffer_queue_full_action. De forma predeterminada, genera excepciones.
buffer_queue_full_action string exception Controla el comportamiento del búfer cuando la cola del búfer está completa. Valores posibles:
1. exception: Arroja BufferQueueLimitError cuando la cola está completa. La forma en que se controla BufferQueueLimitError depende de los complementos de entrada. Por ejemplo, el complemento de entrada in_tail deja de leer líneas nuevas mientras que el complemento de entrada in_forward muestra un error.
2. block: Este modo detiene el subproceso de complemento de entrada hasta que la condición completa del búfer se resuelva. Esta acción es útil para casos prácticos por lotes. fluentd no recomienda usar la acción de bloqueo para evitar BufferQueueLimitError. Si se genera el error BufferQueueLimitError con frecuencia, significa que la capacidad de destino es insuficiente para tu tráfico.
3. drop_oldest_chunk: Este modo descarta los fragmentos más antiguos.

Las siguientes opciones de configuración te permiten especificar de forma manual un proyecto y ciertos campos del objeto MonitoredResource. El agente de Logging recopila estos valores de forma automática; no se recomienda que los especifiques de forma manual.

Nombre de la configuración Tipo Predeterminado Descripción
project_id string nil Si se especifica, esto anula el project_id que identifica el proyecto de GCP o AWS subyacente en el que se ejecuta el agente de Logging.
zone string nil Si se especifica, anula la zona.
vm_id string nil Si se especifica, anula el ID de la VM.
vm_name string nil Si se especifica, anula el nombre de la VM.

Otras opciones de configuración de complemento de salida

Nombre de la configuración Tipo Predeterminado Descripción
detect_json1 booleano false Especifica si se debe intentar detectar si el registro es una entrada de registro de texto con contenido JSON que necesita analizarse. Si esta opción es true y se detecta una entrada de registro no estructurada (de texto) en formato JSON, se analizará y se enviará como una carga útil estructurada (JSON).
coerce_to_utf8 booleano true Si permitir caracteres que no sean UTF-8 en registros de usuario. Si se configura como true, cualquier carácter que no sea UTF-8 se reemplazará por la string que especifica non_utf8_replacement_string. Si se configura como false, cualquier carácter que no sea UTF-8 activará el error del complemento.
require_valid_tags booleano false Especifica si se deben rechazar entradas de registro con etiquetas no válidas. Si esta opción se configura como false, las etiquetas se validan mediante la conversión de cualquier etiqueta que no sea una string en una string, además del descarte de cualquier carácter que no sea UTF-8 o que no sea válido.
non_utf8_replacement_string string ""(espacio) Si coerce_to_utf8 se configura como true, todo carácter que no sea UTF-8 se reemplazará por la string especificada aquí.

1 Esta función está habilitada de forma predeterminada en las instancias de VM que se ejecutan en el entorno flexible de App Engine y en Google Kubernetes Engine.

Aplica una configuración de agente personalizada

Personalizar el agente de Logging te permite agregar tus archivos de configuración fluentd:

Instancia de Linux

  1. Copia tus archivos de configuración en el directorio siguiente:

    /etc/google-fluentd/config.d/
    
  2. Reinicia el agente mediante la ejecución del siguiente comando:

    sudo service google-fluentd force-reload
    

La secuencia de comandos de instalación del agente de Logging propaga este directorio con los archivos de configuración genéricos predeterminados. Para obtener más información, consulta Obtén el código fuente del agente de Logging.

Instancia de Windows

  1. Copia tus archivos de configuración en el subdirectorio config.d de tu directorio de instalación de agente. Si aceptaste el directorio de instalación predeterminado, ese directorio es el siguiente:

    C:\Program Files (x86)\Stackdriver\LoggingAgent\config.d\
    
  2. Reinicia el agente mediante la ejecución de los comandos siguientes en una línea de comandos de shell:

    net stop  StackdriverLogging
    net start StackdriverLogging
    

Para obtener más información sobre los archivos de configuración fluentd, consulta la documentación de la sintaxis del archivo de configuración de fluentd.