Règle de journalisation des messages

Vous consultez la documentation d'Apigee Edge.
Consultez la documentation Apigee X.
en savoir plus

Quoi

L'un des meilleurs moyens de suivre les problèmes dans l'environnement d'exécution de l'API consiste à consigner les messages. Vous pouvez associer et configurer une règle MessageLogging sur votre API pour consigner les messages personnalisés sur un disque local (Edge pour Private Cloud uniquement) ou sur syslog.

Samples

Syslog

<MessageLogging name="LogToSyslog">
  <Syslog>
    <Message>[3f509b58 tag="{organization.name}.{apiproxy.name}.{environment.name}"] Weather request for WOEID {request.queryparam.w}.</Message>
    <Host>logs-01.loggly.com</Host>
    <Port>514</Port>
    <Protocol>TCP</Protocol>
    <FormatMessage>true</FormatMessage>
    <DateFormat>yyyy-MM-dd'T'HH:mm:ss.SSSZ</DateFormat>
  </Syslog>
  <logLevel>ALERT</logLevel>
</MessageLogging>

Une utilisation courante du type de règle MessageLogging consiste à se connecter à un compte syslog. Lorsqu'il est configuré pour syslog, un proxy d'API transfère les messages de journal d'Apigee Edge à un serveur syslog distant. Vous devez déjà disposer d'un serveur syslog. Si ce n'est pas le cas, les services de gestion des journaux publics, tels que Splunk, Sumo Logic et Loggly, sont disponibles. Consultez la section Configurer des services de gestion de journaux tiers.

Par exemple, imaginez que vous deviez consigner des informations sur chaque message de requête que votre API reçoit des applications clientes. La valeur 3f509b58 représente une valeur de clé spécifique au service Loggly. Si vous avez un compte Loggly, remplacez votre clé Loggly. Le message de journal généré est renseigné avec quatre valeurs : l'organisation, le proxy d'API et le nom de l'environnement associés à la transaction, ainsi que la valeur d'un paramètre de requête sur le message de requête.

Si vous disposez d'un déploiement Edge pour Private Cloud, vous pouvez également écrire des messages de journal dans un fichier.

Syslog via TLS/SSL

<MessageLogging name="LogToSyslog">
  <Syslog>
    <Message>[3f509b58 tag="{organization.name}.{apiproxy.name}.{environment.name}"] Weather request for WOEID {request.queryparam.w}.</Message>
    <Host>logs-01.loggly.com</Host>
    <Port>6514</Port>
    <Protocol>TCP</Protocol>
    <FormatMessage>true</FormatMessage>
    <SSLInfo>
        <Enabled>true</Enabled>
    </SSLInfo>
    <DateFormat>yyMMdd-HH:mm:ss.SSS</DateFormat>
  </Syslog>
  <logLevel>WARN</logLevel>
</MessageLogging>

Vous pouvez envoyer des messages à des fournisseurs de journalisation de messages tiers via TLS/SSL en ajoutant le bloc <SSLInfo>.

Rotation des fichiers : taille

<MessageLogging name="LogPolicy">
  <File>
    <Message>This is a test message. Message id : {request.header.messageid}</Message>
      <FileName>test.log</FileName>
      <FileRotationOptions rotateFileOnStartup="true">
        <FileRotationType>SIZE</FileRotationType>
        <MaxFileSizeInMB>10</MaxFileSizeInMB>
        <MaxFilesToRetain>10</MaxFilesToRetain>
      </FileRotationOptions>
  </File>
  <logLevel>ERROR</logLevel>
</MessageLogging>

Rotation des fichiers basée sur la taille.

Rotation des fichiers : heure

<MessageLogging name="LogPolicy">
  <File>
    <Message>This is a test message. Message id : {request.header.messageid}</Message>
    <FileName>test.log</FileName>
    <FileRotationOptions rotateFileOnStartup="true">
      <FileRotationType>TIME</FileRotationType>
      <RotationFrequency unit="minute">10</RotationFrequency>
      <MaxFilesToRetain>10</MaxFilesToRetain>
    </FileRotationOptions>
  </File>
  <logLevel>ERROR</logLevel>
</MessageLogging>

Rotation des fichiers basée sur l'heure.

Rotation des fichiers : heure et taille

<MessageLogging name="LogPolicy">
  <File>
    <Message>This is a test message. Message id : {request.header.messageid}</Message>
    <FileName>test.log</FileName>
    <FileRotationOptions rotateFileOnStartup="true">
      <FileRotationType>TIME_SIZE</FileRotationType>
      <MaxFileSizeInMB>10</MaxFileSizeInMB>
      <MaxFilesToRetain>10</MaxFilesToRetain>
      <RotationFrequency unit="minute">10</RotationFrequency>
    </FileRotationOptions>
  </File>
  <logLevel>ERROR</logLevel>
</MessageLogging>

Rotation des fichiers basée sur l'heure et la taille.

Compatible avec le streaming

<MessageLogging name="LogPolicy">
  <File>
  ....
  ....
  </File>
  <BufferMessage>true</BufferMessage>
</MessageLogging>

Journalisation des messages compatible avec le streaming


Documentation de référence des éléments

Utilisez les éléments suivants pour configurer le type de stratégie MessageLogging.

Nom du champ Description du champ

File

Destination du fichier local. (La journalisation des fichiers n'est prise en charge que dans Edge pour les déploiements de cloud privé.) Pour plus d'informations sur l'emplacement de stockage des fichiers, consultez la section Emplacement des fichiers journaux dans Edge for Private Cloud.

Message Créez le message à envoyer dans le fichier journal, en combinant du texte avec des variables pour capturer les informations souhaitées. Consultez les exemples.
FileName Nom du fichier journal dans lequel le message est consigné.
FileRotationOptions
rotateFileOnStartup

Attribut. Valeurs valides: true/false

Si la valeur est "true", le fichier journal est alterné chaque fois que le moteur de messagerie redémarre.

FileRotationType Spécifie la règle de rotation (size ou time) d'un fichier journal.
MaxFileSizeInMB (Lorsque vous sélectionnez size comme type de rotation) Spécifie la taille d'un fichier journal qui déclenche le déplacement des messages de journal vers un fichier distinct par le serveur. Lorsque le fichier journal atteint la taille spécifiée, le serveur renomme le fichier journal actuel.
RotationFrequency (Lorsque vous sélectionnez time comme type de rotation) Spécifie le délai, en minutes, qui déclenche le déplacement des messages de journal vers un fichier distinct. Une fois l'intervalle spécifié écoulé, le fichier journal actuel est renommé.
MaxFilesToRetain

Spécifie le nombre maximal de fichiers à conserver dans le contexte de vos paramètres de rotation. La valeur par défaut est 8.

Si vous spécifiez zéro (0), les fichiers journaux sont conservés indéfiniment, mais ils sont soumis à vos paramètres de rotation des fichiers, même si aucun des fichiers n'est supprimé ni renommé. Par conséquent, pour éviter de futures erreurs survenant sur le disque, définissez cette valeur sur une valeur supérieure à zéro ou mettez en œuvre un système standard et automatisé de suppression ou d'archivage des anciens fichiers journaux conservés.

BufferMessage

Si le streaming HTTP est activé pour votre proxy, les messages de requête/réponse ne sont pas mis en mémoire tampon. Si vous souhaitez consigner le contenu nécessitant l'analyse du message de flux, définissez BufferMessage sur "true". Consultez l'exemple d'onglet "Diffusion en streaming" pour voir un exemple. Valeur par défaut : false

Syslog

Destination syslog. Pour envoyer syslog vers Splunk, Sumo Logic ou Loggly, consultez la page Configurer des services de gestion des journaux tiers.

Message

Créez le message à envoyer à syslog, en combinant le texte avec des variables pour capturer les informations souhaitées. Consultez les exemples.

Remarque : Les variables de réponse ne seront pas disponibles dans PostClientFlow après un flux d'erreur. Utilisez les variables de message pour consigner les informations de réponse aux situations d'erreur et de réussite. Consultez également les remarques sur l'utilisation.

Host Nom d'hôte ou adresse IP du serveur où le syslog doit être envoyé. Si vous n'incluez pas cet élément, la valeur par défaut est "localhost".
Port Port sur lequel syslog est exécuté. Si vous n'incluez pas cet élément, la valeur par défaut est 514.
Protocol TCP ou UDP (valeur par défaut). Bien que le protocole UDP soit plus performant, le protocole TCP garantit la distribution des journaux de messagerie au serveur syslog. Pour l'envoi de messages syslog via TLS/SSL, seul TCP est accepté.
FormatMessage

true ou false (valeur par défaut)

Facultative, mais <FormatMessage>true</FormatMessage> est requis pour une utilisation avec Loggly.

Cet élément vous permet de contrôler le format du contenu généré par Apigee ajouté au message. Si cette valeur est définie sur "true", le message syslog est précédé d'un nombre fixe de caractères, ce qui vous permet de filtrer ces informations dans les messages. Voici un exemple pour le format fixe :

<14>1 2023-03-20T09:24:39.039+0000 e49cd3a9-4cf6-48a7-abb9-7ftfe4d97d00 Apigee-Edge - - - Message starts here

Les informations générées par Apigee incluent :

  • <14> - Un niveau de priorité (voir le protocole Syslog) basé sur le niveau de journalisation et le niveau d'installation du message.
  • 1 - Version syslog actuelle.
  • Date avec un décalage UTC (UTC = +0000).
  • UUID du processeur de messages.
  • "Apigee-Edge - - - "

Si cette valeur est définie sur "false" (valeur par défaut), le message n'est pas précédé de ces caractères fixes.

PayloadOnly

true ou false (valeur par défaut)

Cet élément définit le format des messages générés par Apigee de sorte qu'il ne contienne que le corps du message syslog, sans les caractères présentés spécifiés par FormatMessage.

Si vous n'incluez pas cet élément ou le laissez vide, la valeur par défaut est false.

Voir FormatMessage.

DateFormat

Facultatif.

Chaîne de modèle de mise en forme à utiliser pour formater l'horodatage de chaque message de journal. Par défaut, Apigee utilise yyyy-MM-dd'T'HH:mm:ss.SSSZ. Le comportement de ce modèle est décrit dans la documentation de la classe SimpleDateFormat de Java.

SSLInfo

Vous permet de consigner les messages via SSL/TLS. Utilisez cette valeur avec le sous-élément <Enabled>true</Enabled>.

Si vous n'incluez pas cet élément ou le laissez pas vide, la valeur par défaut est "false" (sans TLS/SSL).

<SSLInfo>
    <Enabled>true</Enabled>
</SSLInfo>

Vous pouvez configurer le tag <SSLInfo> comme vous le feriez pour un TargetEndpoint, y compris l'activation de TLS/SSL bidirectionnelle, comme décrit dans la documentation de référence sur la configuration du proxy d'API. Seul le protocole TCP est compatible.

logLevel

Facultatif.

Valeurs valides : INFO (valeur par défaut), ALERT, WARN, ERROR

Définissez un niveau spécifique d'informations à inclure dans le journal des messages.

Si vous utilisez l'élément FormatMessage (défini sur "true"), le paramètre logLevel affecte le score de priorité calculé (le nombre entre crochets) dans les informations générées par Apigee ajoutées au message.

Schémas


Remarques sur l'utilisation

Lorsque vous associez une règle MessageLogging à un flux de proxy d'API, pensez à la placer dans la réponse ProxyEndpoint, dans un flux spécial appelé PostClientFlow. PostClientFlow s'exécute après que la réponse a été envoyée au client demandeur, ce qui garantit que toutes les métriques sont disponibles pour la journalisation. Pour plus de détails sur l'utilisation de PostClientFlow, consultez la documentation de référence sur la configuration du proxy d'API.

PostClientFlow est spécial de deux manières :

  1. Il ne s'exécute que dans le cadre du flux de réponse.
  2. Il s'agit du seul flux exécuté une fois que le proxy passe à l'état d'erreur.

Comme il est exécuté, que le proxy ait réussi ou échoué, vous pouvez placer les règles MessageLogging dans PostClientFlow et être sûr qu'elles s'exécutent toujours.

L'image Trace suivante montre une règle MessageLogging exécutée dans le cadre du flux PostClientFlow, après l'exécution de la règle DefaultFaultRule :

Dans cet exemple, la règle "Valider la clé API" a causé l'erreur en raison d'une clé non valide.

Ci-dessous figure la définition ProxyEndpoint qui inclut le flux PostPostFlow :

<ProxyEndpoint name="default">
  ...
  <PostClientFlow>
    <Response>
      <Step>
        <Name>Message-Logging-1</Name>
      </Step>
    </Response>
  </PostClientFlow>
  ...
</ProxyEndpoint>

Edge consigne les messages sous forme de texte simple et vous pouvez configurer la journalisation pour inclure des variables, telles que la date et l'heure de réception de la requête ou de la réponse, l'identité de l'utilisateur sur la requête, l'adresse IP source à partir de laquelle la requête a été envoyée, etc. Edge consigne les messages de manière asynchrone, ce qui signifie qu'aucune latence susceptible d'être causée par le blocage d'appels n'est introduite dans votre API.

La règle MessageLogging écrit les messages enregistrés en mémoire dans un tampon. L'enregistreur de message lit les messages du tampon, puis écrit dans la destination que vous configurez. Chaque destination dispose de son propre tampon.

Si le taux d'écriture dans le tampon dépasse le taux de lecture, le tampon est débordé et la journalisation échoue. Dans ce cas, le fichier journal peut contenir le message suivant :

Log message size exceeded. Increase the max message size setting

Si vous rencontrez ce problème dans Edge for Private Cloud 4.15.07 et versions antérieures, localisez le fichier message-logging.properties et utilisez cette solution:

Augmentez la propriété max.log.message.size.in.kb (valeur par défaut = 128 Ko) dans le fichier message-logging.properties.

Pour Edge for Private Cloud 4.16.01 et versions ultérieures, définissez la propriété conf_message-logging_max.log.message.size.in.kb dans le fichier /opt/apigee/customer/application/message-processor.properties et redémarrez le processeur de messages.

Remarque:Les variables de message de réponse dans Edge ne sont pas disponibles à partir du flux d'erreur. Ces variables ne sont également pas disponibles dans PostClientFlow si le flux précédent était le flux d'erreur. Si vous souhaitez journaliser les informations de réponse à partir de PostClientFlow, utilisez l'objet message. Vous pouvez utiliser cet objet pour obtenir des en-têtes et d'autres informations de la réponse, qu'il s'agisse ou non d'une erreur. Pour en savoir plus et obtenir un exemple, consultez la section Variables de message.

Contrôler l'horodatage des messages de journal dans Edge for Private Cloud

Par défaut, l'horodatage de tous les messages de journal se présente au format suivant:

yyyy-MM-dd'T'HH:mm:ss.SSSZ

Cette valeur par défaut à l'échelle du système peut être remplacée pour les destinations syslog à l'aide de l'élément DateFormat. Le comportement de ce modèle est décrit dans la documentation de la classe SimpleDateFormat de Java. Selon cette définition, yyyy sera remplacé par une année à quatre chiffres, MM par un numéro de mois à deux chiffres, et ainsi de suite. Le format ci-dessus peut générer une chaîne au format suivant:

2022-09-28T22:38:11.721+0000

Vous pouvez utiliser la propriété conf_system_apigee.syslogger.dateFormat sur le processeur de messages Edge pour contrôler ce format. Par exemple, vous pouvez remplacer le format du message par:

yy/MM/dd'T'HH:mm:ss.SSSZ

..en remplaçant les tirets par des barres obliques et en le raccourcissant en une année à deux chiffres, l'horodatage est enregistré sous la forme suivante:

22/09/28T22:38:11.721+0000

Pour modifier le format:

  1. Ouvrez le fichier message-processor.properties dans un éditeur. Si le fichier n'existe pas, créez-le:
    > vi /opt/apigee/customer/application/message-processor.properties
  2. Définissez les propriétés comme vous le souhaitez:
    conf_system_apigee.syslogger.dateFormat=yy/MM/dd'T'HH:mm:ss.SSSZ
  3. Enregistrez les modifications.
  4. Assurez-vous que le fichier de propriétés appartient à l'utilisateur "apigee" :
    > chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
  5. Redémarrez le processeur Edge Message:
    > /opt/apigee/apigee-service/bin/apigee-serviceedge-message-processor restart

Emplacement du fichier journal dans Edge pour Private Cloud

Edge pour Private Cloud 4.16.01 et versions ultérieures

Par défaut, les journaux de messages de Private Cloud se trouvent dans le répertoire suivant sur les nœuds du processeur de messages:

/opt/apigee/var/log/edge-message-processor/messagelogging/org_name/environment/api_proxy_name/revision/logging_policy_name/

Vous pouvez changer l'emplacement du journal par défaut en modifiant les propriétés du fichier message-logging.properties sur les processeurs de messages:

  • bin_setenv_data_dir : définit le chemin d'accès racine au stockage des fichiers journaux. Par exemple, bin_setenv_data_dir=/opt/apigee/var/log.
  • conf_message-logging_log.root.dir : si vous le définissez sur un chemin d'accès relatif, tel que conf/message-logging.properties+log.root.dir=custom/folder/, the path is appended to the bin_setenv_data_dir location.

    Si vous le définissez sur un chemin absolu, tel que conf/message-logging.properties+log.root.dir=/opt/apigee/var/log/messages, les journaux des messages seront stockés dans /opt/apigee/var/log/messages/messagelog/. Un chemin d'accès absolu est prioritaire sur bin_setenv_data_dir.

    Notez que vous devez référencer la propriété sous conf/message-logging.properties+log.root.dir, car elle est mise en commentaire par défaut. Pour en savoir plus, consultez la section Définir un jeton actuellement commenté.

Si vous souhaitez stocker les fichiers journaux dans une structure de fichiers plat afin que tous les fichiers journaux soient placés dans le même répertoire, définissez conf/message-logging.properties+enable.flat.directory.structure sur "true" dans le fichier message-logging.properties. Les messages sont stockés dans le répertoire spécifié par les propriétés ci-dessus, et les noms de fichiers prennent la forme {org}_{environment}_{api_proxy_name}_{revision}_{logging_policy_name}_{filename}.

Pour définir ces propriétés:

  1. Ouvrez le fichier message-processor.properties dans un éditeur. Si le fichier n'existe pas, créez-le:
    > vi /opt/apigee/customer/application/message-processor.properties
  2. Définissez les propriétés comme vous le souhaitez:
    conf/message-logging.properties+log.root.dir=/opt/apigee/var/log/messages
  3. Enregistrez les modifications.
  4. Assurez-vous que le fichier de propriétés appartient à l'utilisateur "apigee" :
    > chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
  5. Redémarrez le composant Edge:
    > /opt/apigee/apigee-service/bin/apigee-service Edge-message-processor restart

Edge pour Private Cloud 4.15.07 et versions antérieures

Par défaut, les journaux des messages sont stockés à l'emplacement suivant sur les processeurs de messages:

/opt/apigee4/var/log/apigee/message-processor/messagelog/{org}/{environment}/{api_proxy_name}/{revision}/{logging_policy_name}/

Vous pouvez changer l'emplacement du journal par défaut en modifiant les propriétés suivantes dans le fichier message-logging.properties sur les processeurs de messages:

  • data.dir : définit le chemin d'accès racine au stockage des fichiers journaux. Par exemple, data.dir=/opt/apigee4/var/log
  • log.root.dir : si vous le définissez sur un chemin d'accès relatif, tel que log.root.dir=custom/folder/, le chemin est ajouté à l'emplacement data.dir.

Par exemple, la combinaison des deux propriétés définirait le répertoire de journalisation dans /opt/apigee4/var/log/custom/folder/messagelog/ (notez que /messagelog est ajouté automatiquement).

Si vous le définissez sur un chemin absolu, tel que log.root.dir=/opt/apigee4/var/log/messages, les journaux de messages seront stockés dans /opt/apigee4/var/log/messages/messagelog/. Un chemin d'accès absolu dans log.root.dir est prioritaire sur data.dir.

Si vous souhaitez stocker les fichiers journaux dans une structure de fichiers journaux de sorte que tous les fichiers journaux soient placés dans le même répertoire, définissez la propriétéenable.flat.directory.structure sur "true" dans le fichier message-logging.properties sur les processeurs de messages. Les messages sont stockés dans le répertoire spécifié par les propriétés ci-dessus, et les noms de fichiers prennent la forme {org}_{environment}_{api_proxy_name}_{revision}_{logging_policy_name}_{filename}.

Valeurs par défaut des variables dans le modèle de message

Vous pouvez spécifier des valeurs par défaut séparément pour chaque variable dans le modèle de message. Par exemple, si la variable request.header.id ne peut pas être résolue, sa valeur est remplacée par la valeur unknown.

<Message>This is a test message. id = {request.header.id:unknown}</Message>

Une valeur par défaut commune peut être spécifiée pour toutes les variables non résolues en définissant l'attribut defaultVariableValue dans l'élément Message :

<Message defaultVariableValue="unknown">This is a test message. id = {request.header.id}</Message>

Configurer des services de gestion de journaux tiers

La règle MessageLogging vous permet d'envoyer des messages syslog à des services de gestion de journaux tiers, tels que Splunk, Sumo Logic et Loggly. Si vous souhaitez envoyer syslog à l'un de ces services, consultez la documentation de ce service pour configurer l'hôte, le port et le protocole du service, puis définissez l'élément Syslog sur cette règle en conséquence.

Consultez la documentation suivante concernant la configuration de la gestion des journaux tiers :

Informations de référence sur les erreurs

Cette section décrit les codes d'erreur et les messages d'erreur renvoyés, ainsi que les variables d'erreur définies par Edge lorsque cette stratégie déclenche une erreur. Ces informations sont importantes si vous développez des règles de défaillance afin de gérer les pannes. Pour en savoir plus, consultez les pages Ce que vous devez savoir à propos des erreurs liées aux règles et Gérer les pannes.

Erreurs d'exécution

Ces erreurs peuvent se produire lors de l'exécution de la règle.

Code d'erreur État HTTP Cause
steps.messagelogging.StepDefinitionExecutionFailed 500 Voir la chaîne d'erreur.

Erreurs de déploiement

Ces erreurs peuvent se produire lorsque vous déployez un proxy contenant cette règle.

Nom de l'erreur Cause Solution
InvalidProtocol Le déploiement de la règle MessageLogging peut échouer et renvoyer cette erreur si le protocole spécifié dans l'élément <Protocol> n'est pas valide. Les protocoles valides sont TCP et UDP. Pour l'envoi de messages syslog via TLS/SSL, seul TCP est accepté.
InvalidPort Le déploiement de la règle MessageLogging peut échouer et renvoyer cette erreur si le numéro de port n'est pas spécifié dans l'élément <Port> ou s'il n'est pas valide. Le numéro de port doit être un entier supérieur à zéro.

Variables de panne

Ces variables sont définies lorsqu'une erreur d'exécution se produit. Pour en savoir plus, consultez la section Ce que vous devez savoir sur les erreurs liées aux règles.

Variables Où : Exemple
fault.name="fault_name" fault_name est le nom de l'erreur, tel qu'indiqué dans le tableau Erreurs d'exécution ci-dessus. Le nom d'erreur est la dernière partie du code d'erreur. fault.name Matches "StepDefinitionExecutionFailed"
messagelogging.policy_name.failed policy_name est le nom spécifié par l'utilisateur de la règle qui a provoqué l'erreur. messagelogging.ML-LogMessages.failed = true

Exemple de réponse d'erreur

{  
   "fault":{  
      "detail":{  
         "errorcode":"steps.messagelogging.StepDefinitionExecutionFailed"
      },
      "faultstring":"Execution failed"
   }
}

Exemple de règle de défaillance

<FaultRule name="MessageLogging">
    <Step>
        <Name>ML-LogMessages</Name>
        <Condition>(fault.name Matches "StepDefinitionExecutionFailed") </Condition>
    </Step>
    <Condition>(messagelogging.ML-LogMessages.failed = true) </Condition>
</FaultRule>


Variables de flux

Les variables suivantes sont renseignées lors de l'échec de la règle.

  • messagelogging.failed
  • messagelogging.{stepdefinition-name}.failed

Articles associés