Configurar el agente de Logging

En esta página se proporcionan detalles sobre las configuraciones predeterminadas y personalizadas del agente de Cloud Logging.

La mayoría de los usuarios no tienen que leer esta página. Lee esta página si:

• Quieres conocer los detalles técnicos de la configuración del agente de Cloud Logging.

• Quieres cambiar la configuración del agente de Cloud Logging.

Configuración predeterminada

El agente de registro google-fluentd es una versión modificada del recopilador de datos de registro fluentd. El agente de Logging incluye una configuración predeterminada. En la mayoría de los casos, no es necesario realizar ninguna configuración adicional.

En su configuración predeterminada, el agente de Logging transmite los registros, tal como se indica en la lista de registros predeterminados, a Cloud Logging. Puedes configurar el agente para que transmita registros adicionales. Para obtener más información, consulta la sección Personalizar la configuración del agente de registro de esta página.

El agente de Logging usa fluentd plugins de entrada para recuperar y extraer registros de eventos de fuentes externas, como archivos en el disco, o para analizar los registros de eventos entrantes. Los complementos de entrada se incluyen con el agente o se pueden instalar por separado como gemas de Ruby. Consulta la lista de complementos incluidos.

El agente lee los registros de registro almacenados en archivos de registro de la instancia de VM a través del complemento in_tail integrado de fluentd. Cada registro se convierte en una estructura de entrada de registro para Cloud Logging. El contenido de cada registro se almacena principalmente en la carga útil de las entradas de registro, pero estas también contienen elementos estándar, como una marca de tiempo y una gravedad. El agente Logging requiere que cada registro de registro se etiquete con una etiqueta de formato de cadena. Todas las consultas y los complementos de salida coinciden con un conjunto específico de etiquetas. El nombre del registro suele seguir 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 internalizado en una entrada de registro de Cloud Logging. La carga útil se convierte en el texto o la carga útil de JSON.

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

Definiciones de configuración predeterminadas

En las siguientes secciones se describen las definiciones de configuración predeterminadas de syslog, el complemento de entrada de reenvío, las configuraciones 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 estás ejecutando un agente de Logging anterior a la versión 1-5, la ubicación es: C:\GoogleStackdriverLoggingAgent\fluent.conf

Configuración de Syslog

Nota: La siguiente configuración predeterminada de syslog, que forma 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/syslog.conf

• Description: este archivo incluye la configuración para especificar syslog como entrada de registro.

• Consulta el repositorio de configuración.

Nombre de configuración	Tipo	Predeterminado	Descripción
format	cadena	/^(?<message>(?<time>[^ ]*\s*[^ ]* [^ ]*) .*)$/	El formato del syslog.
path	cadena	/var/log/syslog	Ruta del archivo syslog.
pos_file	cadena	/var/lib/google-fluentd/pos/syslog.pos	Ruta del archivo de posición de esta entrada de registro. fluentd registra en este archivo la posición en la que leyó por última vez. Consulta la documentación detallada sobre fluentd.
read_from_head	bool	true	Indica si se deben empezar a leer los registros desde el principio del archivo en lugar de desde el final. Consulta la documentación detallada sobre fluentd.
tag	cadena	syslog	Etiqueta de registro de esta entrada de registro.

Configuración del complemento de entrada in_forward

Nota: La siguiente configuración predeterminada del complemento in_forward, que forma 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/forward.conf

• Descripción: este archivo incluye la configuración para configurar el complemento de entrada in_forward fluentd. El complemento de entrada in_forward te permite enviar registros a través de un socket TCP.

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

Nombre de configuración	Tipo	Predeterminado	Descripción
port	int	24224	El puerto que se va a monitorizar.
bind	cadena	127.0.0.1	Dirección de enlace que se va a monitorizar. De forma predeterminada, solo se aceptan conexiones de localhost. Para abrirlo, esta configuración debe cambiarse a 0.0.0.0.

Configuración de entrada de registros de aplicaciones de terceros

Nota: La siguiente configuración predeterminada de registro de aplicaciones de terceros, que forma 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: este directorio incluye 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 (por ejemplo, apache.conf para la aplicación Apache).

• Consulta el repositorio de configuración.

Nombre de configuración	Tipo	Predeterminado	Descripción
format^1	cadena	Varía según la aplicación	El formato del registro. Consulta la documentación detallada sobre fluentd.
path	cadena	Varía según la aplicación	Ruta de los archivos de registro. Se pueden especificar varias rutas separadas por ",". Se pueden incluir los formatos * y strftime para añadir o quitar archivos de seguimiento de forma dinámica. Consulta la documentación detallada sobre fluentd.
pos_file	cadena	Varía según la aplicación	Ruta del archivo de posición de esta entrada de registro. fluentd registra en este archivo la posición en la que leyó por última vez. Consulta la documentación detallada de fluentd.
read_from_head	bool	true	Indica si se deben empezar a leer los registros desde el principio del archivo en lugar de desde el final. Consulta la documentación detallada sobre fluentd.
tag	cadena	Varía; el nombre de la aplicación.	Etiqueta de registro de esta entrada de registro.

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

Configuración del complemento de salidaGoogle 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 estás ejecutando un agente de Logging anterior a la versión 1-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 salidaGoogle Cloud fluentd.

• Ve al repositorio de configuración.

Nombre de configuración	Tipo	Predeterminado	Descripción
buffer_chunk_limit	cadena	512KB	A medida que se reciben los registros de log, los que no se pueden escribir en los componentes posteriores con la suficiente rapidez se insertan en una cola de fragmentos. Esta configuración define el límite de tamaño de cada fragmento. De forma predeterminada, definimos el límite de fragmentos de forma conservadora para evitar superar el tamaño de fragmento recomendado de 5 MB por solicitud de escritura en la API Logging. Las entradas de registro de la solicitud de la API pueden ser entre 5 y 8 veces más grandes que el tamaño original del registro con todos los metadatos adicionales adjuntos. Un fragmento de búfer se vacía si se cumple una de las dos condiciones siguientes: 1. flush_interval se activa. 2. El tamaño del búfer alcanza buffer_chunk_limit.
flush_interval	cadena	5s	A medida que se reciben los registros de log, los que no se pueden escribir en los componentes posteriores con la suficiente rapidez se insertan en una cola de fragmentos. La configuración define cuánto tiempo debe transcurrir antes de que tengamos que vaciar un búfer de fragmentos. Un fragmento de búfer se vacía si se cumple una de las dos condiciones siguientes: 1. flush_interval se activa. 2. El tamaño del búfer alcanza buffer_chunk_limit.
disable_retry_limit	bool	false	Aplica un límite al número de reintentos de vaciado fallido de fragmentos de búfer. Consulta las especificaciones detalladas en retry_limit, retry_wait y max_retry_wait.
retry_limit	int	3	Cuando no se puede vaciar un fragmento del búfer, fluentd vuelve a intentarlo más tarde de forma predeterminada. Esta configuración define cuántos reintentos se deben realizar antes de descartar un fragmento de búfer problemático.
retry_wait	int	10s	Cuando no se puede vaciar un fragmento del búfer, fluentd vuelve a intentarlo más tarde de forma predeterminada. Esta configuración define el intervalo de espera en segundos antes del primer reintento. El intervalo de espera se duplica en cada reintento posterior (20 s, 40 s, etc.) hasta que se alcanza retry_ limit o max_retry_wait.
max_retry_wait	int	300	Cuando no se puede vaciar un fragmento del búfer, fluentd vuelve a intentarlo más tarde de forma predeterminada. El intervalo de espera se duplica en cada reintento posterior (20 s, 40 s, etc.). Esta configuración define el máximo de intervalos de espera en segundos. Si el intervalo de espera alcanza este límite, la duplicación se detiene.
num_threads	int	8	Número de vaciados de registros simultáneos que puede procesar el complemento de salida.
use_grpc	bool	true	Indica si se debe usar gRPC en lugar de REST/JSON para comunicarse con la API Logging. Con gRPC habilitado, el uso de la CPU suele ser menor
grpc_compression_algorithm	enum	none	Si se usa gRPC, define el esquema de compresión que se va a usar. Puede ser none (lector) u gzip (propietario).
partial_success	bool	true	Indica si se admite el éxito parcial en la ingesta de registros. Si true, se descartan las entradas de registro no válidas de un conjunto completo y las entradas de registro válidas se ingieren correctamente en la API Logging. Si es false, se descartaría todo el conjunto si contuviera alguna entrada de registro no válida.
enable_monitoring	bool	true	Si se le asigna el valor true, el agente de Logging exporta la telemetría interna. Consulta Telemetría del complemento de salida para obtener más información.
monitoring_type	cadena	opencensus	El tipo de monitorización. Las opciones admitidas son opencensus y prometheus. Consulta Telemetría del complemento de salida para obtener más información.
autoformat_stackdriver_trace	bool	true	Si se define como true, el seguimiento se reformatea si el valor del campo de carga útil estructurada logging.googleapis.com/trace coincide con el formato ResourceTrace traceId. Puedes consultar los detalles del formato automático en la sección Campos especiales en cargas útiles estructuradas de esta página.

Configuración de la monitorización

Telemetría del complemento de salida

La opción enable_monitoring controla si el complemento de salida Google Cloud fluentd recoge su telemetría interna. Si se define como true, el agente de registro hace un seguimiento del número de entradas de registro que se han solicitado para enviarse a Cloud Logging y del número real de entradas de registro que Cloud Logging ha ingerido correctamente. Si se le asigna el valor false, el complemento de salida no recogerá ninguna métrica.

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

Si se define como prometheus, el agente de registro expone las métricas en formato Prometheus en el endpoint de Prometheus (localhost:24231/metrics de forma predeterminada; consulta la configuración de los complementos prometheus y prometheus_monitor para obtener más información sobre cómo personalizarlo). En las VMs de Compute Engine, para que esas métricas se escriban en la API Monitoring, también se debe instalar y ejecutar el agente de Monitoring.

Si se define como opencensus (valor predeterminado desde la versión v1.6.25), el agente de Logging escribe directamente sus propias métricas de estado en la API Monitoring. Para ello, se debe conceder el rol roles/monitoring.metricWriter a la cuenta de servicio predeterminada de Compute Engine, aunque el agente de Monitoring no esté instalado.

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

• agent.googleapis.com/agent/uptime con la etiqueta version: Tiempo de actividad del agente de Logging.
• agent.googleapis.com/agent/log_entry_count con la etiqueta response_code: número de entradas de registro escritas por el agente de Logging.
• agent.googleapis.com/agent/log_entry_retry_count con una etiqueta response_code : recuento de entradas de registro escritas por el agente de Logging.
• agent.googleapis.com/agent/request_count con la etiqueta response_code: Número de solicitudes de API del agente de Logging.

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

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

• uptime con la etiqueta version: Tiempo de actividad del agente de Logging.
• stackdriver_successful_requests_count con las etiquetas grpc y code: Número de solicitudes correctas a la API Logging.
• stackdriver_failed_requests_count con las etiquetas grpc y code: Número de solicitudes fallidas a la API Logging, desglosado por código de error.
• stackdriver_ingested_entries_count con las etiquetas grpc y code: el número de entradas de registro insertadas por la API Logging.
• stackdriver_dropped_entries_count con las etiquetas grpc y code: número de entradas de registro rechazadas por la API Logging.
• stackdriver_retried_entries_count con las etiquetas grpc y code: Número de entradas de registro que no se han podido ingerir mediante el Google Cloud plugin de salida fluentd debido a un error transitorio y que se han vuelto a intentar.

Configuración de los complementos prometheus y prometheus_monitor

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

• Ubicaciones de los archivos de configuración: /etc/google-fluentd/google-fluentd.conf

• Descripción: Este archivo incluye opciones de configuración para controlar el comportamiento de los complementos prometheus y prometheus_monitor. El complemento prometheus_monitor monitoriza la infraestructura principal de Fluentd. El complemento prometheus expone las métricas, incluidas las del complemento prometheus_monitor y las del complemento google_cloud, 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 monitorizar Fluentd, el servidor de métricas http de Prometheus integrado está habilitado de forma predeterminada. Puedes quitar la siguiente sección de la configuración para evitar que se inicie este endpoint:

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

Procesar cargas útiles

La mayoría de los registros admitidos en la configuración predeterminada del agente de registro proceden de archivos de registro y se ingieren como cargas útiles no estructuradas (texto) en las entradas de registro.

La única excepción es el complemento de entrada in_forward, que también está habilitado de forma predeterminada y solo acepta registros estructurados, que ingiere como cargas útiles estructuradas (JSON) en las entradas de registro. Para obtener más información, consulta la sección Registros de streaming estructurados (JSON) mediante el complemento in_forward de esta página.

Si 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 máquina virtual 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 ingiere como jsonPayload.

Puedes personalizar la configuración de los agentes para que admitan la ingestión de registros estructurados de recursos adicionales. Para obtener más información, consulta el artículo sobre enviar registros estructurados (JSON) a Cloud Logging.

La carga útil de los registros de registro transmitidos por un agente de registro configurado de forma personalizada puede ser un único mensaje de texto sin estructurar (textPayload) o un mensaje JSON estructurado (jsonPayload).

Campos especiales en cargas útiles estructuradas

Cuando el agente de Logging recibe un registro de registro estructurado, mueve cualquier clave que coincida con la tabla siguiente al campo correspondiente del objeto LogEntry. De lo contrario, la clave pasará a formar parte del campo LogEntry.jsonPayload. Este comportamiento te permite definir campos específicos en el objeto LogEntry, que es lo que se escribe en la API Logging. Por ejemplo, si el registro de registro estructurado contiene una clave severity, el agente de Logging rellena 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 asociar varias cadenas de gravedad comunes, entre las que se incluye la lista de cadenas LogSeverity reconocidas por la API 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 que queda después de que el agente de registro mueva los otros campos de propósito especial y detect_json no se haya habilitado. De lo contrario, message permanece en jsonPayload. detect_json no se aplica a entornos de registro gestionados, como Google Kubernetes Engine. Si tu entrada de registro contiene un seguimiento de pila de excepciones, este debe definirse en este campo de registro JSON message para que se pueda analizar y guardar en Error Reporting.
log (solo para la versión antigua de Google Kubernetes Engine)	textPayload	Solo se aplica a la versión antigua de Google Kubernetes Engine: si, después de mover los campos de propósito especial, solo queda un campo log, ese campo se guarda como textPayload.
httpRequest	httpRequest	Un registro estructurado con el formato del campo LogEntry HttpRequest.	"httpRequest":{"requestMethod":"GET"}
campos relacionados con el tiempo	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 la sección insertId de 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 valor de este campo también lo usa el Explorador de registros para agrupar las 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 la ubicación del código fuente asociada a la entrada de registro, si la hay. Para obtener más información, consulta la sección LogEntrySourceLocation de la página LogEntry.	"logging.googleapis.com/sourceLocation": {"file":"get_data.py","line":"142","function":"getData"}
logging.googleapis.com/spanId	spanId	El ID del intervalo de la traza asociada a la entrada de registro. Para obtener más información, consulta la sección spanId de la página LogEntry.	"logging.googleapis.com/spanId":"000000000000004a"
logging.googleapis.com/trace	trace	Nombre de recurso de la traza asociada a la entrada de registro, si lo hay. Para obtener más información, consulta la sección trace de la página LogEntry.	"logging.googleapis.com/trace":"projects/my-projectid/traces/0679686673a" Nota: Si no escribe en stdout o stderr, el valor de este campo debe tener el formato projects/[PROJECT-ID]/traces/[TRACE-ID], para que Explorador de registros y Visor de trazas puedan usarlo para agrupar entradas de registro y mostrarlas en línea con las trazas. Si autoformat_stackdriver_trace es true y [V] coincide con el formato de ResourceTrace, traceId 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 la sección traceSampled de la página LogEntry.	"logging.googleapis.com/trace_sampled": false

Campos relacionados con el tiempo

Por lo general, la información relacionada con la hora de 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 información relacionada con la hora en los campos de la entrada jsonPayload:

1. Busca un campo timestamp que sea un objeto JSON que incluya los campos seconds y nanos, que representan, respectivamente, un número de segundos firmado desde el inicio del registro de tiempo 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 cadena en formato RFC 3339:

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

Cuando se encuentra información relacionada con el tiempo, el agente de Logging la usa para definir 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 definir 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 del objeto JSON timestamp se utilizan para definir el campo LogEntry.timestamp. El objeto LogEntry.jsonPayload contiene un campo time, porque este campo no se ha usado para definir el valor LogEntry.timestamp.

Personalizar 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 que envíe registros adicionales a Logging o para ajustar la configuración del agente añadiendo configuraciones de entrada.

Las definiciones de configuración de estas secciones solo se aplican al complemento de salida fluent-plugin-google-cloud y especifican cómo se transforman y se ingieren los registros en 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 estás ejecutando un agente de Logging anterior a la versión 1-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.

Registros de streaming de entradas adicionales

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

Transmitir registros no estructurados (texto) a través de archivos de registro

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

1. En el símbolo del sistema de Linux, crea un archivo de registro:

   touch /tmp/test-unstructured-log.log
   

2. Crea un archivo de configuración llamado 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
   

   Otra opción es añadir la información de configuración a un archivo de configuración que ya tengas.

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. Consulta el Explorador de registros para ver la entrada de registro insertada:

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

Transmitir registros estructurados (JSON) a través de archivos de registro

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

Puede configurar el agente de Logging para que cada entrada de registro de determinadas entradas de registro sea estructurada. También puedes personalizar el agente de registro para que ingiera contenido en formato JSON de un archivo de registro. Cuando el agente se configura para ingerir contenido JSON, la entrada debe tener un formato en el que cada objeto JSON esté en una línea nueva:

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

Para configurar el agente de Logging de forma que ingiera contenido con formato JSON, haz lo siguiente:

1. En el símbolo del sistema de Linux, crea un archivo de registro:

   touch /tmp/test-structured-log.log
   

2. Crea un archivo de configuración llamado 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
   

   Otra opción es añadir la información de configuración a un archivo de configuración que ya tengas.

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. Consulta el Explorador de registros para ver la entrada de registro insertada:

   {
     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 tu tipo de recurso y por el logName structured-log.

Para ver otras opciones de personalización del formato de entrada de registro de aplicaciones comunes de terceros, consulta Common Log Formats and How To Parse Them (Formatos de registro comunes y cómo analizarlos).

Transmitir registros estructurados (JSON) mediante el 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 fácilmente al complemento in_forward. En la documentación de fluentd se incluye más información sobre esta herramienta.

Para enviar registros a través del complemento fluentd in_forward, consulta 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. Consulta el Explorador de registros para ver la entrada de registro insertada:

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

Enviar por streaming registros de registro estructurados (JSON) desde el código de la aplicación

Puede habilitar conectores en varios idiomas para enviar registros estructurados desde el código de la aplicación. Para obtener más información, consulte la fluentddocumentación. Estos conectores se han creado a partir del complemento in_forward.

Definir etiquetas de entrada de registro

Las siguientes opciones de configuración te permiten anular las etiquetas LogEntry y MonitoredResource al ingerir registros en Cloud Logging. Todas las entradas de registro están asociadas a recursos supervisados. Para obtener más información, consulta la lista de tipos de recursos supervisados de Cloud Logging.

Nombre de configuración	Tipo	Predeterminado	Descripción
label_map	hash	nil	label_map (especificado como un objeto JSON) es un conjunto desordenado de nombres de campos fluentd cuyos valores se envían como etiquetas en lugar de como parte de la carga útil estructurada. Cada entrada del mapa es un par {field_name: label_name}. Cuando se encuentra field_name (analizado por el complemento de entrada), se añade una etiqueta con el label_name correspondiente a la entrada del registro. El valor del campo se usa como valor de la etiqueta. El mapa te ofrece más flexibilidad a la hora de especificar nombres de etiquetas, incluida la posibilidad de usar caracteres que no serían válidos como parte de los nombres de los campos fluentd. Para ver un ejemplo, consulta Definir etiquetas en entradas de registro estructuradas.
labels	hash	nil	labels (especificado como un objeto JSON) es un conjunto de etiquetas personalizadas que se proporciona durante la configuración. Te permite inyectar información adicional del entorno en cada mensaje o personalizar las etiquetas que se detectan automáticamente. Cada entrada del mapa es un par {label_name: label_value}.

El complemento de salida del agente de Logging admite tres formas de definir etiquetas LogEntry:

• De forma dinámica, sustituyendo etiquetas específicas de una entrada estructurada por otras etiquetas. Para obtener más información, consulta la sección Definir etiquetas en entradas de registro estructuradas de esta página.
• De forma estática, adjuntando una etiqueta a cualquier aparición de un valor. Para obtener más información, consulta la sección Definir etiquetas de forma estática de esta página.

Configurar etiquetas en entradas de registro estructuradas

Supongamos que has escrito una carga útil de entrada de registro estructurada como esta:

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

Supongamos que quieres traducir el campo de carga útil env a una etiqueta de metadatos environment. Para ello, añade 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>

El ajuste label_map sustituye la etiqueta env de la carga útil por environment, por lo que la entrada de registro resultante tiene la etiqueta environment con el valor production.

Definir etiquetas de forma estática

Si no tienes esta información en la carga útil y solo quieres añadir una etiqueta de metadatos estática llamada environment, añade 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
  labels {
    "environment": "production"
  }
  ...
</match>

En este caso, en lugar de usar un mapa para sustituir una etiqueta por otra, usamos un ajuste de labels para adjuntar una etiqueta con un valor literal determinado a una entrada de registro, independientemente de si la entrada ya tiene una etiqueta o no. Este método se puede usar incluso si envías registros no estructurados.

Para obtener más información sobre cómo configurar labels, label_map y otros ajustes del agente de registro, consulta la sección Definir etiquetas de entrada de registro de esta página.

Modificar registros

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

El complemento de filtro más utilizado es filter_record_transformer. Te permite hacer lo siguiente:

• Añadir campos nuevos a las entradas de registro
• Actualizar campos en entradas de registro
• Eliminar 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 ofrece una funcionalidad similar a la del complemento de filtro filter_record_transformer, pero también te permite modificar las etiquetas de registro. Se espera que este complemento consuma más recursos, ya que cada vez que se actualiza una etiqueta de registro, se genera una nueva entrada de registro con la nueva etiqueta. Ten en cuenta que el campo tag de la configuración es obligatorio. También te recomendamos que modifiques este campo para evitar que se produzca un bucle infinito.

El complemento de salida fluent-plugin-detect-exceptions analiza un flujo de registro, ya sea no estructurado (texto) o registros de registro en formato JSON, para buscar seguimientos de pila de excepciones de varias líneas. Si una secuencia consecutiva de entradas de registro forma un seguimiento de pila de excepciones, las entradas de registro se reenvían como un único mensaje de registro combinado. De lo contrario, la entrada de registro se reenvía tal cual.

Definiciones de configuración avanzada (no predeterminada)

Si quieres personalizar la configuración de tu agente de registro más allá de 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 de almacenamiento en búfer interno del agente de Logging.

Nombre de configuración	Tipo	Predeterminado	Descripción
buffer_type	cadena	buf_memory	Los registros que no se pueden escribir en la API Logging con la suficiente rapidez se insertan en un búfer. El búfer puede estar en la memoria o en archivos reales. Valor recomendado: buf_file. El valor predeterminado buf_memory es rápido, pero no persistente. Existe el riesgo de perder los registros. Si buffer_type es buf_file, también debe especificarse buffer_path.
buffer_path	cadena	Especificado por el usuario	Ruta en la que se almacenan los fragmentos del 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 el límite de longitud de la cola de fragmentos. Cuando la cola del búfer alcanza este número de fragmentos, el comportamiento del búfer se controla mediante buffer_queue_full_action. De forma predeterminada, genera excepciones. Esta opción, combinada con buffer_chunk_limit, determina el espacio máximo en disco que ocupa fluentd 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á llena. Valores posibles: 1. exception: lanza BufferQueueLimitError cuando la cola esté llena. La forma en que se gestiona 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 devuelve un error. 2. block: este modo detiene el subproceso del complemento de entrada hasta que se resuelve la condición de búfer lleno. Esta acción es adecuada para casos prácticos similares a los de los lotes. fluentd no recomienda usar la acción de bloqueo para evitar BufferQueueLimitError. Si alcanzas el límite BufferQueueLimitError con frecuencia, significa que la capacidad de tu destino es insuficiente para tu tráfico. 3. drop_oldest_chunk: en este modo se eliminan los fragmentos más antiguos.

Opciones de configuración relacionadas con proyectos y recursos monitorizados

Las siguientes opciones de configuración te permiten especificar manualmente un proyecto y determinados campos del objeto MonitoredResource. El agente de registro recoge estos valores automáticamente, por lo que no se recomienda especificarlos manualmente.

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

Otras opciones de configuración del complemento de salida

Nombre de configuración	Tipo	Predeterminado	Descripción
detect_json^1	bool	false	Indica si se debe intentar detectar si el registro es una entrada de registro de texto con contenido JSON que debe analizarse. Si esta opción está true y se detecta una entrada de registro no estructurada (texto) en formato JSON, se analiza y se envía como una carga útil estructurada (JSON).
coerce_to_utf8	bool	true	Indica si se permiten caracteres no UTF-8 en los registros de usuarios. Si se define como true, cualquier carácter que no sea UTF-8 se sustituirá por la cadena especificada en non_utf8_replacement_string. Si se define como false, cualquier carácter que no sea UTF-8 hará que el complemento genere un error.
require_valid_tags	bool	false	Si se deben rechazar las entradas de registro con etiquetas no válidas. Si esta opción está definida como false, las etiquetas se validan convirtiendo cualquier etiqueta que no sea una cadena en una cadena y saneando cualquier carácter que no sea UTF-8 u otro carácter no válido.
non_utf8_replacement_string	cadena	""(espacio)	Si coerce_to_utf8 tiene el valor true, cualquier carácter que no sea UTF-8 se sustituirá por la cadena 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.

Aplicar una configuración de agente personalizada

Personalizar el agente de Logging te permite añadir tus propios fluentdarchivos de configuración:

Instancia de Linux

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

   /etc/google-fluentd/config.d/
   

   La secuencia de comandos de instalación del agente de registro rellena este directorio con los archivos de configuración catch-all predeterminados. Para obtener más información, consulta Obtener el código fuente del agente de Logging.

2. Opcional. Valida el cambio de configuración ejecutando el siguiente comando:

   sudo service google-fluentd configtest
   

3. Reinicia el agente ejecutando el siguiente comando:

   sudo service google-fluentd force-reload
   

Instancia de Windows

Nota: Si usas una versión del agente anterior a la 1-5, no podrás añadir tus propios archivos de configuración. Actualiza al agente más reciente.

1. Copia los archivos de configuración en el subdirectorio config.d del directorio de instalación del agente. Si has aceptado el directorio de instalación predeterminado, este es el directorio:

   C:\Program Files (x86)\Stackdriver\LoggingAgent\config.d\
   

2. Reinicia el agente ejecutando los siguientes comandos en un shell de línea de comandos:

   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.