Vous consultez la documentation Apigee Edge.
Accéder à la documentation sur Apigee X en savoir plus
![](https://docs.apigee.com/static/api-platform/images/icon_policy_message-logging.jpg?authuser=6&hl=fr)
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
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. Une fois configuré pour syslog, un proxy d'API transmet 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 règle MessageLogging.
Nom du champ | Description du champ | |
---|---|---|
Destination des fichiers locaux. (La journalisation des fichiers n'est compatible qu'avec Edge pour les déploiements de cloud privé.) Pour plus d'informations sur l'emplacement de stockage des fichiers, consultez la section Emplacement du fichier journal dans Edge pour Private Cloud. |
Message |
Créez le message à envoyer dans le fichier journal, en combinant du texte et 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: Si cette règle est définie sur "true", le fichier journal est alterné à chaque redémarrage du moteur de messagerie. |
|
FileRotationType |
Spécifie la règle de rotation (size ou time ) d'un fichier journal. |
|
MaxFileSizeInMB |
(Lors de la sélection de 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. Une fois que le fichier journal a atteint la taille spécifiée, le serveur renomme le fichier journal actuel. |
|
RotationFrequency |
(Lors de la sélection de time comme type de rotation) Spécifie la durée, en minutes, à partir de laquelle le serveur déplace les 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 soumis aux paramètres de rotation de vos fichiers, bien qu'aucun d'eux ne soit supprimé ni renommé. Par conséquent, pour éviter de futures erreurs d'espace disque saturé, définissez cette valeur sur une valeur supérieure à zéro ou implémentez un système standard et automatisé de suppression définitive 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 activée" pour voir un exemple. Valeur par défaut : false |
|
Une destination syslog. Pour envoyer un journal syslog vers Splunk, Sumo Logic ou Loggly, consultez la section 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 |
Facultative, mais 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 :
Les informations générées par Apigee incluent :
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 |
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 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 |
|
SSLInfo |
Vous permet de consigner les messages via SSL/TLS. Utilisez cette valeur avec le sous-élément 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 : Définissez un niveau spécifique d'informations à inclure dans le journal des messages. Si vous utilisez l'élément |
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 :
- Il ne s'exécute que dans le cadre du flux de réponse.
- 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 Vérifier la clé API est à l'origine de 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 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 des 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.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: 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 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 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 donner le résultat suivant:
2022-09-28T22:38:11.721+0000
Vous pouvez utiliser la propriété conf_system_apigee.syslogger.dateFormat sur le processeur de message périphérique pour contrôler ce format. Par exemple, vous pouvez remplacer le format du message par:
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:
- 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 - Définissez les propriétés comme vous le souhaitez:
conf_system_apigee.syslogger.dateFormat=yy/MM/dd'T'HH:mm:ss.SSSZ - Enregistrez les modifications.
- Assurez-vous que le fichier de propriétés appartient à l'utilisateur "apigee" :
> chown apigee:apigee /opt/apigee/customer/application/message-processor.properties - Redémarrez le processeur de messages Edge:
> /opt/apigee/apigee-service/bin/apigee-service Edge-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 des messages du cloud privé 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 pour le 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 queconf/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 surbin_setenv_data_dir
.
Notez que vous devez référencer la propriété sous conf/message-logging.properties+log.root.dir, car elle est commentée 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 plats 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:
- 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 - Définissez les propriétés comme vous le souhaitez:
conf/message-logging.properties+log.root.dir=/opt/apigee/var/log/messages - Enregistrez les modifications.
- Assurez-vous que le fichier de propriétés appartient à l'utilisateur "apigee" :
> chown apigee:apigee /opt/apigee/customer/application/message-processor.properties - 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 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 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 pour le 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éfinit le répertoire de journalisation sur /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 des messages 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 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 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 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é. |
build |
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. |
build |
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
- Variables exposées par Edge: Référence des variables