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

Vous consultez la documentation d'Apigee et d'Apigee hybrid.
Consultez la documentation d'Apigee Edge.

La règle MessageLogging d'Apigee permet aux développeurs de proxys d'API de consigner des messages personnalisés dans Cloud Logging ou dans des points de terminaison syslog. 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 ouvre une connexion à un point de terminaison externe pour chaque règle MessageLogging. Si la règle utilise TLS sur TCP, comme pour les points de terminaison syslog, 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. Des effets négatifs semblables se produisent si vous utilisez MessageLogging pour vous connecter à des points de terminaison Cloud Logging.

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 récurrent de connexions aux points de terminaison de journalisation, 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".
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

Dans le flux de proxy, utilisez une ou plusieurs instances de la règle ExtractVariables ou de la règle JavaScript pour définir toutes les variables de flux à consigner dans une variable de contexte. Elles seront ainsi disponibles pour la règle MessageLogging qui va s'exécuter ultérieurement.
Utilisez une seule règle MessageLogging pour consigner toutes les données requises dans le PostClientFlow, qui est exécutée sans condition.
Si vous utilisez syslog, utilisez le protocole UDP si la diffusion garantie des messages au serveur syslog, ainsi que le recours à TLS/SSL, ne sont pas obligatoires.

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

Règle JavaScript
Règle ExtractVariables
Exécuter du code après le traitement du proxy, y compris en cas d'erreur, avec le PostClientFlow