Remarque :

Inclure des journaux dans OCI Logging Analytics à l'aide de Fluentd

Introduction

Utilisez le logiciel collecteur de données open source Fluentd pour collecter les données de journal de votre source. Installez le module d'extension de sortie OCI Logging Analytics pour acheminer les données de journal collectées vers Oracle Cloud Logging Analytics.

Remarque : Oracle recommande d'utiliser les agents de gestion Oracle Cloud pour une expérience optimale d'inclusion des données de journal dans Oracle Cloud Logging Analytics. Toutefois, si votre cas d'emploi ne le permet pas, utilisez le module d'extension de sortie OCI Logging Analytics pour Fluentd.

Dans ce tutoriel, une configuration Fluentd est utilisée sur la base du package td-agent rpm installé sur Oracle Linux, mais les étapes requises peuvent être similaires pour les autres distributions de Fluentd.

Fluentd possède des composants qui fonctionnent conjointement pour collecter les données de journal à partir des sources d'entrée, transformer les journaux et acheminer les données de journal vers la sortie souhaitée. Vous pouvez installer et configurer le module d'extension de sortie pour Fluentd afin d'inclure des journaux de diverses sources dans Oracle Cloud Logging Analytics.

Description de l'image fluentd_plugin_overview.png

Objectifs

Migration du module d'extension de sortie OCI Logging Analytics à partir de la version 1.x vers 2.x

Si vous êtes un nouvel utilisateur du module d'extension de sortie OCI Logging Analytics et que vous devez le télécharger et l'installer, ignorez cette sous-section et accédez à Prérequis. Si vous avez installé le module d'extension version 1.x à l'aide du fichier fluent-plugin-oci-logging-analytics-1.0.0.gem, notez les modifications que vous devrez éventuellement apporter pour effectuer la migration vers le module d'extension version 2.x :

1.x 2.x
global_metadata oci_la_global_metadata
métadonnées oci_la_metadata
ID d'entité 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

Prérequis

Création du fichier de configuration Fluentd

Pour configurer Fluentd afin d'acheminer les données de journal vers Oracle Cloud Logging Analytics, modifiez le fichier de configuration fourni par Fluentd ou td-agent et fournissez les informations relatives à Oracle Cloud Logging Analytics et à d'autres personnalisations.

La configuration du module d'extension de sortie Fluentd sera au format suivant :

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

Il est recommandé de configurer un module d'extension secondaire qui serait utilisé par Fluentd pour vider les données de sauvegarde lorsque le module d'extension de sortie continue d'échouer lors de l'écriture des blocs de tampon et dépasse le seuil de délai d'attente pour les nouvelles tentatives. En outre, pour les erreurs irrécupérables, Fluentd abandonne immédiatement le bloc et le déplace vers le répertoire secondaire ou le répertoire de sauvegarde. Reportez-vous à la section Fluentd Documentation : Second Output.

Paramètres de configuration du plug-in de sortie

Fournissez les valeurs appropriées aux paramètres suivants dans le fichier de configuration Fluentd :

Paramètre de configuration Description
namespace (paramètre obligatoire) Espace de noms de location OCI vers lequel les données de journal collectées doivent être téléchargées
config_file_location Emplacement du fichier de configuration contenant les détails d'authentification OCI
profile_name Nom du profil de configuration OCI à utiliser à partir du fichier de configuration
http_proxy Proxy sans informations d'identification. Exemple : www.proxy.com:80
proxy_ip Détails de l'adresse IP du proxy lorsque des informations d'identification sont requises. Exemple : www.proxy.com
proxy_port Détails du port proxy lorsque les informations d'identification sont requises. Exemple : 80
proxy_username Détails du nom utilisateur proxy
proxy_password Détails du mot de passe proxy lorsque des informations d'identification sont requises
plugin_log_location Chemin du fichier pour que le module d'extension de sortie écrive ses propres journaux. Assurez-vous que le chemin existe et est accessible. Valeur par défaut : répertoire de travail.
plugin_log_level Niveau de journalisation du module d'extension de sortie : DEBUG < INFO < WARN < ERROR < FATAL < UNKNOWN. Valeur par défaut : INFO.
plugin_log_rotation (DEPRECATED) Fréquence de rotation du fichier journal du module d'extension de sortie : quotidienne, hebdomadaire ou mensuelle. Valeur par défaut : quotidienne.
plugin_log_file_size Taille maximale du fichier journal à laquelle le fichier journal doit faire l'objet d'une rotation." (1 ko, 1 Mo, etc.). Valeur par défaut : 1 Mo.
plugin_log_file_count Nombre de fichiers journaux archivés/rotés à conserver (plus de 0). Valeur par défaut : 10.

Si vous n'indiquez pas les paramètres config_file_location et profile_name pour les noeuds OCI Compute, l'authentification basée sur instance_principal est utilisée.

Paramètres de configuration de tampon

Dans le même fichier de configuration que celui que vous avez modifié dans la section précédente, modifiez la section tampon et fournissez les informations obligatoires suivantes :

Paramètre obligatoire Description
@type Indique le module d'extension à utiliser en tant que back-end. Saisissez file.
path Chemin où les fichiers tampon sont stockés. Assurez-vous que le chemin existe et est accessible.

Les paramètres facultatifs suivants peuvent être inclus dans le bloc tampon :

Paramètre facultatif Valeur par défaut Description
flush_thread_count 1 Nombre de threads à vider/écrire des blocs en parallèle.
retry_wait 1s Patientez quelques secondes avant la prochaine tentative de vidage.
retry_max_times none Ce champ est obligatoire uniquement lorsque le champ retry_forever a la valeur False.
retry_exponential_backoff_base 2 Attendez en secondes avant le prochain facteur constant d'attente exponentielle.
retry_forever false Si la valeur est true, le module d'extension ignore l'option retry_max_times et relance le vidage indéfiniment.
overflow_action throw_exception Valeurs possibles : throw_exception / block / drop_oldest_chunk. Valeur recommandée : bloc.
disable_chunk_backup false Lorsque la valeur false est spécifiée, les blocs irrécupérables dans le répertoire de sauvegarde sont supprimés.
chunk_limit_size 8MB Taille maximale de chaque bloc. Les événements seront écrits en blocs jusqu'à ce que la taille des blocs devienne cette taille. Remarque : quelle que soit la valeur indiquée, le module d'extension de sortie Logging Analytics définit actuellement la valeur par défaut sur 1 Mo.
total_limit_size 64GB (pour le fichier) Une fois que la taille totale du tampon stocké a atteint ce seuil, toutes les opérations d'ajout échoueront avec des erreurs (et les données seront perdues).
flush_interval 60s Fréquence de vidage des blocs vers le plugin de sortie.

Pour plus d'informations sur les valeurs possibles des paramètres, reportez-vous à la section Fluentd Documentation : Buffer Plugins.

Vérification du format des événements de journal entrants

Les événements de journal entrants doivent avoir un format spécifique afin que le module d'extension Fluentd fourni par Oracle puisse traiter les données de journal, les segmenter et les transférer vers Oracle Cloud Logging Analytics.

Consultez l'exemple de configuration pouvant être utilisé pour surveiller les fichiers journaux syslog, apache et kafka dans l'Example Input Configuration.

Configuration du plug-in source/entrée

Exemple de configuration source pour les journaux 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>

Les paramètres suivants sont obligatoires pour définir le bloc source :

Les paramètres facultatifs suivants peuvent être inclus dans le bloc source :

Pour plus d'informations sur les autres paramètres, reportez-vous à la section Fluentd Documentation : tail.

Configuration de filtre

Utilisez ces paramètres pour répertorier les ressources Logging Analytics qui doivent être utilisées pour traiter vos journaux.

Pour vous assurer que les journaux de votre source d'entrée peuvent être traités par le module d'extension de sortie fourni par Oracle, vérifiez que les événements de journal d'entrée sont conformes au format prescrit, par exemple en configurant le module d'extension de filtre record_transformer pour modifier le format en conséquence.

Conseil : la configuration du module d'extension de filtre record_transformer n'est qu'une des manières d'inclure les paramètres requis dans les événements entrants. Pour connaître d'autres méthodes, reportez-vous à la documentation Fluentd.

Exemple de configuration de filtre :

    <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>`

Fournissez les informations obligatoires suivantes dans le bloc de filtre :

Vous pouvez éventuellement fournir les paramètres supplémentaires suivants dans le bloc de filtre :

Exemples de configurations que vous pouvez utiliser pour surveiller les journaux suivants :

Installer le module d'extension de sortie

Utilisez le fichier gem fourni par Oracle pour l'installation du module d'extension de sortie OCI Logging Analytics. Les étapes de cette section concernent la configuration Fluentd basée sur le package td-agent rpm installé sur Oracle Linux.

  1. Installez le module d'extension de sortie en exécutant la commande suivante :

    gem install fluent-plugin-oci-logging-analytics

Pour plus d'informations, reportez-vous à Plug-in de sortie Puissant pour envoyer des journaux/événements à OCI Logging Analytics sur RubyGems : https://rubygems.org/gems/fluent-plugin-oci-logging-analytics.

  1. Systemd démarre td-agent avec l'utilisateur td-agent. Donnez à l'utilisateur td-agent l'accès aux fichiers et dossiers OCI. Pour exécuter td-agent en tant que service, exécutez la commande chown ou chgrp pour les dossiers du module d'extension de sortie OCI Logging Analytics et le fichier pem .oci, par exemple, chown td-agent [FILE].

  2. Pour démarrer la collecte de journaux dans Oracle Cloud Logging Analytics, exécutez td-agent :

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

    Vous pouvez utiliser le fichier journal /var/log/td-agent/td-agent.log pour déboguer si vous rencontrez des problèmes lors de la collecte de journaux ou de la configuration.

    Pour arrêter td-agent à tout moment, exécutez la commande suivante :

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

Démarrer l'affichage des journaux dans Logging Analytics

Accédez à l'explorateur de journaux et utilisez le panneau Visualiser d'Oracle Cloud Logging Analytics pour visualiser les données de journal sous une forme qui vous aide à mieux les comprendre et les analyser. En fonction de ce que vous voulez réaliser avec votre ensemble de données, vous pouvez sélectionner le type de visualisation le mieux adapté à votre application.

Après avoir créé et exécuté une requête de recherche, vous pouvez enregistrer et partager vos recherches de journal dans un widget pour les réutiliser.

Vous pouvez créer des tableaux de bord personnalisés sur la page Tableaux de bord en ajoutant les widgets définis par Oracle ou les widgets personnalisés que vous avez créés.

Surveiller Fluentd à l'aide de Prometheus

Vous pouvez facultativement surveiller Fluentd à l'aide de Prometheus. Pour connaître les étapes permettant d'exposer les mesures ci-dessous et les autres mesures émises par Fluentd à Prometheus, reportez-vous à la section Fluentd Documentation : Monitoring by Prometheus. Si vous souhaitez surveiller uniquement les mesures Fluentd principales et ces mesures, ignorez les étapes Etape 1 : Comptage d'enregistrements entrants par module d'extension de filtre Prometheus et Etape 2 : Comptage d'enregistrements sortants par module d'extension de sortie Prometheus dans la documentation Fluentd référencée.

Le module d'extension Fluentd émet les mesures suivantes au format Prometheus, qui fournit des informations sur les données collectées et traitées par le module d'extension :

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

En savoir plus

Ressources de formation supplémentaires

Explorez d'autres exercices sur docs.oracle.com/learn ou accédez à davantage de contenu de formation gratuit sur le canal Oracle Learning YouTube. En outre, accédez à education.oracle.com/learning-explorer pour devenir explorateur Oracle Learning.

Pour consulter la documentation du produit, consultez Oracle Help Center.