Règle de journalisation des messages

<ph type="x-smartling-placeholder"></ph> Vous consultez la documentation Apigee Edge.
Accédez à la page Documentation sur 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 dans un sur un disque local (Edge pour le cloud privé uniquement) ou vers syslog.

Exemples

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

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

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

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

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

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

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

Utilisez les éléments suivants pour configurer le type de règle MessageLogging.

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

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 de vérification de 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. Message de journaux Edge de manière asynchrone, ce qui signifie qu'aucune latence pouvant être causée par le blocage des appels n'est introduite. à 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 message-logging.properties et utilisez la solution suivante:

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.properties+max. log.message.size.in.kb dans le fichier /opt/apigee/customer/application/message-processor.properties et redémarrez le processeur de messages. Veuillez noter que cette propriété est initialement commentée par défaut.

Remarque:Le 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 le message de journal code temporel dans Edge pour Private Cloud

Par défaut, le code temporel de tous les messages de journal est 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 la Élément DateFormat. Le comportement de ce modèle est décrit dans la de la classe SimpleDateFormat de Java. Selon cette définition, yyyy sera remplacé. par une année à quatre chiffres, MM est remplacé par un numéro de mois à deux chiffres, et ainsi de suite. Le format ci-dessus peut donner le résultat suivant:

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

Vous pouvez utiliser conf_system_apigee.syslogger.dateFormat sur le processeur de messages Edge pour contrôler ce format. Par exemple, modifier le message au format suivant:

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

..le remplacement des tirets par des barres obliques et l'abréviation d'une année à deux chiffres permet d'enregistrer un code temporel au format suivant:

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

Pour modifier le format:

1. Ouvrez le fichier message-processor.properties dans une éditeur. Si le fichier n'existe pas, créez-le:
   &gt; 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&#39;T&#39;HH:mm:ss.SSSZ
3. Enregistrez les modifications.
4. Assurez-vous que le fichier de propriétés appartient à "apigee" utilisateur:
   &gt; chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
5. Redémarrez le processeur de messages Edge:
   &gt; /opt/apigee/apigee-service/bin/apigee-service Edge-message-processor redémarrage

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 des messages Private Cloud se trouvent dans le répertoire suivant sur Message Nœuds de processeur:

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

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

• bin_setenv_data_dir : Définit le chemin d'accès racine pour le stockage des fichiers journaux. Par exemple, bin_setenv_data_dir=/opt/apigee/var/log.
• conf_message-logging_log.root.dir : si définissez-le 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 d'accès absolu, comme conf/message-logging.properties+log.root.dir=/opt/apigee/var/log/messages, message seront stockés dans /opt/apigee/var/log/messages/messagelog/. Un chemin 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 il est commenté par défaut. Reportez-vous à la section Définition d'une qui est actuellement commenté.

Si vous souhaitez stocker les fichiers journaux dans une structure de fichiers plats afin que tous les fichiers journaux soient placés dans même répertoire, définissez conf/message-logging.properties+enable.flat.directory.structure sur 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 se présentent sous la forme suivante : {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 une éditeur. Si le fichier n'existe pas, créez-le:
   &gt; 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 à "apigee" utilisateur:
   &gt; chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
5. Redémarrez le composant Edge:
   &gt; /opt/apigee/apigee-service/bin/apigee-service Edge-message-processor redémarrage

Edge pour Private Cloud 4.15.07 et versions antérieures

Par défaut, les journaux des messages sont situés à l'emplacement suivant sur le message processeurs:

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

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

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

Par exemple, la combinaison des deux propriétés définirait le répertoire de journalisation à /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 message seront stockés dans /opt/apigee4/var/log/messages/messagelog/. Un chemin absolu dans log.root.dir est prioritaire sur data.dir.

Si vous souhaitez stocker les fichiers journaux dans une structure de fichiers plats afin que tous les fichiers journaux soient placés dans même répertoire, définissez la propriétéenable.flat.directory.structure sur dans le fichier message-logging.properties sur les objets Processeurs. Les messages sont stockés dans le répertoire spécifié par les propriétés ci-dessus, et le fichier se présentent sous 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 :

• Splunk (sélectionnez la version du produit)
  Consultez également ce post destiné à la communauté Apigee : https://community.apigee.com/content/kbentry/13298/log-messages -into-splunk.html
• Sumo Logic
  • Consultez également ce post destiné à la communauté Apigee : https://community.apigee.com/questions/5226/setting-up-logging-with-sumo-logic-which-host-shou.html.
  • Pour obtenir un exemple complet d'utilisation de Sumo Logic comme service de journalisation, consultez le post destiné à la communauté ci-dessous. La solution utilise une seule règle JavaScript pour envoyer des requêtes HTTP POST au collecteur source de Sumo Logic : https://community.apigee.com/articles/32286/logging-to-sumo-logic-using-javascript-and-http.html
• Loggly
  Lorsque vous utilisez Loggly, <FormatMessage>true</FormatMessage> est requis dans la règle en tant qu'enfant de l'élément <Syslog>.
  Consultez également ce post destiné à la communauté Apigee pour en savoir plus sur la journalisation des messages dans Loggly : https://community.apigee.com/content/kbentry/14798/log-messages-into- loggly.html

Informations de référence sur les erreurs

Cette section décrit les codes d'erreur et les messages d'erreur qui sont 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.

Erreurs de déploiement

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

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.

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

• Variables exposées par Edge: Référence des variables