Présentation

Utilisez Fluentd, le logiciel de collecte de données à code source libre, pour collecter les données de journal à partir de votre source. Installez le plugiciel de sortie OCI Log Analytics pour acheminer les données de journal collectées vers Oracle Cloud Log Analytics.

Note : Oracle recommande d'utiliser les agents de gestion Oracle Cloud pour obtenir la meilleure expérience d'ingestion de données de journal dans Oracle Cloud Log Analytics. Toutefois, si cela n'est pas possible pour votre cas d'utilisation, utilisez uniquement le plugiciel de sortie OCI Log Analytics pour Fluentd.

Dans ce tutoriel, une configuration Fluentd est utilisée, basée sur l'ensemble td-agent rpm installé sur Oracle Linux, mais les étapes requises peuvent être similaires pour d'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 plugiciel de sortie pour Fluentd afin qu'il ingère les journaux de diverses sources dans Oracle Cloud Log Analytics.

Description de l'illustration fluentd_plugin_overview.png

Objectifs

  • Voyez comment installer le plugiciel de sortie Log Analytics pour OCI fourni par Oracle pour ingérer les journaux à partir de votre source.
  • Créez la configuration Fluentd pour établir la collecte de journaux de votre source vers Log Analytics.

Migrer le plugiciel de sortie OCI Log Analytics de la version 1.x vers 2.x

Si vous êtes un nouvel utilisateur du plugiciel de sortie Log Analytics pour OCI et que vous devez encore le télécharger et l'installer, ignorez cette section et allez à Préalables. Si vous avez installé le plugiciel version 1.x à l'aide du fichier fluent-plugin-oci-logging-analytics-1.0.0.gem, notez que vous devrez peut-être apporter des modifications pour migrer vers le plugiciel version 2.x.

Les paramètres de configuration suivants sont renommés dans version 2.x :
1.x 2.x
global_metadata oci_la_global_metadata
métadonnées oci_la_metadata
entityId 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
  • La prise en charge est ajoutée pour l'épuration automatique des journaux du plugiciel de sortie Log Analytics pour OCI.
  • Le paramètre plugin_log_rotation est maintenant obsolète. Utilisez plutôt les paramètres plugin_log_file_size et plugin_log_file_count conjointement pour effectuer la même action.
  • Installez le plugiciel version 2.x à l'aide de la commande disponible dans la section Installer le plugiciel de sortie.

Effectuer les tâches préalables

Créer le fichier de configuration Fluentd

Pour configurer Fluentd pour acheminer 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 plugiciel 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 plugiciel secondaire qui serait utilisé par Fluentd pour vider les données de sauvegarde lorsque le plugiciel de sortie continue d'échouer en écrivant les blocs de mémoire tampon et dépasse le seuil de temporisation pour les nouvelles tentatives. En outre, pour les erreurs irrécupérables, Fluentd abandonnera immédiatement le bloc et le déplacera dans le répertoire secondaire ou le répertoire de sauvegarde. Reportez-vous à la documentation sur Fluentd : Sortie secondaire.

Paramètres de configuration du plugiciel de sortie

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

Paramètre de configuration Description
espace de noms (Paramètre obligatoire) Espace de noms de la location OCI vers lequel les données de journal collectées doivent être 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 Mandataire sans données d'identification. Exemple : www.proxy.com:80
proxy_ip Détails de l'adresse IP du mandataire lorsque les données d'identification sont requises. Exemple : www.proxy.com
proxy_port Détails du port du mandataire lorsque les données d'identification sont requises. Exemple : 80
proxy_username Détails du nom d'utilisateur du mandataire
proxy_password Détails du mot de passe du mandataire lorsque les données d'identification sont requises
plugin_log_location Chemin d'accès au fichier pour le plugiciel de sortie afin d'écrire 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 plugiciel 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 plugiciel 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/roités à conserver (supérieur à 0). Valeur par défaut : 10.

Si vous ne spécifiez pas les paramètres config_file_location et profile_name pour les noeuds du service de calcul pour OCI, l'authentification basée sur instance_principal est utilisée.

Paramètres de configuration de mémoire 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 plugiciel à utiliser en tant que serveur dorsal. Entrez un fichier.
chemin Chemin d'accès au stockage des fichiers tampons. 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 d'unités d'exécution à vider/écrire des fragments 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 Faux.
retry_exponential_backoff_base 2 Attendez en secondes avant le facteur constant suivant de l'attente exponentielle.
retry_forever false Si true, le plugiciel ignore l'option retry_max_times et réessaie de vider définitivement.
overflow_action throw_exception Valeurs possibles : throw_exception / block / drop_oldest_chunk. Valeur recommandée : bloc.
disable_chunk_backup false Lorsque vous spécifiez Faux, les fragments non récupérables dans le répertoire de sauvegarde sont abandonnés.
chunk_limit_size 8MB Taille maximale de chaque fragment. Les événements seront écrits en fragments jusqu'à ce que la taille des fragments devienne cette taille. Note : Quelle que soit la valeur spécifiée, la valeur par défaut du plugiciel de sortie Log Analytics est actuellement de 1 Mo.
total_limit_size 64GB (pour le fichier) Une fois que la taille totale de la mémoire tampon stockée a atteint ce seuil, toutes les opérations d'ajout échoueront avec une erreur (et les données seront perdues).
flush_interval 60s Fréquence de vidage des fragments vers le plugiciel de sortie.

Pour plus de détails sur les valeurs possibles des paramètres, voir Documentation de Fluentd : Plugiciels tampon.

Vérifier le format des événements de journal entrants

Les événements de journal entrants doivent être dans un format spécifique afin que le plugiciel 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 dans Exemple de configuration d'entrée.

Configuration du plugiciel d'entrée/source

Exemple de configuration de 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 plugiciel d'entrée. Utilisez la queue pour consommer les événements d'un fichier local. Les autres valeurs possibles peuvent être http, forward.

  • chemin : Chemin d'accès aux fichiers sources.

  • marqueur : Marqueur qui sera utilisé par le plugiciel Fluentd d'Oracle pour filtrer les événements de journal qui doivent être consommés par Log Analytics. Assurez-vous d'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>. À 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 encapsuleur json, utilisez la directive d'analyse <parse> @type json </parse>. Remplacez le champ de message du filtre record_transformer par la valeur ${record["log"]}.

    Remarque :

    • Il est recommandé de ne pas utiliser d'analyseurs Fluentd. Au lieu de cela, envoyez les journaux à Log Analytics dans le format initial. La directive Parse doit être de la forme suivante :

      <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. Par 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 initiaux encapsulés par l'encapsuleur json dont 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>

    Et, remplacez 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 des journaux est stocké dans la valeur du journal de clé qui est encapsulé 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 multiligne afin de vous assurer que tous les journaux sont consommés par Log Analytics. Si la valeur n'est pas définie pour les journaux multiligne, Fluentd restera en mode d'attente pour le lot d'enregistrements suivant. Par défaut, ce paramètre est désactivé.
  • pos_file : Utilisez ce paramètre pour spécifier le fichier dans lequel Fluentd conserve l'enregistrement de la position qu'il a lue en dernier.

Pour plus d'informations sur d'autres paramètres, voir Documentation sur Fluentd : tail.

Filtrer la configuration

Utilisez ces paramètres pour lister les ressources Log 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 plugiciel 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 plugiciel de filtre record_transformer pour modifier le format en conséquence.

Conseil : Notez que la configuration du plugiciel 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 de Fusion.

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 le marqueur spécifié dans le bloc source.
  • @type record_transformer : Le plugiciel de transformateur d'enregistrements transforme l'enregistrement de journal initial en un formulaire qui peut être utilisé par le plugiciel de sortie Log Analytics pour OCI.
  • enable_ruby : Permet l'utilisation de 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 préalable pour mapper 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 préalable.
  • oci_la_log_source_name : Source Log Analytics qui doit être utilisée pour traiter les enregistrements de journal.
  • oci_la_log_path : Spécifiez l'emplacement initial des fichiers journaux. Si la valeur de oci_la_log_path n'est pas privée ou n'est pas valide, alors :
    • si le marqueur est disponible, il est utilisé comme oci_la_log_path
    • si marqueur n'est pas disponible, oci_la_log_path est réglé à Non défini
  • oci_la_log_group_id : OCID du groupe de journaux Log Analytics où les journaux doivent être stockés.

Vous pouvez éventuellement indiquer 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 entre 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 au niveau de la source remplacera le filtre global. Il est recommandé d'utiliser oci comme préfixe pour tous les marqueurs.
  • oci_la_global_metadata : Utilisez ce paramètre pour spécifier des métadonnées supplémentaires ainsi que le contenu de journal initial dans Log Analytics dans le format 'key1': 'value1', 'key2': 'value2'. Ici, la clé est le champ Log Analytics qui doit déjà être défini avant de l'indiquer 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 initial du journal dans Log Analytics dans le format 'key1': 'value1', 'key2': 'value2'. Ici, la clé est le champ Log Analytics qui doit déjà être défini avant de l'indiquer ici.
  • marqueur : Utilisez ce paramètre pour joindre un marqueur au message à des fins d'utilisation interne. Indiquez le format tag ${tag}.
  • message ${record["log"]} : Incluez ce paramètre pour les journaux qui sont encapsulés dans un encapsuleur json où le message de journal initial est la valeur de l'attribut log dans le json.

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

Installer le plugiciel de sortie

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

  1. Installez le plugiciel de sortie en exécutant la commande suivante :

    gem install fluent-plugin-oci-logging-analytics

Pour plus d'informations, voir Plugiciel de sortie Fluentd pour expédier 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 du plugiciel de sortie Log Analytics pour OCI 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 le débogage si vous rencontrez des problèmes lors de la collecte des journaux ou lors 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 la consultation des journaux dans Log Analytics

Allez à l'explorateur de journaux et utilisez le panneau Visualiser d'Oracle Cloud Log Analytics pour voir les données de journal sous une forme qui vous aide à mieux comprendre et analyser. En fonction de ce que vous souhaitez obtenir avec votre jeu de données, vous pouvez sélectionner le type de visualisation qui convient le mieux à votre application.

Après avoir créé et exécuté une interrogation de recherche, vous pouvez enregistrer et partager vos recherches dans les journaux en tant que widgets pour les réutiliser.

Vous pouvez créer des tableaux de bord personnalisés dans 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 avec Prometheus

Vous pouvez facultativement surveiller Fluentd à l'aide de Prometheus. Pour les étapes permettant d'exposer les mesures ci-dessous et les autres mesures émises par Fluentd vers Prometheus, voir Documentation sur Fluentd : Surveillance par Prometheus. Si vous voulez surveiller uniquement le module Fluentd de base et ces mesures, ignorez les étapes Étape 1 : Comptage des enregistrements entrants par le plugiciel de filtre Prometheus et Étape 2 : Comptage des enregistrements sortants par le plugiciel de sortie Prometheus dans la documentation Fluentd référencée.

Le plugin Fluentd émet les mesures suivantes au format Prometheus, qui fournit des informations sur les données collectées et traitées par le 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

En savoir plus

Autres ressources d'apprentissage

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

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