Antipattern: richiamare il criterio MessageLogging più volte in un proxy API

Stai visualizzando la documentazione di Apigee e Apigee hybrid.
Visualizza la documentazione di Apigee Edge.

I criteri di logging dei messaggi di Apigee consentono agli sviluppatori di proxy API di registrare messaggi personalizzati negli endpoint Cloud Logging o syslog. Qualsiasi informazione importante relativa alla richiesta dell'API, come parametri di input, payload della richiesta, codice di risposta, messaggi di errore (se presenti) e così via, può essere registrata per riferimento futuro o per il debug. Sebbene il criterio utilizzi un processo in background per eseguire il logging, esistono alcune limitazioni per l'utilizzo del criterio.

Antipattern

Il criterio di registrazione dei messaggi fornisce 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 dello stesso criterio di registrazione dei messaggi più volte o la presenza di più criteri di registrazione dei messaggi che registrano i dati in blocchi nello stesso proxy API in flussi diversi da PostClientFlow potrebbe avere implicazioni negative. Questo accade perché Apigee apre una connessione a un endpoint esterno per un criterio di registrazione dei messaggi. Se il criterio utilizza TLS su TCP, come per gli endpoint syslog, è presente il sovraccarico aggiuntivo dell'instaurazione di una connessione TLS.

Spieghiamolo con l'aiuto di un esempio di proxy API.

proxy API

Nell'esempio seguente, un criterio di registrazione dei messaggi denominato "LogRequestInfo" viene inserito nel flusso di richiesta e un altro criterio di registrazione dei messaggi denominato "LogResponseInfo" viene aggiunto al flusso di risposta. Entrambi si trovano in ProxyEndpoint PreFlow. 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ò comporterà un utilizzo aggiuntivo delle risorse di sistema, poiché potrebbero essere stabilite due connessioni TLS.

Inoltre, esiste un criterio di registrazione dei messaggi denominato "LogErrorInfo" che viene eseguito solo se si verifica un 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>

Norme relative al logging dei messaggi

Nei seguenti esempi di configurazioni dei criteri, i dati vengono registrati su server di log di terze parti utilizzando TLS su TCP. Se nello stesso proxy API viene utilizzato più di uno di questi criteri, il sovraccarico per l'impostazione e la gestione delle connessioni TLS occuperebbe ulteriore memoria di sistema e cicli della CPU, causando problemi di prestazioni su larga scala. Effetti negativi simili si verificano se utilizzi MessageLogging per eseguire il logging negli endpoint di Cloud Logging.

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 relative a 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 della rete dovuto all'instaurazione di connessioni agli endpoint dei log più volte durante il flusso dell'API Proxy.
  • Se il server syslog è lento o non è in grado di gestire l'elevato volume causato da più chiamate syslog, causerà una pressione a ritroso sull'elaboratore dei messaggi, con conseguente elaborazione lenta delle richieste e latenza potenzialmente elevata o errori di timeout del gateway 504.

  • Se il criterio di registrazione dei messaggi viene inserito in flussi diversi dal flusso PostClient, è possibile che le informazioni non vengano registrate, in quanto il criterio di registrazione dei messaggi non verrà eseguito se si verifica un errore prima dell'esecuzione di questo criterio.

    Nell'esempio ProxyEndpoint precedente, le informazioni non verranno registrate nelle seguenti circostanze:

    • Se uno dei criteri posizionati prima del criterio LogRequestInfo nel flusso di richiesta non va a buon fine.
      oppure
    • Se il server di destinazione non funziona con qualsiasi errore (HTTP 4XX, 5XX). In questa situazione, se non viene restituita una risposta positiva, il criterio LogResponseInfo non verrà eseguito.

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

Best practice

  • All'interno del flusso proxy, utilizza una o più istanze del criterio ExtractVariables o del criterio JavaScript per impostare tutte le variabili del flusso da registrare in una variabile di contesto; in questo modo, saranno disponibili per il criterio di registrazione dei messaggi che verrà eseguito in un secondo momento.
  • Utilizza un singolo criterio di logging dei messaggi per registrare tutti i dati richiesti in PostClientFlow, che viene eseguito incondizionatamente.
  • Se utilizzi syslog, utilizza il protocollo UDP se la consegna garantita dei messaggi al server syslog non è obbligatoria e TLS/SSL non è obbligatorio.

Il criterio di logging dei messaggi è stato progettato per essere disaccoppiato dalla funzionalità effettiva dell'API, incluso gestione degli errori. Pertanto, se lo chiami in PostClientFlow, che è esterno all'elaborazione della richiesta/risposta, i dati verranno sempre registrati indipendentemente dal fatto che l'API abbia avuto esito positivo o meno.

Ecco un esempio di chiamata del criterio di registrazione dei messaggi 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 di registrazione dei messaggi, 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 dopo un flusso di errore, è importante impostare esplicitamente le variabili woeid e weather.response* utilizzando i criteri ExtractVariables o JavaScript.

Per approfondire