Anti-pattern: richiama più volte il criterio MessageLogging in un proxy API

Stai visualizzando la documentazione di Apigee Edge.
Vai alla documentazione di Apigee X. informazioni

Il criterio MessageLogging di Apigee Edge consente agli sviluppatori di proxy API di registrare messaggi personalizzati su syslog o su disco (solo Edge per Cloud privato). Tutte le informazioni importanti relative alla richiesta API, come parametri di input, payload della richiesta, codice di risposta, messaggi di errore (se presenti) e così via, possono essere registrate per riferimento futuro o per il debug. Anche se il criterio utilizza un processo in background per eseguire il logging, è necessario prestare attenzione all'utilizzo del criterio.

Antipattern

Il criterio MessageLogging offre un modo efficiente per ottenere ulteriori informazioni su una richiesta API e per eseguire il debug di eventuali problemi riscontrati con la richiesta API. Tuttavia, l'utilizzo più volte dello stesso criterio MessageLogging o la presenza di più criteri MessageLogging che registrano i dati in blocchi nello stesso proxy API in flussi diversi da PostClientFlow potrebbero avere implicazioni negative. Questo perché Apigee Edge apre una connessione a un server syslog esterno per un criterio MessageLogging. Se il criterio utilizza TLS su TCP, esiste un ulteriore sovraccarico dovuto allo stabilire una connessione TLS.

Spieghiamo ciò con l'aiuto di un proxy API di esempio.

proxy API

Nell'esempio seguente, un criterio MessageLogging denominato "LogRequestInfo" viene inserito nel flusso di richiesta, mentre un altro criterio MessageLogging denominato "LogResponseInfo" viene aggiunto al flusso di risposta. Entrambi si trovano nel PreFlow ProxyEndpoint. Il criterio LogRequestInfo viene eseguito in background non appena il proxy API riceve la richiesta e il criterio LogResponseInfo viene eseguito dopo che il proxy ha ricevuto una risposta dal server di destinazione, ma prima che il proxy restituisca la risposta al client API. Ciò consumerà ulteriori risorse di sistema poiché potrebbero essere stabilite due connessioni TLS.

Inoltre, è presente un criterio MessageLogging denominato "LogErrorInfo" che viene eseguito solo in caso di errore durante l'esecuzione del proxy 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>

Criterio di logging dei messaggi

Nelle configurazioni di criteri di esempio seguenti, i dati vengono registrati su server di log di terze parti utilizzando TLS su TCP. Se più di uno di questi criteri viene utilizzato sullo stesso proxy API, l'overhead associato alla creazione e alla gestione delle connessioni TLS occuperebbe ulteriore memoria di sistema e cicli di CPU, causando problemi di prestazioni su larga scala.

Norme relative a 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>

Norme di 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>

Norme relative a 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>

Impatto

  • Aumento dell'overhead di networking dovuto all'instaurazione ripetuta di connessioni ai server di log durante il flusso del proxy API.
  • Se il server syslog è lento o non è in grado di gestire il volume elevato causato da più chiamate syslog, causerà una contropressione sul processore di messaggi, con conseguenti errori di elaborazione delle richieste lenta, latenza elevata o timeout del gateway 504.
  • Aumento del numero di descrittori di file simultanei aperti dal processore di messaggi nelle configurazioni del cloud privato in cui è utilizzato il logging dei file.

  • Se il criterio MessageLogging viene inserito in flussi diversi dal flusso PostClient, è possibile che le informazioni non vengano registrate, poiché il criterio MessageLogging non verrà eseguito in caso di errore prima dell'esecuzione di questo criterio.

    Nel precedente esempio di ProxyEndpoint, le informazioni non verranno registrate nelle seguenti circostanze:

    • Se uno dei criteri posizionati prima del criterio LogRequestInfo nel flusso di richiesta ha esito negativo.
      o
    • In caso di errore del server di destinazione (HTTP 4XX, 5XX). In questo caso, se non viene restituita una risposta positiva, il criterio LogResponseInfo non viene eseguito.

    In entrambi i casi, il criterio LogErrorInfo verrà eseguito e registrerà solo le informazioni relative all'errore.

Best practice

  • Utilizza un criterio ExtractVariables o JavaScript per impostare tutte le variabili di flusso che devono essere registrate, rendendole disponibili per il criterio MessageLogging.
  • Utilizza un singolo criterio MessageLogging per registrare tutti i dati richiesti in PostClientFlow, che viene eseguito incondizionatamente.
  • Utilizza il protocollo UDP, per cui la consegna garantita dei messaggi al server syslog non è richiesta e TLS/SSL non è obbligatorio.

Il criterio MessageLogging è stato progettato per essere disaccoppiato dalle funzionalità effettive dell'API, inclusa la gestione degli errori. Pertanto, richiamarlo in PostClientFlow, al di fuori dell'elaborazione di richieste/risposte, significa che i dati verranno sempre registrati indipendentemente dal fatto che l'API abbia avuto esito negativo o meno.

Ecco un esempio di chiamata del criterio MessageLogging in PostClientFlow:

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

Ecco un esempio di criterio MessageLogging, LogInfo, che registra tutti i dati:

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

Poiché le variabili di risposta non sono disponibili in PostClientFlow in seguito a un flusso di errori, è importante impostare esplicitamente le variabili woeid e weather.response* utilizzando i criteri ExtractVariables o JavaScript.

Per approfondire