Règle de journalisation des messages

Vous consultez la documentation Apigee Edge.
Accédez à la documentation Apigee X.

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 enregistrer les messages personnalisés sur un disque local (Edge pour Private Cloud uniquement) ou dans 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.

<FileName>/opt/apigee/var/log/messages/mylog.log</FileName>

<FileName>mylog.log</FileName>

<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 enregistre les messages sous forme de texte simple. 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 une requête a été envoyée, etc. Edge enregistre les messages de manière asynchrone, ce qui signifie qu'aucune latence susceptible d'être causée par le blocage des appels n'est introduite dans l'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.

Les utilisateurs peuvent constater des retards dans la réception des messages de journaux envoyés à un nouveau point de terminaison syslog. Cela est dû à un comportement de "démarrage à froid" intentionnel dans la règle. Lorsqu'une nouvelle destination de journalisation est configurée, en plus des destinations de journalisation existantes, le processeur de messages (MP) peut d'abord mettre en file d'attente 1 000 messages de journal en mémoire avant de les envoyer. Cela peut entraîner un délai initial dans les environnements à faible trafic. Ce délai initial n'est pas observable pour les charges de travail de production typiques, car les messages devraient s'accumuler rapidement. Une fois le seuil atteint, les messages de journalisation seront distribués comme prévu. Le redémarrage en douceur du processeur de messages peut également déclencher la distribution des messages en file d'attente à mesure qu'ils sont supprimés de la file d'attente.

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 pour le cloud privé 4.15.07 ou version antérieure, 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 pour le cloud privé 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. Notez que cette propriété est initialement commentée par défaut.

Remarque : Les variables de message de réponse dans Edge ne sont pas disponibles dans le flux d'erreurs. 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 code temporel des messages de journaux dans Edge pour Private Cloud

Par défaut, le code temporel de tous les messages du 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 ignorée pour les destinations syslog à l'aide de l'élément DateFormat. Le comportement de ce modèle est décrit dans la documentation relative à 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 de ce type :

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, en modifiant le format du message comme suit :

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

..replacing the dashes with slashes, and shortening to a 2-digit year, records a timestamp in the form:

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 de messages Edge :
   > /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

Emplacement des fichiers journaux dans Edge pour le cloud privé

Edge pour le cloud privé 4.16.01 et versions ultérieures

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

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

Vous pouvez modifier 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 pour le stockage des fichiers journaux. Par exemple, bin_setenv_data_dir=/opt/apigee/var/log.
• conf_message-logging_log.root.dir : si vous définissez ce paramètre sur un chemin 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 définissez ce paramètre sur un chemin absolu, tel que conf/message-logging.properties+log.root.dir=/opt/apigee/var/log/messages, les journaux de messages seront stockés dans /opt/apigee/var/log/messages/messagelog/. Un chemin absolu est prioritaire sur bin_setenv_data_dir.
  
  Notez que vous devez faire référence à la propriété en tant que conf/message-logging.properties+log.root.dir, car elle est commentée par défaut. Pour en savoir plus, consultez Définir un jeton actuellement mis en commentaire.

Si vous souhaitez stocker les fichiers journaux dans une structure de fichier à 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 se présentent sous 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 le cloud privé 4.15.07 et versions antérieures

Par défaut, les journaux de messages se trouvent à 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 modifier 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 pour le stockage des fichiers journaux. Par exemple, data.dir=/opt/apigee4/var/log
• log.root.dir : si vous définissez ce paramètre sur un chemin d'accès relatif, tel que log.root.dir=custom/folder/, le chemin d'accès est ajouté à l'emplacement data.dir.

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

Si vous définissez un chemin d'accès 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 fichier plat afin 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 des processeurs de messages. Les messages sont stockés dans le répertoire spécifié par les propriétés ci-dessus. Les noms de fichiers 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 cet article de la communauté Apigee : Journaliser les messages dans Splunk
• Sumo Logic
  • Consultez également ce post destiné à la communauté Apigee : Configurer la journalisation avec Sumo Logic : quel hôte dois-je utiliser ?
  • Pour obtenir un exemple complet d'utilisation de Sumo Logic comme service de journalisation, consultez le post destiné à la communauté ci-dessous. La solution se sert d'une seule règle JavaScript pour envoyer des requêtes HTTP POST au collecteur HTTP source Sumo Logic : Journaliser dans Sumo Logic à l'aide de JavaScript et HTTP.
• 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 cet article de la communauté Apigee pour en savoir plus sur la journalisation des messages dans Loggly : Journaliser des messages dans Loggly

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 : Documentation de référence sur les variables