Anti-Pattern: Die MessageLogging-Richtlinie mehrmals in einem API-Proxy aufrufen

Sie lesen gerade die Dokumentation zu Apigee und Apigee Hybrid.
Apigee Edge-Dokumentation aufrufen.

Mit der MessageLogging-Richtlinie von Apigee können API-Proxy-Entwickler benutzerdefinierte Meldungen in Cloud Logging- oder syslog-Endpunkten protokollieren. Wichtige Informationen zur API-Anfrage, wie z. B. Eingabeparameter, Anfragenutzlast, Antwortcode, Fehlermeldungen (falls vorhanden) usw. können für die spätere Verwendung für das Debugging in protokolliert werden. Die Richtlinie verwendet ein Hintergrundverfahren zur Ausführung des Loggings. Bei der Verwendung der Richtlinie müssen jedoch Einschränkungen beachtet werden.

Anti-Pattern

Die MessageLogging-Richtlinie bietet eine effiziente Möglichkeit, weitere Informationen zu einer API-Anfrage abzurufen und Fehler zu beheben, die bei der API-Anfrage auftreten. Wenn Sie jedoch dieselbe MessageLogging-Richtlinie mehrmals oder mehrere MessageLogging-Richtlinien für das Logging von Daten in Blöcken im selben API-Proxy in anderen Abläufen als dem PostClientFlow verwenden, kann dies negative Auswirkungen haben. Das liegt daran, dass Apigee für eine MessageLogging-Richtlinie eine Verbindung zu einem externen Endpunkt öffnet. Wenn die Richtlinie TLS über TCP verwendet, entsteht wie bei syslog-Endpunkten zusätzlicher Aufwand beim Herstellen einer TLS-Verbindung.

Erläutern wir dies mithilfe eines Beispiel-API-Proxys.

API-Proxy

Im folgenden Beispiel wird eine MessageLogging-Richtlinie namens "LogRequestInfo" in den Anfrageablauf eingefügt und dem Antwortablauf wird eine weitere MessageLogging-Richtlinie namens "LogResponseInfo" hinzugefügt. Beide befinden sich im PreEndpoint-PreFlow. Die LogRequestInfo-Richtlinie wird im Hintergrund ausgeführt, sobald der API-Proxy die Anfrage empfängt. Die LogResponseInfo-Richtlinie wird ausgeführt, nachdem der Proxy eine Antwort vom Zielserver erhalten hat, aber bevor der Proxy die Antwort an den API-Client zurückgibt. Dadurch werden zusätzliche Systemressourcen verbraucht, da möglicherweise zwei TLS-Verbindungen hergestellt werden.

Außerdem gibt es eine MessageLogging-Richtlinie namens "LogErrorInfo", die nur ausgeführt wird, wenn während der API-Proxy-Ausführung ein Fehler auftritt.

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

MessageLogging-Richtlinie

In den folgenden Beispielrichtlinien für Konfigurationen werden die Daten mit TLS über TCP an Drittanbieter-Logserver protokolliert. Wenn mehrere dieser Richtlinien im selben API-Proxy verwendet werden, beansprucht das Herstellen und Verwalten von TLS-Verbindungen zusätzlichen Systemarbeitsspeicher und CPU-Zyklen, was zu bedeutenden Leistungsproblemen führt. Ähnliche negative Auswirkungen treten auf, wenn Sie MessageLogging für das Logging bei Cloud Logging-Endpunkten verwenden.

LogRequestInfo-Richtlinie

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

LogResponseInfo-Richtlinie

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

LogErrorInfo-Richtlinie

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

Auswirkungen

  • Erhöhter Netzwerkaufwand, da Verbindungen zu den Log-Endpunkten während des API-Proxy-Ablaufs mehrmals hergestellt werden.
  • Wenn der Syslog-Server langsam ist oder das durch mehrere syslog-Aufrufe verursachte hohe Volumen nicht verarbeiten kann, verursacht dies einen hohen Druck auf dem Nachrichtenprozessor. Dies führt zu einer langsamen Anfrageverarbeitung und zu hoher Latenz bzw. zu 504 Gateway-Zeitüberschreitungen.

  • Wenn die MessageLogging-Richtlinie in anderen Abläufen als dem PostClient-Ablauf platziert wird, kann es sein, dass die Informationen nicht geloggt werden, da die MessageLogging-Richtlinie nicht ausgeführt wird, wenn vor der Ausführung dieser Richtlinie ein Fehler auftritt.

    Im vorherigen ProxyEndpoint-Beispiel werden die Informationen unter den folgenden Umständen nicht geloggt:

    • Wenn eine der im Anfrageablauf vor der LogRequestInfo-Richtlinie platzierten Richtlinien fehlschlägt.
      oder
    • Wenn der Zielserver mit einem Fehler fehlschlägt (HTTP 4XX, 5XX). Wenn in diesem Fall keine erfolgreiche Antwort zurückgegeben wird, wird die LogResponseInfo-Richtlinie nicht ausgeführt.

    In beiden Fällen wird die LogErrorInfo-Richtlinie ausgeführt und es werden nur die Fehlerinformationen protokolliert.

Best Practice

  • Verwenden Sie im Proxyablauf eine oder mehrere Instanzen der ExtractVariables-Richtlinie oder der JavaScript-Richtlinie, um alle Ablaufvariablen festzulegen, die in einer Kontextvariable protokolliert werden sollen. Dadurch werden sie für die spätere Ausführung der MessageLogging-Richtlinie verfügbar.
  • Verwenden Sie eine einzige MessageLogging-Richtlinie, um alle erforderlichen Daten im PostClientFlow zu protokollieren, der bedingungslos ausgeführt wird.
  • Wenn Sie Syslog nutzen, verwenden Sie das UDP-Protokoll, wenn die garantierte Zustellung von Nachrichten an den Syslog-Server nicht erforderlich ist und TLS/SSL nicht obligatorisch ist.

Die MessageLogging-Richtlinie wurde von der eigentlichen API-Funktionalität, einschließlich der Fehlerbehandlung, entkoppelt. Wenn Sie sie im PostClientFlow aufrufen, also außerhalb der Anfrage-/Antwortverarbeitung, werden Daten immer unabhängig davon aufgezeichnet, ob die API erfolgreich war oder nicht.

Hier ist ein Beispiel für den Aufruf der MessageLogging-Richtlinie in PostClientFlow:

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

Hier sehen Sie ein Beispiel für eine MessageLogging-Richtlinie, LogInfo, in der alle Daten protokolliert werden:

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

Da Antwortvariablen nach einem ErrorFlow nicht in PostClientFlow verfügbar sind, müssen woeid- und weather.response*-Variablen mithilfe von ExtractVariables oder JavaScript-Richtlinien explizit festgelegt werden.

Weitere Informationen