Structure du fichier de configuration de l'adaptateur

Un fichier de configuration d'adaptateur comporte une collection de contextes devant être exécutés par une instance d'exécution de l'adaptateur de journal générique. Chaque contexte décrit le mode de traitement d'un fichier journal simple. Etant donné que le fichier de configuration d'adaptateur peut contenir de nombreux contextes, l'adaptateur peut traiter de nombreux fichiers journaux à la fois.

Chaque contexte associé à un fichier journal particulier est constitué d'une série de composants. Chaque composant a un rôle à jouer dans le traitement du fichier journal.

Le diagramme suivant montre la structure type d'une configuration d'adaptateur de journal générique.

Diagramme montrant un adaptateur avec un contexte unique et un certain nombre de composants

Contexte

Le contexte décrit le groupement ordonné des composants tels qu'ils s'enchaînent pour le traitement des fichiers journaux. Chaque fichier journal dispose d'un contexte distinct et il est possible de définir plusieurs contextes dans une seule et même configuration. L'adaptateur de journal générique fournit deux implémentations de contexte :

Un contexte dispose des propriétés suivantes :

Propriété Type Comportement
Description Chaîne Description du contexte. Cette valeur est utilisée uniquement par l'éditeur de configuration d'adaptateur.
ID unique Chaîne Identificateur unique du contexte. Le contexte se réfère à cette chaîne pour identifier l'instance du composant à utiliser.
Opération continue Booléen Indique si les modifications apportées au fichier journal doivent être surveillées selon les propriétés Délai d'inactivité maximal et Intervalle d'interruption.
Délai d'inactivité maximal Entier (millisecondes) Durée maximale pendant laquelle le contexte attend qu'un fichier journal soit modifié avant de s'arrêter.
Intervalle d'interruption Entier (millisecondes) Durée pendant laquelle le contexte doit patienter après avoir atteint la fin d'un fichier journal avant de tenter une nouvelle lecture.
Code de langue ISO Code de langue de l'environnement local dans lequel le fichier journal a été généré. Ces codes sont les codes à deux lettres minuscules définis dans la norme ISO-639. Vous trouverez la liste complète de ces codes sur de nombreux sites, comme par exemple : http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt. Si cette valeur n'est pas spécifiée, c'est la langue de l'environnement local courant dans lequel l'adaptateur de journal générique est exécuté qui sera utilisée. Cette valeur est utilisée lors de l'analyse syntaxique d'horodatages dans le fichier journal.
Code pays ISO Code pays de l'environnement local dans lequel le fichier journal a été généré. Ces codes sont les codes à deux lettres majuscules définis dans la norme ISO-3166. Vous trouverez la liste complète de ces codes sur de nombreux sites comme, par exemple : http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html. Si cette valeur n'est pas spécifiée, ce sera le pays de l'environnement local courant dans lequel l'adaptateur de journal générique est exécuté qui sera utilisé. Cette valeur est utilisée lors de l'analyse syntaxique d'estampilles temporelles dans le fichier journal.
Codage Codage des caractères du fichier journal à analyser. La valeur de codage spécifiée doit figurer dans la liste du IANA Charset Registry (http://www.iana.org/assignments/character-sets) et doit être prise en charge par le JVM dans lequel l'adaptateur de journal générique est exécuté. Si cette valeur n'est pas spécifiée, le fichier journal sera analysé à l'aide du codage de fichier par défaut du JVM dans lequel l'adaptateur de journal générique est exécuté, qui est spécifié dans les propriétés système file.encoding JVM.

Détecteur

Le détecteur fournit le mécanisme de lecture du contenu du journal en vue de son traitement. L'adaptateur de journal générique fournit les détecteurs suivants :

Le tableau suivant répertorie les attributs communs aux types de détecteur.

Attributs des détecteurs

Nom d'attribut Type Comportement
Type de détecteur Chaîne Type de détecteur à utiliser par l'adaptateur.
Description (obligatoire) Chaîne Description du détecteur. Cette valeur est utilisée uniquement par l'éditeur de configuration d'adaptateur.
ID unique (obligatoire) Chaîne Identificateur unique du composant. Le détecteur se réfère à cette chaîne pour identifier l'instance du composant à utiliser.
Blocage maximal (obligatoire) Entier Nombre maximal de lignes lues par le détecteur avant la transmission à l'extracteur pour traitement. Pour le type StaticParserSensor, cette zone indique le nombre maximal d'objets CBE créés par le programme d'analyse statique avant la transmission au module Outputter pour traitement.
Taille de la mémoire tampon de référence Entier Les n derniers octets d'un fichier à sauvegarder et permettant de savoir si un ajout a eu lieu dans le fichier depuis sa dernière lecture.
Taille du bas de page du fichier Entier Les n octets d'un fichier qui contient du contenu statique. Certains fichiers journaux ajoutent un bas de page à la fin du fichier journal. Cette partie du fichier journal n'est pas considérée comme des données de journal. Le bas de page d'un fichier n'est pas utilisé pour savoir si un ajout a eu lieu dans le fichier depuis sa dernière lecture.

Le tableau suivant répertorie les propriétés spécifiques de chaque type de détecteur. Les propriétés suivantes sont connues par le code du composant et doivent être orthographiées exactement telles qu'elles sont indiquées dans le tableau pour être reconnues et utilisées par le composant.

Type de détecteur Propriétés Application
SingleFileSensor
directory (obligatoire)
Emplacement du répertoire du fichier devant être lu par SinlgeFileSensor.
fileName (obligatoire)
Nom du fichier devant être lu par SingleFileSensor. Si l'application utilise la rotation de fichier journal, des expressions régulières peuvent être utilisées pour spécifier le nom du fichier.
Remarque : la casse est prise en compte lors de l'interprétation de la zone fileName. Si vous souhaitez que la zone ne soit pas sensible à la casse, spécifiez le nom du fichier à l'aide d'une expression régulière.
shell
Shell UNIX dans lequel exécuter la commande converter. Utilisé uniquement sur les plateformes UNIX.
converter
Ligne de commande d'une instruction de pré-traitement à exécuter avant de lancer le détecteur.
Utilisé lors de la création d'un adaptateur en vue de l'analyse syntaxique d'un fichier journal avec des règles d'expression régulière.
StaticParserSensor
directory (obligatoire)
Emplacement du répertoire du fichier devant être lu par StaticParserSensor.
fileName (obligatoire)
Nom du fichier devant être lu par StaticParserSensor.
parserClassName (obligatoire)
Nom de la classe Java qui implémente le programme d'analyse statique. La classe doit implémenter l'interface org.eclipse.hyades.logging.parsers.IParser.
Utilisé lors de la création d'un adaptateur en vue de l'analyse syntaxique d'un fichier journal avec une classe Java de programme d'analyse statique.

Extracteur

L'extracteur extrait plusieurs lignes d'entrée fournies par le détecteur et les sépare en frontières de message.

L'adaptateur de journal générique fournit les extracteurs suivants :

Les propriétés suivantes sont indiquées dans la configuration de l'extracteur :

Propriété Type Comportement
Description Chaîne Description de l'extracteur. Cette valeur est utilisée uniquement par l'éditeur de configuration d'adaptateur.
ID unique Chaîne Identificateur unique du composant. L'extracteur se réfère à cette chaîne pour identifier l'instance du composant à utiliser.
Contient des retours à la ligne Booléen Indique si les messages du fichier journal s'étendent sur plusieurs lignes.
Remplace les retours à la ligne Booléen Remplace les retours à la ligne du fichier par un autre segment de chaîne. Le remplacement est effectué avant que l'extracteur ne recherche les schémas de début et de fin.
Remarque : l'effet secondaire de l'utilisation de cette option est que les valeurs analysées à partir du fichier journal ne contiendront pas de sauts de ligne, à moins que ces derniers ne soient ajoutés explicitement par les règles de substitution de l'interpréteur.
Symbole de retour à la ligne Chaîne Segment de chaîne devant remplacer les retours à la ligne. Est utilisé uniquement si la propriété Remplace les retours à la ligne prend la valeur True.
Inclure le schéma de début Booléen Indique si le schéma de début doit être inclus dans le message à transmettre au prochain composant. Si la valeur est False, la partie correspondante du message est rayée.
Schéma de début Chaîne ou expression régulière Segment de chaîne identifiant le début d'un message. Vous pouvez toujours utiliser la classe RegularExpressionExtractor. Toutefois, si le schéma de début est une chaîne simple, la classe SimpleExtractor utilise moins de temps système.
Inclure le schéma de fin Booléen Indique si le schéma de fin doit être inclus dans le message à transmettre au prochain composant. Si la valeur est False, la partie correspondante du message est rayée.
Schéma de fin Chaîne ou expression régulière Segment de chaîne identifiant la fin d'un message. Si le schéma de fin n'est pas spécifié, le message est délimité par le schéma de fin suivant.

Analyseur

Le programme d'analyse syntaxique prend les messages délimités par l'extracteur et génère un ensemble de mappages de valeurs de chaîne vers une structure de données. Dans le cas de l'adaptateur de journal générique, la structure de données est CBE 1.0.1

L'adaptateur de journal générique fournit la classe de programme d'analyse syntaxique suivante :

Le programme d'analyse syntaxique est exécuté en deux phases :

  1. la phase de traitement global, pendant laquelle un ensemble d'expressions régulières globales est exécuté sur le message fourni par l'extracteur ;
  2. la phase de traitement des attributs, pendant laquelle des ensembles spécifiques de règles de substitution sont exécutés pour déterminer la valeur à affecter à chaque attribut de la structure de données (CBE 1.0.1).

Les deux phases d'exécution permettent la segmentation du message en une série de valeurs d'attribut pendant la phase de traitement global. Il est ensuite possible de faire référence aux valeurs d'attribut par les noms d'attribut ou l'index pendant la phase de traitement des attributs.

Les propriétés globales suivantes sont spécifiées dans le programme d'analyse syntaxique :

Propriété Type Comportement
Description Chaîne Description du programme d'analyse syntaxique. Cette valeur est utilisée uniquement par l'éditeur de configuration d'adaptateur.
ID unique Chaîne Identificateur unique du composant. Le programme d'analyse syntaxique se réfère à cette chaîne pour identifier l'instance du composant à utiliser.
Sème de séparateur Chaîne ou expression régulière Sème ou expression régulière décrivant une série de sèmes, pouvant décomposer le message en paires attribut-valeur.

Par exemple, si chaque nouvelle ligne du fichier journal comporte un attribut et sa valeur, vous pouvez spécifier un sème de séparateur \n. L'avantage de la décomposition du message est la possibilité de référence aux segments de chaîne dans la phase de traitement des attributs.
Remarque : si un jeton de séparation n'est pas spécifié, aucun traitement global n'est effectué.

Sème de désignation Chaîne ou expression régulière Sème ou expression régulière décrivant une série de sèmes, pouvant décomposer les segments de chaîne créés par le sème de désignation en paires attribut-valeur. Par exemple, si chaque attribut et chaque valeur sont séparés par le signe =, et que la valeur du sème de désignation est =, il est possible de faire référence à l'attribut et à sa valeur lors de la phase de traitement des attributs. Si un sème de séparateur est spécifié, mais qu'aucun sème de désignation n'est indiqué, le message est décomposé en une liste de valeur d'attribut, à laquelle il est possible de faire référence dans les règles de substitution via l'index.

Les attributs individuels de CBE ont les propriétés suivantes :

Remarque : les blancs devant et derrière les valeurs analysées seront supprimés au cours du traitement global. Dès lors, les règles de substitution qui utilisent des valeurs de position peuvent être écrites en assumant que les valeurs ne sont plus précédées ni suivies de blancs.

Propriété Type Comportement
Utiliser la substitution de l'occurrence précédente comme valeur par défaut Booléen Si l'ensemble de règles de substitution en cours pour cet attribut renvoi une correspondance positive, stockez la valeur de correspondance de telle sorte qu'elle puisse être utilisée comme valeur par défaut pour traiter l'enregistrement suivant s'il n'existe pas de correspondance positive.
Valeur par défaut Chaîne Si aucune règle de substitution de cet attribut ne fournit de correspondance positive ou s'il n'existe aucune règle de substitution pour cet attribut, la valeur par défaut spécifiée ici lui est affectée. Si vous souhaiter affecter la même valeur à tous les enregistrements d'un attribut particulier, vous pouvez employer cette propriété au lieu de créer une règle de substitution par défaut pour cet attribut. La propriété Utiliser la substitution de l'occurrence précédente comme valeur par défaut est prioritaire si aucune valeur sauvegardée n'est disponible.
Requis par le parent Booléen Permet de spécifier si cet élément doit avoir une valeur valide pour que l'élément parent soit valide. Par exemple, si cette option est sélectionnée pour l'élément situation, cela indique à l'interpréteur que l'objet Common Base Event doit avoir un élément situation valide. Au cours du traitement, si l'élément situation renvoie une valeur nulle, l'analyseur syntaxique ne traitera aucun des autres éléments enfant de l'objet Common Base Event car il sait déjà que cet objet Common Base Event est non valide parce qu'un élément enfant obligatoire a renvoyé une valeur non valide.
Choix de l'enfant Booléen Permet de spécifier s'il faut arrêter le traitement de cet élément une fois qu'un attribut ou élément d'enfant valide renvoie une valeur valide. Par exemple, imaginez une situation avec trois éléments enfant, ReportSituation, RequestSituation et StartSituation, chacun avec ses propres sous-arborescences. Si l'option Choix de l'enfant est sélectionnée pour l'élément situation, l'analyse s'arrête à la première sous-arborescence qui renvoie une valeur valide.

Les règles de substitution sont exécutées au cours de la phase de traitement des attributs. Elles sont traitées dans l'ordre, du haut vers le bas. Lorsqu'une règle trouve une occurrence, les autres règles ne sont pas exécutées sur cette propriété. Si aucune occurrence n'est trouvée, aucune valeur n'est placée dans l'attribut, sauf si la propriété Utiliser la substitution de l'occurrence précédente comme valeur par défaut ou Valeur par défaut de l'attribut est spécifiée.

Les règles de substitution ont les propriétés suivantes :

Propriété Type Comportement
Occurrence Expression régulière Expression régulière identifiant la valeur à appliquer à cet attribut si une occurrence est trouvée dans la portée du segment de chaîne traité par cette règle de substitution. Si vous n'indiquez pas d'expression régulière, la règle est considérée comme une occurrence.
Positions Paires d'attribut nom-valeur Paires d'attribut nom-valeur créées lors de la phase de traitement global.
  • Si un sème de séparateur et un sème de désignation sont spécifiés en même temps, la chaîne Positions peut faire référence à de nombreux attributs par leur nom, via la syntaxe suivante : $h('Attr1')@@$h('Attr2')...
    $h('Attrn') identifie un nom d'attribut précédemment créé
    et @@ est le séparateur figurant entre les attributs.
  • Si un sème de séparateur est spécifié, mais qu'aucun sème de désignation n'est indiqué, la chaîne Positions peut faire référence à un ou plusieurs attributs par l'index, et non par le nom, via la syntaxe suivante : n1@@n2..
    où n1 et n2 sont des entiers représentant les indices. L'index commence à 1. Si la chaîne du message commence par un sème de séparateur, la valeur d'attribut d'index 1 a pour valeur null. La première valeur d'attribut commence alors à l'index 2.

Dans la propriété Occurrence, vous pouvez ajouter un séparateur pour indiquer les expressions régulières à appliquer à telle valeur d'attribut.

Substituer Chaîne Valeur à placer dans l'attribut. Il peut s'agir d'une chaîne ou d'une référence à l'expression régulière de la propriété Occurrence. Il est possible de faire référence aux segments de chaîne extraits par la propriété Occurrence en utilisant les regroupements dans l'expression régulière. $1 indique le premier regroupement, $2 le deuxième, et ainsi de suite.
Utiliser la fonction intégrée Case à cocher La propriété Utiliser la fonction intégrée sélectionnée pour un attribut, si aucune des règles de substitution précédentes, le cas échéant, ne trouve de correspondance, entraîne la génération par l'adaptateur de fichier journal d'une valeur pour l'attribut utilisant ses propres fonctions internes. Cette fonction n'est prise en charge que par les attributs CBE suivants :
  • localInstanceId
  • globalInstanceId
  • componentIdentification.location
  • componentIdentification.locationType
Classe d'extension de substitution Chaîne Spécifie le nom d'une classe Java créée par l'utilisateur pouvant analyser de manière personnalisée la syntaxe de la logique de la valeur correspondant aux spécifications Positions, Occurrence et Substituer de la règle. Si la règle de substitution correspond aux données de l'enregistrement, cette classe est appelée et le résultat est utilisé pour la création de l'objet CBE.
Spécifications :
  • Cette classe doit implémenter la classe d'interface org.eclipse.hyades.logging.adapter.parsers.ISubstitutionExtension ou la classe d'extension org.eclipse.hyades.logging.adapter.parsers.IStatefulSubstitutionExtension pour que cette dernière soit exécutée par l'adaptateur de journal générique.
  • Utilisez la classe d'extension lorsque vous souhaitez sauvegarder les données d'état entre les enregistrements du fichier journal. La classe org.eclipse.hyades.logging.adapter.parsers.IStatefulSubstitutionExtension indique à l'adaptateur de journal générique d'allouer uniquement une instance de cette classe pour l'analyse syntaxique de tous les enregistrements du fichier journal.
  • La classe de l'utilisateur doit être incluse dans le chemin d'accès aux classes du module d'exécution de l'adaptateur de journal générique.
  • Si l'adaptateur de journal générique est exécuté dans un environnement Eclipse, la classe peut être créée comme une extension de plug-in eclipse de l'adaptateur de journal générique via l'utilisation du point d'extension substitutionExtension du plug-in org.eclipse.hyades.logging.adapter.
Format de l'heure Chaîne Cette zone s'applique uniquement aux règles de substitution de l'élément creationTime et est utilisée pour simplifier l'analyse syntaxique de la date et de l'heure. Par exemple, certains fichiers journaux contiennent des horodatages incluant les noms de mois au lieu des représentations numériques correspondantes. Cela rend ainsi difficile la création des règles de substitution devant générer la valeur de la chaîne au format du type de données dateTime du schéma XML requis par l'élément CBE creationTime. Dans ce cas, l'utilisateur peut spécifier une chaîne de format de date Java simple, comme indiqué dans la documentation javadoc relative à java.text.SimpleDateFormat (java.sun.com/j2se/1.4.2/docs/api/java/text/SimpleDateFormat.html) dans la zone Format de l'heure. La valeur correspondant aux spécifications Positions, Occurrence et Substituer de la règle est analysé en fonction de la chaîne Format de l'heure et ma valeur résultante est utilisée pour générer la valeur CBE creationTime.
Remarque : l'environnement local, tel que représenté par les valeurs des codes de langue et de pays ISO spécifiés dans la configuration de l'instance de contexte, est utilisé lors de l'analyse de l'horodatage avec la chaîne du format d'heure.

Module de formatage

Le module de formatage effectue le mappage des attributs vers leurs valeurs fournies par le programme d'analyse syntaxique et compile l'instance d'objet Java appropriée. Le module d'exécution de l'adaptateur comporte un seul module de formatage qui crée les objets CBE conformément à la spécification CBE 1.0.1.

Le module de formatage a les propriétés suivantes :

Propriété Type Comportement
ID unique Chaîne Identificateur unique du composant. Le module de formatage se réfère à cette chaîne pour identifier l'instance du composant à utiliser.
Description Chaîne Description du module de formatage. Cette valeur est utilisée uniquement par l'éditeur de configuration d'adaptateur.

Outputter

Le module Outputter externalise les enregistrements CBE résultants fournis par le module de formatage. Les modules Outputter fournissent ou recherchent en boucle le mécanisme de stockage des sorties finales du contexte. L'adaptateur de journal générique fournit les composants outputter suivants :

Propriétés de module Outputter :

Propriété Type Comportement
ID unique Chaîne Identificateur unique du composant. Le module Outputter se réfère à cette chaîne pour identifier l'instance du composant à utiliser.
Description Chaîne Description du module Outputter. Cette valeur est utilisée uniquement par l'éditeur de configuration d'adaptateur.
Type d'outputter Enumération Type de module Outputter.

Types d'outputter et propriétés obligatoires :

Type d'outputter Propriétés obligatoires
StandardOutOutputter Aucune
SingleFileOutputter directory, fileName
LoggingAgentOutputter agentName - nom donné à l'agent de consignation lors de sa création
waitUntilLoggingTime (facultatif) - durée pendant laquelle le module Outputter attend que l'utilisateur associe et démarre la surveillance de l'agent avant qu'il ne commence à écrire sur l'agent. Si cette propriété n'est pas spécifiée, le module Outputter n'attend pas la surveillance de l'agent avant d'y écrire des informations.

 

Concepts connexes
Présentation de l'adaptateur de journal générique Hyades
Spécification du format Common Base Event

Tâches connexes
Création d'un programme d'analyse syntaxique de journaux
Création d'un adaptateur fondé sur des règles
Création d'un adaptateur statique

Références associées
Structure du fichier de configuration d'adaptateur
Spécification du format Common Base Event
Editeur de configuration d'adaptateur
Syntaxe d'une expression régulière