Configurar el agente de Logging

En esta página, se proporcionan detalles sobre los parámetros de configuración personalizados y predeterminados 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 necesitan ajustes adicionales.

En la configuración predeterminada, el agente de Logging transmite registros, como los que se incluyen en la lista de registros predeterminados, a Cloud Logging. El agente se puede configurar con el objetivo 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 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 de Ruby. Consulta la lista de complementos agrupados.

El agente lee registros almacenados en los archivos de registro de la instancia de VM a través del 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 predeterminada para syslog, el complemento de entrada directa, los parámetros de 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 cuya versión es anterior a la 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: En este archivo, se incluye la configuración para especificar syslog como una entrada de registro.

• Consulta el repositorio de configuración.

Nombre de la configuración	Tipo	Predeterminado	Descripción
format	cadena	/^(?<message>(?<time>[^ ]*\s*[^ ]* [^ ]*) .*)$/	El formato del syslog.
path	cadena	/var/log/syslog	La ruta del archivo syslog.
pos_file	cadena	/var/lib/google-fluentd/pos/syslog.pos	Es la ruta de acceso al 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	Indica si se debe empezar a leer los registros desde el encabezado del archivo en vez de desde el final. Consulta la documentación de fluentd detallada.
tag	cadena	syslog	Es 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 de este complemento y del repositorio de configuración.

Nombre de la configuración	Tipo	Predeterminado	Descripción
port	int	24224	El puerto que se debe supervisar.
bind	cadena	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 de los archivos 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 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	cadena	Varía según la aplicación	Es el formato del registro. Consulta la documentación de fluentd detallada.
path	cadena	Varía según la aplicación	Es la ruta de acceso a los archivos 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	cadena	Varía según la aplicación	Es la ruta de acceso al 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	Indica si se debe empezar a leer los registros desde el encabezado del archivo en vez de desde el final. Consulta la documentación de fluentd detallada.
tag	cadena	Varía; el nombre de la aplicación.	Es la etiqueta del registro para esta entrada de registro.

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

Configuración del complemento de salida deGoogle Cloud fluentd

• Ubicaciones de los archivos 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 cuya versión es anterior a 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 deGoogle Cloud fluentd.

• Accede al repositorio de configuración.

Nombre de la configuración	Tipo	Predeterminado	Descripción
buffer_chunk_limit	cadena	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	cadena	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 suele ser 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	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 establece en true, el agente de Logging exporta los datos de telemetría interna. Consulta Telemetría del complemento de salida para obtener más información.
monitoring_type	cadena	opencensus	Es 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	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.

Configuración de la supervisión

Telemetría del complemento de salida

La opción enable_monitoring controla si el complemento de salida Google Cloud fluentd recopila su telemetría interna. Cuando se establece en true, el agente de Logging realiza un seguimiento de la cantidad de entradas de registro solicitadas para enviar a Cloud Logging y de la cantidad real de entradas de registro que Cloud Logging transfirió con éxito. Cuando se establece 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 establece en prometheus, el agente de Logging expone métricas en formato Prometheus en el extremo de Prometheus (de forma predeterminada, localhost:24231/metrics; consulta la configuración de los complementos prometheus y prometheus_monitor para obtener detalles sobre cómo personalizarlo). En las VMs 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 establece en opencensus (opción predeterminada desde la versión v1.6.25), el agente de Logging escribe directamente sus propias métricas de estado en la API de Monitoring. Esto requiere que el rol 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 de Logging escriben las siguientes métricas en la API de Monitoring en modo opencensus:

• Métrica agent.googleapis.com/agent/uptime con una etiqueta version: es el tiempo de actividad del agente de Logging.
• Métrica agent.googleapis.com/agent/log_entry_count con una etiqueta response_code: es el recuento de entradas de registro que escribe el agente de Logging.
• Métrica agent.googleapis.com/agent/log_entry_retry_count con una etiqueta response_code: es el recuento de entradas de registro que escribe el agente de Logging.
• Métrica agent.googleapis.com/agent/request_count con una etiqueta response_code: es el recuento de solicitudes a la API que envía 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:

• Métrica uptime con una etiqueta version: es el tiempo de actividad del agente de Logging.
• Métrica stackdriver_successful_requests_count con etiquetas grpc y code: es la cantidad de solicitudes exitosas enviadas a la API de Logging.
• Métrica stackdriver_failed_requests_count con etiquetas grpc y code: es la cantidad de solicitudes fallidas enviadas a la API de Logging, desglosadas por el código de error.
• Métrica stackdriver_ingested_entries_count con etiquetas grpc y code: es la cantidad de entradas de registro que transfiere la API de Logging.
• Métrica stackdriver_dropped_entries_count con etiquetas grpc y code: es la cantidad de entradas de registro que rechaza la API de Logging.
• Métrica stackdriver_retried_entries_count con etiquetas grpc y code: es la cantidad de entradas de registro que el complemento de salida de Google Cloudfluentd no pudo transferir debido a un error temporal y que se reintentaron enviar.

Configuración de los complementos prometheus y prometheus_monitor

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

• Ubicaciones de los archivos 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.

• Accede 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 de la configuración predeterminada del agente de Logging son de archivos de registro que 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.

La configuración del agente se puede personalizar con el objetivo de que sea compatible con la transferencia de registros estructurados provenientes 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 al 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	Campo LogEntry	Función del agente de Cloud Logging	Valor de ejemplo
severity	severity	El agente de Logging intenta hacer coincidir una variedad de cadenas de gravedad común, que incluye la lista de cadenas LogSeverity reconocidas por la API de Logging.	"severity":"ERROR"
message	textPayload (o parte de jsonPayload)	Es el mensaje que aparece en la línea de la entrada de registro en el Explorador de registros.	"message":"There was an error in the application." Nota: El valor 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 si detect_json no se habilitó; de lo contrario, message permanece en jsonPayload. El valor detect_json no es aplicable a entornos de registro administrados como Google Kubernetes Engine. Si la entrada de registro contiene un seguimiento de pila de excepciones, debes establecerlo 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	Es 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 de código fuente asociada a la entrada de registro, si es que existe. 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	Es 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	Es el nombre del recurso del seguimiento asociado a una entrada de registro, si es que existe. 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 ni stderr, el valor de este campo debe tener el formato projects/[PROJECT-ID]/traces/[TRACE-ID], de modo que el Explorador de registros y el lector de seguimiento lo puedan usar para agrupar entradas de registro y mostrarlas alineadas con los seguimientos. Si autoformat_stackdriver_trace es verdadero y [V] coincide con el formato de ResourceTrace traceId, el campo trace de LogEntry tendrá 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 la hora 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 la hora:

1. Busca un campo timestamp que sea un objeto JSON que incluya los campos seconds y nanos. Estos deben representar, respectivamente, una cantidad firmada de segundos de la época UTC y una cantidad no negativa 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 cadena en formato RFC 3339:

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

Cuando se encuentra información relacionada con la hora, el agente de Logging la usa para establecer el valor de LogEntry.timestamp y no la copia del registro estructurado al 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 al 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 el campo 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 de forma predeterminada, puedes personalizar el agente de Logging para enviar registros adicionales a Logging o con el objetivo de ajustar los parámetros de configuración del agente agregando 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 cuya versión es anterior a 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 de 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 para Windows. Para obtener más información sobre por qué esto es obligatorio, consulta El patrón del 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 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 quieres crear un archivo, una alternativa es agregar la información de la 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 Explorador 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 para Windows. Para obtener más información sobre por qué esto es obligatorio, consulta El patrón del 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 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 quieres crear un archivo, una alternativa es agregar la información de la 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 Explorador 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 Explorador de registros, filtra por tipo de recurso y por el logName de structured-log.

Para conocer más opciones sobre cómo personalizar el formato de entrada de los registros de 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 a través del 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 Explorador 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 la aplicación

Puedes habilitar conectores en varios lenguajes con el objetivo 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 permiten anular las etiquetas LogEntry y MonitoredResource cuando transfieres registros a Cloud Logging. Todas las entradas de registro se asocian a 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 del 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 por etiquetas diferentes. Para obtener más información, consulta 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 incluso si envías registros sin estructura.

Para obtener más información sobre cómo configurar labels, label_map y otros parámetros de configuración del agente de Logging, consulta Configura etiquetas de entrada de registro en esta página.

Modifica los registros

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

El complemento de filtro que más suele usarse 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 permiten modificar 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 te 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)

Para personalizar la configuración del agente de Logging, además de usar su configuración predeterminada, sigue 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	cadena	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	cadena	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 con 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	cadena	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 recursos supervisados y de proyectos

Las siguientes opciones de configuración 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	cadena	nil	Si se especifica, esto anula el project_id que identifica el proyecto subyacente de Google Cloud o AWS en el que se ejecuta el agente de Logging.
zone	cadena	nil	Si se especifica, anula la zona.
vm_id	cadena	nil	Si se especifica, anula el ID de la VM.
vm_name	cadena	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	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	cadena	""(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. Es opcional. Para validar el cambio de configuración, ejecuta el siguiente comando:

   sudo service google-fluentd configtest
   

3. Ejecuta el comando siguiente para reiniciar el agente:

   sudo service google-fluentd force-reload
   

Instancia de Windows

Nota: Si ejecutas una versión del agente anterior a la v1-5, no podrás agregar tus propios 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. Ejecuta los comandos siguientes en una shell de línea de comandos para reiniciar el agente:

   net stop  StackdriverLogging
   net start StackdriverLogging
   

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