Antipadrão: invoque a política MessageLogging várias vezes em um proxy de API

Esta é a documentação da Apigee e da Apigee híbrida.
Confira a documentação da Apigee Edge.

A política MessageLogging da Apigee permite que os desenvolvedores de proxy de API registrem mensagens personalizadas em syslog ou endpoints do Cloud Logging. Qualquer informação importante relacionada à solicitação de API, como parâmetros de entrada, payload da solicitação, código de resposta, mensagens de erro (se houver), pode ser registrada para referência posterior ou para depuração. A política usa um processo em segundo plano para executar a geração de registros, mas há ressalvas quanto ao uso dela.

Antipadrão

A política MessageLogging é uma maneira eficiente de receber mais informações sobre uma solicitação de API e depurar problemas encontrados com ela. No entanto, usar a mesma política MessageLogging mais de uma vez ou ter várias delas em blocos no mesmo proxy de API, em fluxos diferentes do PostClientFlow, pode ter implicações adversas. Isso ocorre porque a Apigee abre uma conexão com um endpoint externo para uma política MessageLogging. Se a política usar TLS sobre TCP, como acontece com os endpoints syslog, haverá uma sobrecarga adicional de estabelecer uma conexão TLS.

Vamos explicar isso com a ajuda de um exemplo de proxy de API.

Proxy de API

No exemplo a seguir, uma política MessageLogging chamada "LogRequestInfo" é colocada no fluxo de solicitação, e outra política MessageLogging chamada "LogResponseInfo" é adicionada ao fluxo de resposta. Ambos estão no pré-processamento ProxyEndpoint. A política LogRequestInfo é executada em segundo plano assim que o proxy da API recebe a solicitação e a política LogResponseInfo é executada após o proxy receber uma resposta do servidor de destino, mas antes do proxy retornar a resposta ao cliente da API. Isso consumirá mais recursos do sistema, já que duas conexões TLS estão sendo estabelecidas.

Além disso, há uma política MessageLogging chamada "LogErrorInfo", que é executada somente se houver um erro durante a execução do proxy da 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>

Política de geração de registros de mensagens

Nos exemplos de configurações de política a seguir, os dados estão sendo registrados em servidores de registros de terceiros usando TLS sobre TCP. Se mais de uma dessas políticas for usada no mesmo proxy da API, a sobrecarga de estabelecer e gerenciar conexões TLS ocupará mais memória do sistema e ciclos de CPU, levando a problemas de desempenho em escala. Efeitos negativos semelhantes ocorrem se você usar o MessageLogging para fazer login em endpoints do Cloud Logging.

Política 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>

Política do 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>

Política do 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>

Impacto

  • Aumento da sobrecarga de rede devido ao estabelecimento de conexões com os servidores de registros várias vezes durante o fluxo de proxy de API.
  • Se o servidor syslog estiver lento ou não puder lidar com o volume alto causado por várias chamadas syslog, haverá uma pressão no processador da mensagem, o que resultará em um processamento de solicitação lento e erros de latência possivelmente elevada ou 504 Gateway Timeout.

  • Se a política de MessageLogging for colocada em fluxos diferentes do PostPost, há uma possibilidade de que as informações não sejam registradas, já que a política do LoggingLogging não será executada se alguma falha ocorrer antes da execução dela.

    No exemplo de ProxyEndpoint anterior, as informações não serão registradas nas seguintes circunstâncias:

    • Se qualquer uma das políticas colocadas antes da política LogRequestInfo no fluxo de solicitação falhar.
      ou
    • Se o servidor de destino falhar com algum erro (HTTP 4XX, 5XX). Nessa situação, quando uma resposta bem-sucedida não é retornada, a política LogResponseInfo não será executada.

    Em ambos os casos, a política LogErrorInfo será executada e registrará apenas as informações relacionadas a erros.

Práticas recomendadas

  • No fluxo do proxy, use uma ou mais instâncias da política ExtractVariables ou do JavaScript para definir todas as variáveis de fluxo que precisam ser registradas em uma variável de contexto. Isso as disponibilizará para a política MessageLogging que será executada mais tarde.
  • Use uma única política MessageLogging para registrar todos os dados necessários no PostClientFlow, que são executados de maneira não condicional.
  • Se você estiver usando o syslog, use o protocolo UDP se a entrega garantida de mensagens para o servidor syslog não for obrigatória e o TLS/SSL não for obrigatório.

A política MessageLogging foi criada para ser separada da funcionalidade real da API, incluindo tratamento de erros. Portanto, sua invocação no PostClientFlow, que está fora do processamento de solicitação/resposta, significa que ela sempre registrará dados independentemente de a API ter falhado ou não.

Veja um exemplo que invoca a política MessageLogging no PostClientFlow:

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

Veja um exemplo de uma política MessageLogging, LogInfo, que registra todos os dados:

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

Como as variáveis de resposta não estão disponíveis no PostClientFlow após um fluxo de erro, é importante definir explicitamente as variáveis woeid e weather.response* usando ExtractVariables ou políticas JavaScript.

Leitura adicional