Introducción

Utilice el software de recopilador de datos de código abierto, Fluentd, para recopilar los datos de log del origen. Instale el complemento de salida de OCI Log Analytics para enrutar los datos del log recopilados a Oracle Cloud Log Analytics.

Nota: Oracle recomienda que utilice Oracle Cloud Management Agents para disfrutar de la mejor experiencia de ingesta de datos de log en Oracle Cloud Log Analytics. Sin embargo, si esa no es una opción posible para su caso a utilizar, solo entonces utilice el plugin de salida de OCI Log Analytics para Fluentd.

En este tutorial, se utiliza una configuración de Fluentd basada en el paquete rpm td-agent instalado en Oracle Linux, pero los pasos necesarios podrían ser similares para otras distribuciones de Fluentd.

Fluentd tiene componentes que trabajan juntos para recopilar los datos de log de los orígenes de entrada, transformar los logs y enrutar los datos de log a la salida deseada. Puede instalar y configurar el plugin de salida para que Fluentd ingiera logs de varios orígenes en Oracle Cloud Log Analytics.

Descripción de la ilustración fluentd_plugin_overview.png

Objetivos

  • Descubra cómo instalar el plugin de salida de OCI Log Analytics proporcionado por Oracle para ingerir logs de su origen.
  • Cree la configuración de Fluentd para establecer la recopilación de logs desde el origen hasta Log Analytics.

Migre el plugin de salida de OCI Log Analytics de la versión 1.x a 2.x

Si es un nuevo usuario del plugin de salida de OCI Log Analytics y aún no lo ha descargado ni instalado, omita esta sección y vaya a Requisitos. Si ha instalado el plugin version 1.x mediante el archivo fluent-plugin-oci-logging-analytics-1.0.0.gem, tenga en cuenta que es posible que deba realizar cambios para migrar al plugin version 2.x.

En version 2.x, se cambia el nombre de los siguientes parámetros de configuración:
1.x 2.x
global_metadata oci_la_global_metadata
metadatos oci_la_metadata
identificador de entidad oci_la_entity_id
Tipo de entidad oci_la_entity_type
logSourceName oci_la_log_source_name
logPath oci_la_log_path
logGroupId oci_la_log_group_id
  • Se ha agregado soporte para la depuración automática de logs del plugin de salida de OCI Log Analytics.
  • El parámetro plugin_log_rotation ahora está en desuso. En su lugar, utilice los parámetros plugin_log_file_size y plugin_log_file_count en conjunción para realizar la misma acción.
  • Instale el plugin version 2.x mediante el comando disponible en la sección Install the Output Plugin.

Realización de requisitos

Creación del archivo de configuración Fluentd

Para configurar Fluentd para que enrute los datos de log a Oracle Cloud Log Analytics, edite el archivo de configuración proporcionado por Fluentd o td-agent y proporcione la información relacionada con Oracle Cloud Log Analytics y otras personalizaciones.

La configuración del plugin de salida de Fluentd tendrá el siguiente formato:

<match pattern>
@type oci-logging-analytics
 namespace                   <YOUR_OCI_TENANCY_NAMESPACE>

# Auth config file details
 config_file_location        ~/.oci/config 
 profile_name                DEFAULT

# When there is no credentials for proxy
 http_proxy                  "#{ENV['HTTP_PROXY']}"

# To provide proxy credentials
 proxy_ip                    <IP>
 proxy_port                  <port>
 proxy_username              <user>
 proxy_password              <password>

# Configuration for plugin (oci-logging-analytics) generated logs
 plugin_log_location       "#{ENV['FLUENT_OCI_LOG_LOCATION'] || '/var/log'}" 
 plugin_log_level          "#{ENV['FLUENT_OCI_LOG_LEVEL'] || 'info'}"
 plugin_log_rotation       "#{ENV['FLUENT_OCI_LOG_ROTATION'] || 'daily'}"  **(DEPRECATED)**
 plugin_log_file_size      "#{ENV['FLUENT_OCI_LOG_AGE'] || '1MB'}"
 plugin_log_file_count     "#{ENV['FLUENT_OCI_LOG_AGE'] || '10'}"

# Buffer Configuration
 <buffer>
       @type file
       path                                "#{ENV['FLUENT_OCI_BUFFER_PATH'] || '/var/log'}"
       flush_thread_count                  "#{ENV['FLUENT_OCI_BUFFER_FLUSH_THREAD_COUNT'] || '10'}"
       retry_wait                          "#{ENV['FLUENT_OCI_BUFFER_RETRY_WAIT'] || '2'}"                     #seconds
       retry_max_times                     "#{ENV['FLUENT_OCI_BUFFER_RETRY_MAX_TIMES'] || '10'}"
       retry_exponential_backoff_base      "#{ENV['FLUENT_OCI_BUFFER_RETRY_EXPONENTIAL_BACKOFF_BASE'] || '2'}" #seconds
       retry_forever                       true
       overflow_action                     block
       disable_chunk_backup                true
 </buffer>
	</match>

Se recomienda configurar un plugin secundario que Fluentd utilizaría para volcar los datos de copia de seguridad cuando el plugin de salida siga fallando al escribir los fragmentos de buffer y exceda el umbral de timeout para los reintentos. Además, para los errores irrecuperables, Fluentd aborta el fragmento inmediatamente y lo mueve al directorio secundario o de copia de seguridad. Consulte Documentación de Fluentd: Salida secundaria.

Parámetros de configuración del plugin de salida

Proporcione valores adecuados a los siguientes parámetros en el archivo de configuración de Fluentd:

Parámetros de configuración Descripción
namespace (parámetro obligatorio) Espacio de nombres de arrendamiento de OCI en el que se cargarán los datos de log recopilados
config_file_location Ubicación del archivo de configuración que contiene los detalles de autenticación de OCI
profile_name Nombre de perfil de configuración de OCI que se utilizará desde el archivo de configuración
http_proxy Proxy sin credenciales. Ejemplo: www.proxy.com:80
proxy_ip Detalles de IP de proxy cuando se necesitan credenciales. Ejemplo: www.proxy.com
proxy_port Detalles de puerto de proxy cuando se necesitan credenciales. Por ejemplo: 80
proxy_username Detalles de nombre de usuario de proxy
proxy_password Detalles de contraseña de proxy cuando se necesitan credenciales
plugin_log_location Ruta de archivo para que el plugin de salida escriba sus propios logs. Asegúrese de que la ruta existe y es accesible. Valor predeterminado: directorio de trabajo.
plugin_log_level Nivel de registro de plugin de salida: DEBUG < INFO < WARN < ERROR < FATAL < UNKNOWN. Valor por defecto: INFO.
plugin_log_rotation (DEPRECATED) Frecuencia de rotación de archivo log de plugin de salida: diaria, semanal o mensual. Valor predeterminado: daily.
plugin_log_file_size Tamaño máximo del archivo log en el que se va a rotar el archivo log." (1 KB, 1 MB, etc.). Valor por defecto: 1MB.
plugin_log_file_count Número de archivos log archivados/rotados que se van a conservar (más de 0). Valor por defecto: 10.

Si no especifica los parámetros config_file_location y profile_name para los nodos de OCI Compute, se utiliza la autenticación basada en instance_principal.

Parámetros de configuración de buffer

En el mismo archivo de configuración que editó en la sección anterior, modifique la sección de buffer y proporcione la siguiente información obligatoria:

Parámetro obligatorio Descripción
@type Especifica qué plugin utilizar como backend. Introduzca file.
ruta de acceso Ruta de acceso donde se almacenan los archivos de memoria intermedia. Asegúrese de que la ruta existe y es accesible.

Los siguientes parámetros opcionales se pueden incluir en el bloque de buffers:

Parámetro opcional Valor por defecto Descripción
flush_thread_count 1 Número de threads para vaciar/escribir fragmentos en paralelo.
retry_wait 1s Espere en segundos antes de que el siguiente reintento se vacíe.
retry_max_times none Esto es obligatorio solo cuando el campo retry_forever es falso.
retry_exponential_backoff_base 2 Espere en segundos antes del siguiente factor constante de retroceso exponencial.
retry_forever false Si es true, el plugin ignorará la opción retry_max_times y volverá a intentar vaciar para siempre.
overflow_action throw_exception Valores posibles: throw_exception / block / drop_oldest_chunk. Valor recomendado: bloque.
disable_chunk_backup false Cuando se especifica false, los fragmentos irrecuperables del directorio de copia de seguridad se desecharán.
chunk_limit_size 8MB El tamaño máximo de cada fragmento. Los eventos se escribirán en trozos hasta que el tamaño de los trozos se convierta en este tamaño. Nota: Independientemente del valor especificado, el plugin de salida de Log Analytics actualmente establece el valor por defecto en 1 MB.
total_limit_size 64GB (para archivo) Una vez que el tamaño total del buffer almacenado ha alcanzado este umbral, todas las operaciones de agregación fallarán con errores (y los datos se perderán).
flush_interval 60s Frecuencia de vaciado de fragmentos al plugin de salida.

Para obtener detalles sobre los posibles valores de los parámetros, consulte Fluentd Documentation: Buffer Plugins.

Verificación del formato de los eventos de log entrantes

Los eventos de log entrantes deben tener un formato específico para que el plugin Fluentd proporcionado por Oracle pueda procesar los datos de log, fragmentarlos y transferirlos a Oracle Cloud Log Analytics.

Vea el ejemplo de configuración que se puede utilizar para supervisar los archivos log syslog, apache y kafka en Configuración de entrada de ejemplo.

Configuración de plugin de origen/entrada

Ejemplo de configuración de origen para logs de syslog:

<source>
  @type tail
  @id in_tail_syslog
  multiline_flush_interval 5s
  path /var/log/messages*
  pos_file /var/log/messages*.log.pos
  read_from_head true
  path_key tailed_path
  tag oci.syslog
  <parse>
    @type json
  </parse>
</source>

Los siguientes parámetros son obligatorios para definir el bloque de origen:

  • @type: tipo de plugin de entrada. Utilice tail para consumir eventos de un archivo local. Los otros valores posibles pueden ser http, forward.

  • path: ruta a los archivos de origen.

  • etiqueta: etiqueta que utilizará el plugin Fluentd de Oracle para filtrar los eventos de log que debe consumir Log Analytics. Asegúrese de utilizar el prefijo oci, por ejemplo, oci.syslog.

  • Directiva de análisis: se recomienda que no defina la directiva de análisis en el archivo de configuración. Mantenga el valor <parse> @type none </parse>. En su lugar, puede utilizar los analizadores y orígenes definidos por Oracle proporcionados por Log Analytics o crear sus propios analizadores y orígenes en Log Analytics. Para los logs ajustados en un envoltorio json, utilice la directiva de análisis <parse> @type json </parse>. Sustituya el campo de mensaje en el filtro record_transformer por el valor ${record["log"]}.

    Nota:

    • Se recomienda no usar ningún analizador Fluentd. En su lugar, envíe los logs a Log Analytics en el formulario original. La directiva de análisis debe tener el siguiente formato:

      <parse>
    @type none
</parse>

    • Sin embargo, en el caso de entradas de log de varias líneas, utilice el tipo de analizador de varias líneas para enviar varias líneas de un log como un único registro. Por ejemplo:

      <parse>
    @type multiline
    format_firstline /^\S+\s+\d{1,2}\s+\d{1,2}:\d{1,2}:\d{1,2}\s+/
    format1 /^(?<message>.*)/
</parse>

    • Para los logs originales que están ajustados por json wrapper donde una de las claves de los pares clave-valor es log, recomendamos que utilice la siguiente directiva de análisis:

      <parse>
    @type json
</parse>

    Además, sustituya el campo message en el filtro record_transformer por message ${record["log"]}. Por ejemplo, en el siguiente bloque de filtros para los logs de kafka, el contenido del log se almacena en el valor de la clave log, que se envuelve en un json.

    ```
<filter oci.kafka>
@type record_transformer
enable_ruby true
<record>
    oci_la_metadata KEY_VALUE_PAIRS
    oci_la_entity_id LOGGING_ANALYTICS_ENTITY_OCID              # If same across sources. Else keep this in individual filters
    oci_la_entity_type LOGGING_ANALYTICS_ENTITY_TYPE            # If same across sources. Else keep this in individual filters
    oci_la_log_source_name LOGGING_ANALYTICS_SOURCENAME
    oci_la_log_group_id LOGGING_ANALYTICS_LOGGROUP_OCID
    oci_la_log_path "${record['tailed_path']}"
    message ${record["log"]}                            # Will assign the 'log' key value from json wrapped message to 'message' field
    tag ${tag}
</record>
</filter>
```

Los siguientes parámetros opcionales se pueden incluir en el bloque de origen:

  • multiline_flush_interval: defina este valor solo para los logs de varias líneas para asegurarse de que Log Analytics consume todos los logs. Si el valor no está definido para los registros de varias líneas, Fluentd permanecerá en el modo de espera para el siguiente lote de registros. Por defecto, este parámetro está desactivado.
  • pos_file: utilice este parámetro para especificar el archivo en el que Fluentd mantiene el registro de la última posición que leyó.

Para obtener información sobre otros parámetros, consulte Fluentd Documentation: tail.

Configuración de filtro

Utilice estos parámetros para mostrar los recursos de Log Analytics que se deben utilizar para procesar los logs.

Para asegurarse de que los logs del origen de entrada puedan ser procesados por el plugin de salida proporcionado por Oracle, verifique que los eventos de log de entrada cumplan con el formato prescrito, por ejemplo, configurando el plugin de filtro record_transformer para modificar el formato según corresponda.

Consejo: Tenga en cuenta que la configuración del plugin de filtro record_transformer solo es una de las formas de incluir los parámetros necesarios en los eventos entrantes. Consulte la documentación de Fluentd para conocer otros métodos.

Ejemplo de configuración de filtro:

    <filter oci.kafka>
    @type record_transformer
    enable_ruby true
    <record>
        oci_la_metadata KEY_VALUE_PAIRS
        oci_la_entity_id LOGGING_ANALYTICS_ENTITY_OCID              # If same across sources. Else keep this in individual filters
        oci_la_entity_type LOGGING_ANALYTICS_ENTITY_TYPE            # If same across sources. Else keep this in individual filters
        oci_la_log_source_name LOGGING_ANALYTICS_SOURCENAME
        oci_la_log_group_id LOGGING_ANALYTICS_LOGGROUP_OCID
        oci_la_log_path "${record['tailed_path']}"
        message ${record["log"]}                            # Will assign the 'log' key value from json wrapped message to 'message' field
        tag ${tag}
    </record>
    </filter>`

Proporcione la siguiente información obligatoria en el bloque de filtros:

  • <filter oci.kafka>: parámetro para definir un bloque de filtro para la etiqueta especificada en el bloque de origen.
  • @type record_transformer: el plugin de transformador de registros transforma el registro de log original en un formulario que puede consumir el plugin de salida de OCI Log Analytics.
  • enable_ruby: permite el uso de la expresión de Ruby dentro de ${...}.
  • oci_la_entity_id: OCID de la entidad de Log Analytics que creó anteriormente en la tarea de requisitos para asignar el host.
  • oci_la_entity_type: tipo de entidad de la entidad de Log Analytics que ha creado anteriormente en la tarea de requisitos.
  • oci_la_log_source_name: origen de Log Analytics que se debe utilizar para procesar los registros de log.
  • oci_la_log_path: especifique la ubicación original de los archivos log. Si el valor de oci_la_log_path no tiene privilegios o no es válido, entonces:
    • si etiqueta está disponible, se utiliza como oci_la_log_path
    • si tag no está disponible, oci_la_log_path se establece en UNDEFINED
  • oci_la_log_group_id: OCID del grupo de logs de Log Analytics en el que se deben almacenar los logs.

Opcionalmente, puede proporcionar los siguientes parámetros adicionales en el bloque de filtros:

  • <filter oci.**>: utilice este filtro para proporcionar la información de configuración aplicable en todos los orígenes. Si utiliza este filtro, asegúrese de que está primero en el orden de ejecución entre los filtros. Si se especifica la misma clave en el filtro global y en el filtro de origen individual, el valor del filtro de nivel de origen sustituirá al filtro global. Se recomienda utilizar oci como prefijo para todas las etiquetas.
  • oci_la_global_metadata: utilice este parámetro para especificar metadatos adicionales junto con el contenido del log original en Log Analytics con el formato 'key1': 'value1', 'key2': 'value2'. Aquí, clave es el campo de Log Analytics que ya se debe definir antes de especificarlo aquí. Los metadatos globales se aplican a todos los archivos log.
  • oci_la_metadata: utilice este parámetro para definir metadatos adicionales junto con el contenido del log original en Log Analytics con el formato 'key1': 'value1', 'key2': 'value2'. Aquí, clave es el campo de Log Analytics que ya se debe definir antes de especificarlo aquí.
  • etiqueta: utilice este parámetro para adjuntar una etiqueta al mensaje para uso interno. Especifique con el formato tag ${tag}.
  • mensaje ${record["log"]}: incluya este parámetro para los logs que se encapsulan en un envoltorio json donde el mensaje de log original es el valor del atributo log dentro del json.

Ejemplos de configuraciones que puede utilizar para supervisar los siguientes logs:

Instalación del plugin de salida

Utilice el archivo gem proporcionado por Oracle para la instalación del plugin de salida de OCI Log Analytics. Los pasos de esta sección son para la configuración de Fluentd basada en el paquete td-agent rpm instalado en Oracle Linux.

  1. Instale el plugin de salida ejecutando el siguiente comando:

    gem install fluent-plugin-oci-logging-analytics

Para obtener más información, consulte el complemento Fluentd Output para enviar logs/eventos a OCI Log Analytics en RubyGems: https://rubygems.org/gems/fluent-plugin-oci-logging-analytics.

  1. Systemd inicia td-agent con el usuario td-agent. Otorgue al usuario de td-agent acceso a los archivos y carpetas de OCI. Para ejecutar td-agent como servicio, ejecute el comando chown o chgrp para las carpetas del plugin de salida de OCI Log Analytics y el archivo .OCI pem, por ejemplo, chown td-agent [FILE].

  2. Para empezar a recopilar logs en Oracle Cloud Log Analytics, ejecute td-agent:

    TZ=utc /etc/init.d/td-agent start

    Puede utilizar el archivo log /var/log/td-agent/td-agent.log para depurar si encuentra problemas durante la recopilación de logs o durante la configuración.

    Para detener td-agent en cualquier momento, ejecute el siguiente comando:

    TZ=utc /etc/init.d/td-agent stop

Inicio de la visualización de logs en Log Analytics

Vaya al Explorador de logs y utilice el panel Visualizar de Oracle Cloud Log Analytics para ver los datos del log en un formulario que le ayude a comprender y analizar mejor. En función de lo que desee lograr con su juego de datos, puede seleccionar el tipo de visualización que mejor se adapte a su aplicación.

Después de crear y ejecutar una consulta de búsqueda, puede guardar y compartir las búsquedas de log como widgets para volver a utilizarlas.

Puede crear paneles de control personalizados en la página Paneles de control agregando los widgets definidos por Oracle o los widgets personalizados que haya creado.

Supervisión de Fluentd usando Prometheus

Puede opcionalmente supervisar Fluentd mediante Prometheus. Para conocer los pasos para exponer las siguientes métricas y otras emitidas por Fluentd a Prometheus, consulte Documentación de Fluentd: supervisión por Prometheus. Si desea supervisar sólo el Fluentd principal y estas métricas, omita los pasos Paso 1: Recuento de registros entrantes por plugin de filtro Prometheus y Paso 2: Recuento de registros salientes por plugin de salida Prometheus en la documentación de Fluentd referida.

El plugin Fluentd emite las siguientes métricas en formato Prometheus, que proporciona información sobre los datos recopilados y procesados por el plugin:

Metric Name: oci_la_fluentd_output_plugin_records_received 
labels: [:tag,:oci_la_log_group_id,:oci_la_log_source_name,:oci_la_log_set]
Description: Number of records received by the OCI Log Analytics Fluentd output plugin.
Type : Gauge

Metric Name: oci_la_fluentd_output_plugin_records_valid 
labels: [:tag,:oci_la_log_group_id,:oci_la_log_source_name,:oci_la_log_set]
Description: Number of valid records received by the OCI Log Analytics Fluentd output plugin.
Type : Gauge 

Metric Name: oci_la_fluentd_output_plugin_records_invalid 
labels: [:tag,:oci_la_log_group_id,:oci_la_log_source_name,:oci_la_log_set,:reason]
Description: Number of invalid records received by the OCI Log Analytics Fluentd output plugin. 
Type : Gauge

Metric Name: oci_la_fluentd_output_plugin_records_post_error 
labels: [:tag,:oci_la_log_group_id,:oci_la_log_source_name,:oci_la_log_set,:error_code, :reason]
Description: Number of records failed posting to OCI Log Analytics by the Fluentd output plugin.
Type : Gauge
    
Metric Name: oci_la_fluentd_output_plugin_records_post_success 
labels: [:tag,:oci_la_log_group_id,:oci_la_log_source_name,:oci_la_log_set]
Description: Number of records posted by the OCI Log Analytics Fluentd output plugin. 
Type : Gauge  

Metric Name: oci_la_fluentd_output_plugin_chunk_time_to_receive
labels: [:tag]
Description: Average time taken by Fluentd to deliver the collected records from Input plugin to OCI Log Analytics output plugin.
Type : Histogram  

Metric Name: oci_la_fluentd_output_plugin_chunk_time_to_post 
labels: [:oci_la_log_group_id]
Description: Average time taken for posting the received records to OCI Log Analytics by the Fluentd output plugin.
Type : Histogram

Más información

Otros recursos de aprendizaje

Explore otros tutoriales en Oracle Learn o acceda a más contenido de aprendizaje gratuito en el canal YouTube de Oracle Learning. Además, visite Oracle Education para convertirse en un explorador de Oracle Learning.

Para obtener documentación sobre el producto, visite Oracle Help Center.