Antimodèle : Appeler la règle MessageLogging plusieurs fois dans un proxy d'API

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

La règle MessageLogging d'Apigee Edge permet aux développeurs de proxy d'API de consigner des messages personnalisés dans syslog ou sur disque (Edge pour Private Cloud uniquement). Toute information importante concernant la requête API, par exemple les paramètres d'entrée, la charge utile de requête, le code de réponse ou encore les messages d'erreur (le cas échéant), peut être consignée pour référence ultérieure ou à des fins de débogage. Bien que la règle utilise un processus en arrière-plan pour effectuer la journalisation, il existe des mises en garde.

Antimodèle

La règle MessageLogging constitue un moyen efficace d'obtenir plus d'informations sur une requête API et de résoudre les problèmes rencontrés avec cette requête. Toutefois, le fait d'utiliser la même règle MessageLogging plusieurs fois ou que plusieurs règles MessageLogging consignent des données dans des fragments du même proxy d'API dans des flux autres que le PostClientFlow peut avoir des conséquences négatives. En effet, Apigee Edge ouvre une connexion à un serveur syslog externe pour une stratégie MessageLogging. Si la règle utilise TLS sur TCP, l'établissement d'une connexion TLS entraîne une surcharge supplémentaire.

Examinons cela à l'aide d'un exemple de proxy d'API.

Proxy d'API

Dans l'exemple suivant, une règle MessageLogging nommée "LogRequestInfo" est placée dans le flux de requêtes, et une autre règle MessageLogging nommée "LogResponseInfo" est ajoutée au flux de réponses. Elles se trouvent toutes deux dans le PreFlow du ProxyEndpoint. La règle LogRequestInfo s'exécute en arrière-plan dès que le proxy d'API reçoit la requête, et la règle LogResponseInfo s'exécute après que le proxy a reçu une réponse du serveur cible, mais avant que le proxy renvoie la réponse au client d'API. Cela consomme des ressources système supplémentaires, car deux connexions TLS sont potentiellement établies.

En outre, il existe une règle MessageLogging nommée "LogErrorInfo" qui ne s'exécute que si une erreur se produit lors de l'exécution du proxy d'API.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ProxyEndpoint name="default">
  ...
<FaultRules>
    <FaultRule name="fault-logging">
        <Step>
            <Name>LogErrorInfo</Name>
        </Step>
    </FaultRule>
</FaultRules>
<PreFlow name="PreFlow">
    <Request>
      <Step>
        <Name>LogRequestInfo</Name>
      </Step>
    </Request>
  </PreFlow>
  <PreFlow name="PreFlow">
    <Response>
      <Step>
        <Name>LogResponseInfo</Name>
      </Step>
    </Response>
  </PreFlow>
  ...
</ProxyEndpoint>

Règle de journalisation des messages

Dans les exemples de configurations de règle suivants, les données sont consignées dans des serveurs de journalisation tiers via TLS sur TCP. Si plusieurs de ces règles sont utilisées dans le même proxy d'API, la surcharge liée à l'établissement et à la gestion des connexions TLS occupera des cycles de mémoire et de processeur supplémentaires, ce qui peut entraîner des problèmes de performances à grande échelle.

Règle LogRequestInfo

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MessageLogging name="LogRequestInfo">
  <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>INFO</logLevel>
</MessageLogging>

Règle LogResponseInfo

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MessageLogging name="LogResponseInfo">
  <Syslog>
    <Message>[3f509b58 tag="{organization.name}.{apiproxy.name}.{environment.name}"] Status: {response.status.code}, Response {response.content}.</Message>
    <Host>logs-01.loggly.com</Host>
    <Port>6514</Port>
    <Protocol>TCP</Protocol>
    <FormatMessage>true</FormatMessage>
    <SSLInfo>
        <Enabled>true</Enabled>
    </SSLInfo>
  </Syslog>
  <logLevel>INFO</logLevel>
</MessageLogging>

Règle LogErrorInfo

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MessageLogging name="LogErrorInfo">
  <Syslog>
    <Message>[3f509b58 tag="{organization.name}.{apiproxy.name}.{environment.name}"] Fault name: {fault.name}.</Message>
    <Host>logs-01.loggly.com</Host>
    <Port>6514</Port>
    <Protocol>TCP</Protocol>
    <FormatMessage>true</FormatMessage>
    <SSLInfo>
        <Enabled>true</Enabled>
    </SSLInfo>
  </Syslog>
  <logLevel>ERROR</logLevel>
</MessageLogging>

Impact

  • Augmentation de la surcharge réseau en raison de l'établissement de connexions aux serveurs de journalisation plusieurs fois lors du flux du proxy d'API.
  • Si le serveur syslog est lent ou ne peut pas gérer le volume important dû à plusieurs appels syslog, cela entraîne une contre-pression sur le processeur de messages, ce qui peut ralentir le traitement des requêtes et potentiellement accroître la latence ou les erreurs "504 Expiration du délai de la passerelle".
  • Augmentation du nombre de descripteurs de fichier ouverts simultanément par le processeur de messages dans les configurations de cloud privé où la journalisation de fichiers est utilisée.

  • Si la règle MessageLogging est placée dans des flux autres que le PostClientFlow, il est possible que ces informations ne soient pas consignées, car la règle MessageLogging ne sera pas exécutée en cas d'échec avant l'exécution de cette règle.

    Dans l'exemple de ProxyEndpoint précédent, les informations ne seront pas consignées dans les circonstances suivantes :

    • Si l'une des règles placées avant la règle LogRequestInfo dans le flux de requêtes échoue.
      ou
    • Si le serveur cible échoue et affiche une erreur (HTTP 4XX, 5XX). Dans ce cas, lorsqu'une réponse positive n'est pas renvoyée, la règle LogResponseInfo n'est pas exécutée.

    Dans les deux cas, la règle LogErrorInfo est exécutée et consigne uniquement les informations sur les erreurs.

Bonne pratique

  • Utilisez une règle ExtractVariables ou une règle JavaScript pour définir toutes les variables de flux à consigner, afin qu'elles soient disponibles pour la règle MessageLogging.
  • Utilisez une seule règle MessageLogging pour consigner toutes les données requises dans le PostClientFlow, qui est exécutée sans condition.
  • Utilisez le protocole UDP, où la diffusion garantie des messages au serveur syslog n'est pas obligatoire et TLS/SSL n'est pas obligatoire.

La règle MessageLogging a été conçue pour être dissociée des fonctionnalités d'API réelles, y compris de la gestion des erreurs. Par conséquent, si vous l'appelez dans le PostClientFlow, qui est en dehors du traitement des requêtes/réponses, cela signifie qu'elle consigne toujours les données, que l'API ait échoué ou non.

Voici un exemple d'appel de la règle MessageLogging dans le PostClientFlow :

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 ...
<PostClientFlow>
        <Request/>
        <Response>
            <Step>
                <Name>LogInfo</Name>
            </Step>
        </Response>
</PostClientFlow>
 ...

Voici un exemple de règle MessageLogging, LogInfo, qui consigne toutes les données :

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MessageLogging name="LogInfo">
  <Syslog>
    <Message>[3f509b58 tag="{organization.name}.{apiproxy.name}.{environment.name}"] Weather request for WOEID {woeid} Status: {weather.response.code}, Response {weather.response}, Fault: {fault.name:None}.</Message>
    <Host>logs-01.loggly.com</Host>
    <Port>6514</Port>
    <Protocol>TCP</Protocol>
    <FormatMessage>true</FormatMessage>
    <SSLInfo>
        <Enabled>true</Enabled>
    </SSLInfo>
  </Syslog>
  <logLevel>INFO</logLevel>
</MessageLogging>

Étant donné que les variables de réponse ne sont pas disponibles dans le PostClientFlow après un flux d'erreurs, il est important de définir explicitement les variables woeid et weather.response* à l'aide de variables ExtractVariables ou JavaScript.

Documentation complémentaire