Configurar el agente de Logging

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 recolector 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 con el 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.

El agente de Logging usa complementos de entrada fluentd con los cuales se recuperan y extraen registros de eventos de fuentes externas (como archivos en un disco) o analizan 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 para 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

Nota: La siguiente configuración predeterminada de syslog, como parte del paquete google-fluentd-catch-all-config, es exclusiva de los sistemas operativos Linux.

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

• Descripción: este archivo 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	bool	true	Si se debe comenzar a leer los registros desde el encabezado del archivo en vez de 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

Nota: La siguiente configuración predeterminada del complemento in_forward, como parte del paquete google-fluentd-catch-all-config, es exclusiva de los sistemas operativos Linux.

• 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

Nota: La siguiente configuración predeterminada del registro de aplicaciones de terceros, como parte del paquete google-fluentd-catch-all-config, es exclusiva de los sistemas operativos Linux.

• 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^1	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	bool	true	Si se debe comenzar a leer los registros desde el encabezado del archivo en vez de 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.

¹ Si usas la estrofa <parse>, especifica el formato del registro mediante @type.

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	bool	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	int	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	int	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	int	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	bool	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.
grpc_compression_algorithm	enum	none	Si se usa gRPC, establece qué esquema de compresión se usará. Puede ser none o gzip.
partial_success	bool	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	bool	true	Cuando se configura en true, el agente de Logging exporta telemetría interna. Consulta Telemetría del complemento de salida para obtener más detalles.
monitoring_type	string	opencensus	El tipo de supervisión. Las opciones compatibles son opencensus y prometheus. Consulta Telemetría del complemento de salida para obtener más información.
autoformat_stackdriver_trace	bool	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.

Configuración de Monitoring

Telemetría del complemento de salida

La opción enable_monitoring controla si el complemento de salida fluentd de Google Cloud recopila su telemetría interna. Cuando se configura como true, el agente de Logging realiza un seguimiento de la cantidad de entradas de registro solicitadas para enviar a Cloud Logging y la cantidad real de entradas de registro que Cloud Logging transfirió correctamente. Cuando se configura en false, el complemento de salida no recopila métricas.

La opción monitoring_type controla cómo el agente expone esta telemetría. Consulta lo siguiente para ver la lista de métricas.

Cuando se configura como prometheus, el agente de Logging expone métricas en formato Prometheus en el extremo de Prometheus (localhost:24231/metrics de forma predeterminada; consulta la configuración del complemento prometheus y prometheus_Monitor) para obtener detalles sobre cómo personalizar esto). En las VM de Compute Engine, para que esas métricas se escriban en la API de Monitoring, el agente de Monitoring también debe instalarse y ejecutarse.

Cuando se configura como opencensus (predeterminado desde v1.6.25), el agente de Logging escribe directamente sus propias métricas de estado en la API de Monitoring. Esto requiere que la función roles/monitoring.metricWriter se otorgue a la cuenta de servicio predeterminada de Compute Engine, incluso si el agente de Monitoring no está instalado.

El agente de Monitoring y el agente de Logging escriben las siguientes métricas en la API de Monitoring: modo opencensus:

• agent.googleapis.com/agent/uptime con una etiqueta version: Tiempo de actividad del agente de Logging.
• agent.googleapis.com/agent/log_entry_count con una etiqueta response_code: Conteo de las entradas de registro escritas por el agente de Logging.
• agent.googleapis.com/agent/log_entry_retry_count con una etiqueta response_code: conteo de las entradas de registro escritas por el agente de Logging.
• agent.googleapis.com/agent/request_count con una etiqueta response_code: conteo de solicitudes a la API desde el agente de Logging.

Estas métricas se describen con más detalle en la página Métricas del agente.

Además, el complemento de salida expone las siguientes métricas de Prometheus en el modo prometheus:

• uptime con una etiqueta version: Tiempo de actividad del agente de Logging.
• stackdriver_successful_requests_count con etiquetas grpc y code: La cantidad de solicitudes exitosas a la API de Logging
• stackdriver_failed_requests_count con etiquetas grpc y code: La cantidad de solicitudes fallidas a la API de Logging, desglosadas por el código de error
• stackdriver_ingested_entries_count con etiquetas grpc y code: La cantidad de entradas de registro que transfiere la API de Logging
• stackdriver_dropped_entries_count con etiquetas grpc y code: La cantidad de entradas de registro rechazadas por la API de Logging.
• stackdriver_retried_entries_count con etiquetas grpc y code: La cantidad de entradas de registro que no pudieron transferirse por el complemento de salida fluentd de Google Cloud debido a un error transitorio y se reintentaron.

Configuración del complemento prometheus y prometheus_monitor

Nota: La siguiente configuración predeterminada de supervisión es exclusiva de los sistemas operativos Linux.

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

• Descripción: en este archivo, se incluyen opciones de configuración para controlar el comportamiento de los complementos prometheus y prometheus_monitor. El complemento prometheus_monitor supervisa la infraestructura principal de Fluentd. El complemento prometheus expone las métricas, incluidas las del complemento prometheus_monitor y las del complemento google_cloud anterior, a través de un puerto local en formato Prometheus. Consulta más detalles en https://docs.fluentd.org/deployment/monitoring-prometheus.

• Ve al repositorio de configuración.

Para supervisar Fluentd, el servidor de métricas HTTP Prometheus integrado está habilitado de forma predeterminada. Puedes quitar la siguiente sección de la configuración para evitar que se inicie este extremo:

# Prometheus monitoring.
<source>
  @type prometheus
  port 24231
</source>
<source>
  @type prometheus_monitor
</source>

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, mueve cualquier clave que coincida con la siguiente tabla en el campo correspondiente del objeto LogEntry. De lo contrario, la clave se vuelve parte del campo LogEntry.jsonPayload. Este comportamiento te permite configurar campos específicos en el objeto LogEntry, que es lo que se escribe en la API de Logging. Por ejemplo, si el registro estructurado contiene una clave de severity, el agente de Logging propaga el campo LogEntry.severity.

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 strings de gravedad común, que incluye la lista de strings 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 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 detect_json no se habilitó; de lo contrario message permanece en jsonPayload. detect_json no es aplicable a entornos de registro administrados como Google Kubernetes Engine. 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 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":"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 la hay. 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	El 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 escribes en stdout o stderr, el valor de este campo debe tener el formato projects/[PROJECT-ID]/traces/[TRACE-ID], por lo que el Explorador de registros y el visor de seguimiento lo pueden usar para agrupar entradas de registro y mostrarlas alineadas con seguimientos. Si autoformat_stackdriver_trace es verdadero y [V] coincide con el formato del 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 ser true o false. Para obtener más información, consulta traceSampled en la página LogEntry.	"logging.googleapis.com/trace_sampled": false

Campos relacionados con la hora

En general, la información relacionada con el tiempo sobre una entrada de registro se almacena en el campo timestamp del objeto LogEntry:

{
insertId: "1ad8d08f-6529-47ea-832e-467f869a2da4"
...
resource: {2}
timestamp: "2023-10-30T16:33:15.505196Z"
}

Cuando la fuente de una entrada de registro son datos estructurados, el agente de Logging usa las siguientes reglas para buscar los campos en la entrada jsonPayload en busca de información relacionada con el tiempo:

1. Busca un campo timestamp que sea un objeto JSON que incluya los campos seconds y nanos, que representen, respectivamente, una cantidad firmada de segundos del ciclo de entrenamiento UTC y un número no negativo. de segundos fraccionarios:

   jsonPayload: {
     ...
     "timestamp": {
       "seconds": CURRENT_SECONDS,
       "nanos": CURRENT_NANOS
     }
   }
   

2. Si la búsqueda anterior falla, busca un par de campos timestampSeconds y timestampNanos:

   jsonPayload: {
     ...
     "timestampSeconds": CURRENT_SECONDS,
     "timestampNanos": CURRENT_NANOS
   }
   

3. Si la búsqueda anterior falla, busca un campo time que sea una string en formato RFC 3339:

   jsonPayload: {
     ...
     "time": CURRENT_TIME_RFC3339
   }
   

Cuando se encuentra información relacionada con el tiempo, el agente de Logging usa esa información para establecer el valor de LogEntry.timestamp y no copia esa información del registro estructurado en el objeto LogEntry.jsonPayload. .

Los campos relacionados con la hora que no se usan para establecer el valor del campo LogEntry.timestamp se copian del registro estructurado en el objeto LogEntry.jsonPayload. Por ejemplo, si el registro estructurado contiene un objeto JSON timestamp y un campo time, los datos en el objeto JSON timestamp se usan para establecer LogEntry.timestamp. El objeto LogEntry.jsonPayload contiene un campo time, ya que este campo no se usó para establecer el valor LogEntry.timestamp.

Personaliza la configuración del agente

Además de la lista de registros predeterminados que el agente de Logging transmite por 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 configuraciones 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

Nota: En esta sección, se incluye un ejemplo del comando de Linux. Si usas Windows, debes adaptar los pasos del comando para que use este entorno. C:\Program Files (x86)\Stackdriver\LoggingAgent\config.d: Es el directorio de configuración de terceros para Windows. Además, asegúrate de usar barras diagonales (/) en el archivo de configuración de Windows. Para obtener más información sobre por qué esto es obligatorio, consulta El patrón de comodín en la ruta de acceso no funciona en Windows.

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

   touch /tmp/test-unstructured-log.log
   

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

   sudo tee /etc/google-fluentd/config.d/test-unstructured-log.conf <<EOF
   <source>
       @type tail
       <parse>
           # 'none' indicates the log is unstructured (text).
           @type none
       </parse>
       # 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) a través de archivos de registro

Nota: En esta sección, se incluye un ejemplo del comando de Linux. Si usas Windows, debes adaptar los pasos del comando para que use este entorno. C:\Program Files (x86)\Stackdriver\LoggingAgent\config.d: Es el directorio de configuración de terceros para Windows. Además, asegúrate de usar barras diagonales (/) en el archivo de configuración de Windows. Para obtener más información sobre por qué esto es obligatorio, consulta El patrón de comodín en la ruta de acceso no funciona en Windows.

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 archivo de configuración nuevo con la etiqueta test-structured-log.conf en el directorio de configuración adicional /etc/google-fluentd/config.d:

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

• De manera dinámica, reemplaza etiquetas específicas en una entrada estructurada con etiquetas diferentes. Para obtener más información, ve a Configura etiquetas en entradas de registro estructuradas, en esta página.
• De manera estática, adjunta una etiqueta a cualquier caso de un valor. Para obtener más información, consulta Configura etiquetas de manera estática, en esta página.

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.

Opciones de configuración relacionadas con el búfer

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. Esta opción, en combinación con buffer_chunk_limit, determina el espacio máximo en el disco que fluentd necesita para el almacenamiento en búfer.
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.

Opciones de configuración relacionadas con los recursos supervisados de proyecto

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 Google Cloud 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_json^1	bool	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	bool	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	bool	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í.

¹ 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/
   

   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.

2. Opcional. Para validar el cambio de configuración, ejecuta el siguiente comando:

   sudo service google-fluentd configtest
   

3. Reinicia el agente mediante la ejecución del comando siguiente:

   sudo service google-fluentd force-reload
   

Instancia de Windows

Nota: Si ejecutas una versión del agente inferior a v1-5, no podrás agregar tus archivos de configuración. Actualiza al agente más reciente.

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.