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

Sie sehen die Dokumentation zu Apigee Edge.
Zur Apigee X-Dokumentation
weitere Informationen

Mit der MessageLogging-Richtlinie von Apigee Edge können API-Proxy-Entwickler benutzerdefinierte Nachrichten in Syslog oder auf einem Laufwerk (nur Edge für Private Cloud) 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. Dies liegt daran, dass Apigee Edge eine Verbindung zu einem externen Syslog-Server für eine MessageLogging-Richtlinie öffnet. Wenn die Richtlinie TLS über TCP verwendet, entsteht 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.

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 Logservern 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.
  • Erhöhte Anzahl gleichzeitiger Dateideskriptoren, die vom Nachrichtenprozessor in Private Cloud-Konfigurationen geöffnet werden, in denen Datei-Logging verwendet wird.
  • 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

  • Mit einer ExtractVariables-Richtlinie oder JavaScript-Richtlinie können Sie alle zu protokollierenden Ablaufvariablen festlegen, sodass sie für die MessageLogging-Richtlinie verfügbar sind.
  • Verwenden Sie eine einzige MessageLogging-Richtlinie, um alle erforderlichen Daten im PostClientFlow zu protokollieren, der bedingungslos ausgeführt wird.
  • Verwenden Sie das UDP-Protokoll, bei dem 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 fehlgeschlagen ist 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