Règle de journalisation des messages

Cette page s'applique à Apigee et à Apigee hybrid.

Consultez la documentation d'Apigee Edge.

icône de la règle

Quoi

La règle MessageLogging vous permet de consigner des messages personnalisés dans Cloud Logging ou syslog. Vous pouvez utiliser les informations contenues dans les journaux pour diverses tâches, telles que le suivi des problèmes dans l'environnement d'exécution de l'API.

Cette règle est une règle extensible et son utilisation peut avoir des conséquences sur le coût ou l'utilisation, en fonction de votre licence Apigee. Pour en savoir plus sur les types de règles et les implications en termes d'utilisation, consultez la section Types de règles.

Il existe deux manières d'utiliser la règle MessageLogging :

  • L'élément <CloudLogging> consigne les messages dans Cloud Logging. Pour utiliser cette méthode, vous devez activer les API Cloud Logging pour votre projet Google Cloud. Pour en savoir plus sur l'activation des API pour un projet Google Cloud, consultez la page Activer et désactiver des services.
  • L'élément <Syslog> consigne les messages dans syslog, un protocole standard permettant d'envoyer des messages de journaux système ou d'événement à un serveur spécifique. Pour utiliser cette méthode, vous devez disposer d'un serveur syslog disponible. Si ce n'est pas le cas, vous pouvez utiliser des services de gestion de journaux publics, tels que Splunk, Sumo Logic et Loggly. Consultez la section Configurer des services de gestion de journaux tiers.

Remarque : Vous ne pouvez pas utiliser les éléments <CloudLogging> et <Syslog> dans la même règle.

Élément <MessageLogging>

Définit une règle <MessageLogging>.

Valeur par défaut Consultez l'onglet Règles par défaut ci-dessous.
Obligatoire ? Obligatoire
Type TYPE
Élément parent N/A
Éléments enfants <CloudLogging>
<Syslog>
<logLevel>

L'élément <MessageLogging> utilise la syntaxe suivante :

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MessageLogging continueOnError="false" enabled="true" name="Message-Logging-1">
    <DisplayName>Message Logging-1</DisplayName>
    <Syslog>
<!-- Note: You cannot use both the <Syslog> element and the <CloudLogging> element in the same policy. -->
        <Message>Some message for syslog</Message>
        <Host>localhost</Host>
        <Port>514</Port>
    </Syslog>
    <CloudLogging>
<!-- Note: You cannot use both the <CloudLogging> and the <Syslog> element in the same policy. -->
        <LogName>projects/{organization.name}/logs/{log.id}</LogName>
        <Message contentType="application/json">{"{message.queryparam.key}": "{message.queryparam.value}"}</Message>
        <Labels>
            <Label>
                <Key>key1</Key>
                <Value>value1</Value>
            </Label>
            <Label>
                <Key>key2</Key>
                <Value>value2</Value>
            </Label>
        </Labels>
        <ResourceType>api</ResourceType>
    </CloudLogging>
    <logLevel>ALERT</logLevel>
</MessageLogging>

Cet élément possède les attributs suivants qui sont communs à toutes les règles :

Attribut Par défaut Obligatoire ? Description
name ND Obligatoire

Nom interne de la règle. La valeur de l'attribut name peut contenir des lettres, des chiffres, des espaces, des tirets, des traits de soulignement et des points. Cette valeur ne peut pas dépasser 255 caractères.

Vous pouvez également utiliser l'élément <DisplayName> pour ajouter un libellé à la règle dans l'éditeur de proxy de l'interface utilisateur de gestion avec un nom différent, en langage naturel.
continueOnError faux Facultatif Définissez sur false pour afficher une erreur en cas d'échec d'une règle. Il s'agit du comportement attendu pour la plupart des règles. Définissez sur true pour que l'exécution du flux se poursuive même après l'échec d'une règle. Voir aussi :
enabled true Facultatif Définissez sur true pour appliquer la règle. Définissez sur false pour désactiver la règle. La règle ne sera pas appliquée même si elle reste associée à un flux.
async   faux Obsolète Cet attribut est obsolète.

Le tableau suivant fournit une description détaillée des éléments enfants de <MessageLogging> :

Nom du champ Description du champ
CloudLogging

Configurer les messages à consigner dans Cloud Logging.
Syslog

Configurer les messages à consigner dans syslog.

Exemples

CloudLogging

<MessageLogging name="LogToCloudLogging">
    <CloudLogging>
        <LogName>projects/{organization.name}/logs/{log.id}</LogName>
        <Message contentType="application/json">{"{message.queryparam.key}": "{message.queryparam.value}"}</Message>
        <Labels>
            <Label>
                <Key>key1</Key>
                <Value>value1</Value>
            </Label>
            <Label>
                <Key>key2</Key>
                <Value>value2</Value>
            </Label>
        </Labels>
        <ResourceType>api</ResourceType>
    </CloudLogging>
</MessageLogging>

Cet exemple montre comment utiliser des modèles de message. L'élément Message contient les variables de flux suivantes :

{"{message.queryparam.key}": "{message.queryparam.value}"}

Ainsi, lorsqu'un utilisateur appelle le proxy avec les valeurs message.queryparam.key = "fruit" et message.queryparam.value = "apple", l'entrée de journal obtenue est {"fruit": "apple"}.

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>yyMMdd-HH:mm:ss.SSS</DateFormat>
  </Syslog>
  <logLevel>ALERT</logLevel>
</MessageLogging>

Dans cet exemple, supposons 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. Le format des codes temporels est semblable à 230704-13:42:17.376, comme dans le format spécifié dans l'élément DateFormat.

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

Référence d'élément enfant

Les sections suivantes décrivent les éléments enfants de <MessageLogging>

<CloudLogging>

Utilisez l'élément <CloudLogging> pour consigner les messages dans Cloud Logging.

Nom du champ Obligatoire ? Description
LogName Oui Nom du journal. Le nom du journal doit être au format projects/{PROJECT_ID}/logs/{LOG_ID}. Vous pouvez utiliser des variables à la place de {PROJECT_ID} et {LOG_ID}.
Message Oui

Message à consigner. Le message possède un attribut contentType, dont la valeur peut être respectivement text/plain ou application/json pour les messages texte et JSON. Consultez les exemples.
Label Non Libellé à associer au message de journal, le cas échéant. Les libellés se présentent sous la forme d'une paire clé/valeur comme suit : 
<Label>
    <Key>key1</Key>
    <Value>value1</Value>
</Label>
ResourceType Non (valeur par défaut, "global") Représente la ressource surveillée qui génère les journaux.

Authentification pour Cloud Logging

Pour utiliser l'élément <CloudLogging>, vous devez déployer votre proxy d'API de façon à utiliser l'authentification Google. Apigee utilise des identifiants correspondant à l'identité du compte de service que vous spécifiez dans les requêtes sortantes vers Cloud Logging. Pour en savoir plus, consultez la section Utiliser l'authentification Google. Le compte de service que vous associez à votre proxy d'API au moment du déploiement doit disposer d'un rôle doté de l'autorisation logging.logEntries.create. Pour en savoir plus sur les rôles Identity and Access Management (IAM) pour <CloudLogging>, consultez le guide du contrôle des accès.

<Syslog>

Utilisez l'élément <Syslog> pour configurer les messages à consigner dans syslog. Lorsque vous utilisez <Syslog>, un proxy d'API transfère les messages de journal d'Apigee vers un serveur syslog distant. Pour utiliser cette méthode, vous devez disposer d'un serveur syslog disponible. Si ce n'est pas le cas, des services de gestion de journaux publics, tels que Splunk, Sumo Logic et Loggly, sont disponibles. Consultez la section Configurer des services de gestion de journaux tiers.

Nom du champ Obligatoire ? Description du champ
Message Oui

Message à consigner. Le message possède un attribut contentType, dont la valeur peut être respectivement text/plain ou application/json pour les messages texte et JSON. Consultez les exemples.
Host Non 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 Non Port sur lequel syslog est exécuté. Si vous n'incluez pas cet élément, la valeur par défaut est 514.
Protocol Non 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 Non, mais <FormatMessage>true</FormatMessage> est requis pour une utilisation avec Loggly.

true ou false (valeur par défaut)

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

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 Non

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 Non

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 relative à la classe SimpleDateFormat de Java. Selon cette définition, yyyy dans la chaîne de format sera remplacé par une année à quatre chiffres, MM par un numéro de mois à deux chiffres, et ainsi de suite.

SSLInfo Non

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>

Les valeurs valides pour l'élément <logLevel> sont : INFO (par défaut), ALERT, WARN et ERROR.

Définit 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.

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

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

Apigee enregistre les messages de manière asynchrone : la réponse est renvoyée alors que les journaux sont toujours en cours d'écriture. Par conséquent, aucune latence n'est introduite dans l'API en bloquant les appels. Il peut arriver qu'un journal ne soit pas écrit sans qu'une erreur ne soit renvoyée, mais ces événements sont rares.

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 l'un des messages suivants :

  • En utilisant <CloudLoggingg> : 
    steps.messagelogging.TooManyPendingLoggingRequest
  • En utilisant <Syslog> : 
    Log message size exceeded. Increase the max message size setting

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

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 : Log messages in Splunk (Journaliser les messages dans Splunk)
  • Sumo Logic
  • 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 renvoyés et les variables d'erreur définies par Apigee lorsque cette règle 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.
steps.messagelogging.InvalidGoogleCloudLogName 500 Cette erreur est générée lorsque LogName ne renvoie pas le format valide de projects/{project}/logs/{logid}.
steps.messagelogging.InvalidJsonMessage 500 Cette erreur est générée lorsque la valeur d'attributs contentType a été choisie en tant que application/json, mais que la valeur réelle du message n'est pas une chaîne JSON valide.
steps.messagelogging.TooManyPendingLoggingRequest 500 Cette erreur est générée lorsque plus de 2 500 requêtes en attente doivent être écrites dans Cloud Logging. Cette limite de 2 500 requêtes s'applique à chaque pod d'exécution Apigee. Par exemple, si le trafic est réparti sur deux instances de pods d'exécution Apigee, la limite effective est de 5 000 requêtes.
-

Erreurs de déploiement

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

Nom de l'erreur Cause Corriger
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 Lieu 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