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'installation de sortie OCI Log Analytics pour acheminer les données de journal collectées vers Oracle Cloud Log Analytics.

Remarque : Oracle recommande d'utiliser les agents de gestion Oracle Cloud pour une expérience optimale d'inclusion des données du journal dans Oracle Cloud Log Analytics. Toutefois, si votre cas d'emploi ne peut pas le faire, utilisez le plug-in de sortie OCI Log Analytics pour Fluentd.

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

Fluentd a des composants qui fonctionnent ensemble 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'ingérer les journaux de différentes sources dans Oracle Cloud Log Analytics.

Description de l'illustration fluentd_plugin_overview.png

Objectifs

  • Découvrez comment installer le module d'extension de sortie OCI Log Analytics fourni par Oracle pour ingérer des journaux à partir de votre source.
  • Créez la configuration Fluentd pour établir la collecte de journaux de votre source vers Log Analytics.

Migrer le module d'extension de sortie OCI Log Analytics de la version 1.x vers 2.x

Si vous êtes un nouvel utilisateur du module d'extension de sortie OCI Log Analytics et que vous devez encore le télécharger et l'installer, ignorez cette section et accédez à Prérequis. Si vous avez installé le plug-in version 1.x à l'aide du fichier fluent-plugin-oci-logging-analytics-1.0.0.gem, vous devrez peut-être effectuer des modifications pour migrer vers le plug-in version 2.x.

Les paramètres de configuration suivants sont renommés dans la 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
Type d'entité oci_la_entity_type
logSourceName oci_la_log_source_name
logPath oci_la_log_path
logGroupId oci_la_log_group_id
  • La prise en charge de la purge automatique des journaux du module d'extension de sortie OCI Log Analytics est ajoutée.
  • Le paramètre plugin_log_rotation est désormais en phase d'abandon. Utilisez plutôt les paramètres plugin_log_file_size et plugin_log_file_count conjointement pour effectuer la même action.
  • Installez le plug-in version 2.x à l'aide de la commande disponible dans la section Install the Output Plugin.

Exécution des prérequis

Créer le fichier de configuration Fluentd

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

La configuration du plug-in de sortie Fluentd aura le 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 mémoire tampon et dépasse le seuil d'expiration 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 de sauvegarde. Reportez-vous à Documentation Fluentd : Sortie secondaire.

Paramètres de configuration du plug-in de sortie

Fournissez des 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 d'utilisateur proxy
proxy_password Détails du mot de passe proxy lorsque les informations d'identification sont requises
plugin_log_location Chemin d'accès au module d'extension de sortie pour écrire ses propres journaux. Assurez-vous que le chemin existe et qu'il est accessible. Valeur par défaut : répertoire de travail.
plugin_log_level Niveau de journalisation du plug-in 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 plug-in de sortie : quotidienne, hebdomadaire ou mensuelle. Valeur par défaut : daily.
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 (supérieur à 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 fichier de configuration 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 comme back-end. Entrez file.
path Chemin dans lequel les fichiers tampon sont stockés. Assurez-vous que le chemin existe et qu'il est accessible.

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

Paramètre optionnel Valeur par défaut Description
flush_thread_count 1 Nombre de threads à vider/écrire des blocs en parallèle.
retry_wait 1s Attendez 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 quelques secondes avant le prochain facteur constant de backoff exponentiel.
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 indiquée, les blocs irrécupérables du répertoire de sauvegarde sont supprimés.
chunk_limit_size 8MB Taille maximale de chaque bloc. Les événements seront écrits en morceaux jusqu'à ce que la taille des morceaux devienne cette taille. Remarque : quelle que soit la valeur indiquée, le module d'extension de sortie Log 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 plug-in 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 fragmenter et les transférer vers Oracle Cloud Log Analytics.

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

Configuration du plug-in source/d'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 :

  • @type : type de module d'extension d'entrée. Utilisez tail pour consommer des événements à partir d'un fichier local. Les autres valeurs possibles sont http, forward.

  • path : chemin vers les fichiers source.

  • balise : balise qui sera utilisée par le module d'extension Fluentd d'Oracle pour filtrer les événements de journal devant être utilisés par Log Analytics. Veillez à utiliser le préfixe oci, par exemple, oci.syslog.

  • Directive d'analyse : il est recommandé de ne pas définir la directive d'analyse dans le fichier de configuration. Conservez la valeur <parse> @type none </parse>. A la place, vous pouvez utiliser les analyseurs et sources définis par Oracle fournis par Log Analytics ou créer vos propres analyseurs et sources dans Log Analytics. Pour les journaux encapsulés dans un wrapper json, utilisez la directive d'analyse <parse> @type json </parse>. Remplacez le champ de message dans le filtre record_transformer par la valeur ${record["log"]}.

    Remarque :

    • Il est recommandé de ne pas utiliser d'analyseurs Fluentd. En revanche, envoyez les journaux à Log Analytics dans le formulaire d'origine. La directive d'analyse doit se présenter comme suit :

      <parse>
    @type none
</parse>

    • Toutefois, dans le cas d'entrées de journal multiligne, utilisez le type d'analyseur multiligne pour envoyer plusieurs lignes d'un journal en tant qu'enregistrement unique. Exemple :

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

    • Pour les journaux d'origine encapsulés par un wrapper json où l'une des clés des paires clé-valeur est log, nous vous recommandons d'utiliser la directive d'analyse suivante :

      <parse>
    @type json
</parse>

    Remplacez également le champ message dans le filtre record_transformer par message ${record["log"]}. Par exemple, dans le bloc de filtre suivant pour les journaux kafka, le contenu du journal est stocké dans la valeur de la clé log qui est encapsulée dans un fichier 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>
```

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

  • multiline_flush_interval : définissez cette valeur uniquement pour les journaux multilignes afin de vous assurer que tous les journaux sont utilisés par Log Analytics. Si la valeur n'est pas définie pour les journaux multilignes, Fluentd reste en mode d'attente pour le prochain lot d'enregistrements. Ce paramètre est désactivé par défaut.
  • pos_file : utilisez ce paramètre pour indiquer le fichier dans lequel Fluentd conserve l'enregistrement de la position de la dernière lecture.

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

Configuration de filtre

Utilisez ces paramètres pour répertorier les ressources Log Analytics qui doivent être utilisées pour traiter les 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.

A savoir : Notez que la configuration du module d'extension de filtre record_transformer n'est qu'un des moyens d'inclure les paramètres requis dans les événements entrants. Pour 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 :

  • <filter oci.kafka> : paramètre permettant de définir un bloc de filtre pour la balise indiquée dans le bloc source.
  • @type record_transformer : le module d'extension de transformateur d'enregistrement transforme l'enregistrement de journal d'origine en un formulaire pouvant être utilisé par le module d'extension de sortie OCI Log Analytics.
  • enable_ruby : permet d'utiliser l'expression Ruby dans ${...}.
  • oci_la_entity_id : OCID de l'entité Log Analytics que vous avez créée précédemment dans la tâche de prérequis pour mettre en correspondance l'hôte.
  • oci_la_entity_type : type d'entité de l'entité Log Analytics que vous avez créée précédemment dans la tâche de prérequis.
  • oci_la_log_source_name : source Log Analytics qui doit être utilisée pour traiter les enregistrements de journal.
  • oci_la_log_path : indiquez l'emplacement d'origine des fichiers journaux. Si la valeur de oci_la_log_path n'est pas fournie ou n'est pas valide, procédez comme suit :
    • si la balise est disponible, elle est utilisée comme oci_la_log_path
    • si la balise n'est pas disponible, oci_la_log_path est défini sur UNDEFINED
  • oci_la_log_group_id : OCID du groupe de journaux Log Analytics dans lequel les journaux doivent être stockés.

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

  • <filter oci.**> : utilisez ce filtre pour fournir les informations de configuration applicables à toutes les sources. Si vous utilisez ce filtre, assurez-vous qu'il est d'abord dans l'ordre d'exécution parmi les filtres. Si la même clé est spécifiée à la fois dans le filtre global et dans le filtre source individuel, la valeur du filtre de niveau source remplacera le filtre global. Nous vous recommandons d'utiliser oci comme préfixe pour toutes les balises.
  • oci_la_global_metadata : utilisez ce paramètre pour indiquer des métadonnées supplémentaires ainsi que le contenu du journal d'origine dans Log Analytics au format 'key1': 'value1', 'key2': 'value2'. Ici, Clé est le champ Log Analytics qui doit déjà être défini avant de le spécifier ici. Les métadonnées globales sont appliquées à tous les fichiers journaux.
  • oci_la_metadata : utilisez ce paramètre pour définir des métadonnées supplémentaires ainsi que le contenu du journal d'origine dans Log Analytics au format 'key1': 'value1', 'key2': 'value2'. Ici, Clé est le champ Log Analytics qui doit déjà être défini avant de le spécifier ici.
  • balise : utilisez ce paramètre pour attacher une balise au message à des fins d'utilisation interne. Indiquez le format tag ${tag}.
  • message ${record["log"]} : incluez ce paramètre pour les journaux encapsulés dans un wrapper json, où le message de journal d'origine est la valeur de l'attribut log dans le json.

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

Installer le plug-in de sortie

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

  1. Installez le plug-in 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 Fluentd pour envoyer des journaux/événements à OCI Log Analytics sur RubyGems : https://rubygems.org/gems/fluent-plugin-oci-logging-analytics.

  1. Systemd démarre td-agent avec l'utilisateur td-agent. Accordez à 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 de module d'extension de sortie OCI Log Analytics et le fichier .OCI pem, par exemple, chown td-agent [FILE].

  2. Pour commencer à collecter des journaux dans Oracle Cloud Log 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 Log Analytics

Accédez à l'explorateur de journaux et utilisez le panneau Visualiser d'Oracle Cloud Log Analytics pour visualiser les données de journal sous une forme qui vous aide à mieux comprendre et 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.

Surveillance de Fluentd avec Prométhée

Vous pouvez en option surveiller Fluentd à l'aide de Prométhée. Pour connaître les étapes permettant d'afficher les mesures ci-dessous et les autres mesures émises par Fluentd vers Prometheus, reportez-vous à Documentation Fluentd : Surveillance par Prometheus. Si vous souhaitez surveiller uniquement le module d'extension Fluentd principal et ces mesures, ignorez les étapes Etape 1 : Comptage des enregistrements entrants par le module d'extension de filtre Prométhée et Etape 2 : Comptage des enregistrements sortants par le module d'extension de sortie Prométhée 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 :

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

En savoir plus

Autres ressources de formation

Explorez d'autres tutoriels sur Oracle Learn ou accédez à d'autres contenus de formation gratuits sur le canal Oracle Learning YouTube. En outre, visitez Oracle Education pour devenir un explorateur Oracle Learning.

Pour obtenir de la documentation sur le produit, consultez Oracle Help Center.