Nota:

Ingestión de logs en OCI Logging Analytics mediante Fluentd

Introducción

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

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

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

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

Descripción de la ilustración fluentd_plugin_overview.png

Objetivos

Migración del plugin de salida de OCI Logging Analytics de la versión 1.x a 2.x

Si es un nuevo usuario del plugin de salida de OCI Logging Analytics y aún desea descargarlo e instalarlo, omita esta subsección y vaya a Requisitos previos. Si ha instalado el plugin version 1.x mediante el archivo fluent-plugin-oci-logging-analytics-1.0.0.gem, tenga en cuenta los cambios que puede que necesite realizar para migrar al plugin version 2.x:

1.x 2.x
global_metadata oci_la_global_metadata
metadatos oci_la_metadata
identificador de entidad oci_la_entity_id
entityType oci_la_entity_type
logSourceName oci_la_log_source_name
logPath oci_la_log_path
logGroupId oci_la_log_group_id

Requisitos

Creación del Archivo de Configuración Fluentd

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

La configuración del plugin de salida 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 utilice 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 reintentos. Además, para errores irrecuperables, Fluentd cancelará el fragmento inmediatamente y lo moverá al directorio secundario o al directorio de copia de seguridad. Consulte Documentación detallada: salida secundaria.

Parámetros de configuración del plugin de salida

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

Parámetro de configuración Descripción
espacio de nombres (parámetro obligatorio) Espacio de nombres de arrendamiento de OCI al 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á en 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. 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 del plugin de salida para escribir sus propios logs. Asegúrese de que la ruta existe y de que se puede acceder a ella. Valor por defecto: Directorio de trabajo.
plugin_log_level Nivel de registro del plugin de salida: DEBUG < INFO < WARN < ERROR < FATAL < UNKNOWN. Valor predeterminado: INFO.
plugin_log_rotation (DEPRECATED) Frecuencia de rotación de archivo log de plugin de salida: diaria, semanal o mensual. Valor por defecto: diario.
plugin_log_file_size Tamaño máximo del archivo log en el punto en el que se va a rotar el archivo log.' (1 KB, 1 MB, etc.). Valor por defecto: 1 MB.
plugin_log_file_count Número de archivos log archivados/rotados que se van a conservar (mayor que 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 en la que se almacenan los archivos de buffer. Asegúrese de que la ruta existe y de que se puede acceder a ella.

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

Parámetros opcionales 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 del siguiente reintento de vaciado.
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 /bloque / drop_oldest_chunk. Valor recomendado: bloque.
disable_chunk_backup false Cuando se especifica false, se desecharán los fragmentos irrecuperables en el directorio de copia de seguridad.
chunk_limit_size 8MB Tamaño máximo de cada fragmento. Los eventos se escribirán en fragmentos hasta que el tamaño de los fragmentos se convierta en este tamaño. Nota: Independientemente del valor especificado, el plugin de salida de Logging Analytics establece actualmente 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 se perderán los datos).
flush_interval 60s Frecuencia de vaciado de fragmentos en el 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 Logging Analytics.

Visualice la configuración de ejemplo 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 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:

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

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

Configuración de Filtro

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

Para asegurarse de que el plugin de salida proporcionado por Oracle pueda procesar los logs del origen de entrada, verifique que los eventos del log de entrada se ajusten al formato indicado, 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 es solo 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 filtro:

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

Configuraciones de ejemplo 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 Logging Analytics. Los pasos de esta sección son para la configuración de Fluentd basada en el paquete de rpm de agente de td 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 Plugin Fluentd Output para enviar logs/eventos a OCI Logging Analytics en RubyGems: https://rubygems.org/gems/fluent-plugin-oci-logging-analytics.

  1. Systemd inicia td-agent con el usuario td-agent. Proporcione al usuario td-agent el 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 Logging Analytics y el archivo .oci pem, por ejemplo, chown td-agent [FILE].

  2. Para empezar a recopilar logs en Oracle Cloud Logging 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

Comience a ver los logs en Logging Analytics

Vaya al Explorador de logs y utilice el panel Visualizar de Oracle Cloud Logging Analytics para ver los datos del log en un formulario que le ayude a comprenderlos y analizarlos 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.

Control Fluentd con Prometheus

Puede supervisar Fluentd opcionalmente mediante Prometheus. Para conocer los pasos para exponer las métricas siguientes y otras emitidas por Fluentd a Prometheus, consulte Documentación de Fluentd: Supervisión por Prometheus. Si desea supervisar solo el flujo principal y estas métricas, omita los pasos Paso 1: Recuento de registros entrantes por plugin de filtro de Prometheus y Paso 2: Recuento de registros salientes por plugin de salida de 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 Logging 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 Logging 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 Logging 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 Logging 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 Logging 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 Logging 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 Logging Analytics by the Fluentd output plugin.
Type : Histogram

Más información

Más recursos de aprendizaje

Explore otros laboratorios en docs.oracle.com/learn o acceda a más contenido de aprendizaje gratuito en el canal YouTube de Oracle Learning. Además, visite education.oracle.com/learning-explorer para convertirse en Oracle Learning Explorer.

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