MessageLogging-Richtlinie

Sie lesen die Dokumentation zu Apigee X.
Apigee Edge-Dokumentation aufrufen

Richtliniensymbol

Was

Eine der besten Möglichkeiten, Probleme in der API-Laufzeitumgebung zu ermitteln, besteht darin, Nachrichten zu protokollieren. Sie können eine API-Richtlinie für Ihre API anhängen und so konfigurieren, dass benutzerdefinierte Meldungen an syslog protokolliert werden.

Beispiele

syslog

<MessageLogging name="LogToSyslog">
  <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>514</Port>
    <Protocol>TCP</Protocol>
    <FormatMessage>true</FormatMessage>
  </Syslog>
  <logLevel>ALERT</logLevel>
</MessageLogging>

Die Art des Benachrichtigungstyps wird häufig in einem Syslog-Konto protokolliert. Wenn dieser für syslog konfiguriert ist, leitet ein API-Proxy Lognachrichten von Apigee an einen Remote-Syslog-Server weiter. Der Syslog-Server muss bereits vorhanden sein. Ist dies nicht der Fall, sind öffentliche Log-Verwaltungsdienste wie Splunk, Sumo Logic und Loggly verfügbar. Weitere Informationen finden Sie unter Dienste von Drittanbietern für die Logverwaltung konfigurieren.

Beispiel: Sie möchten Informationen zu jeder Anfragenachricht protokollieren, die Ihre API von Nutzeranwendungen empfängt. Der Wert 3f509b58 stellt einen Schlüsselwert dar, der für den Loggly-Dienst spezifisch ist. Wenn Sie ein Loggly-Konto haben, ersetzen Sie Ihren Loggly-Schlüssel. Die generierte Lognachricht enthält vier Werte: die Organisation, den API-Proxy und den Umgebungsnamen der Transaktion sowie den Wert für einen Abfrageparameter in der Anfragenachricht.

Syslog über TLS/SSL

<MessageLogging name="LogToSyslog">
  <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>WARN</logLevel>
</MessageLogging>

Mit dem Block <SSLInfo> können Sie Nachrichten über Drittanbieter-Logging für Nachrichten über TLS/SSL senden.

Dateirotation: Größe

<MessageLogging name="LogPolicy">
  <File>
    <Message>This is a test message. Message id : {request.header.messageid}</Message>
      <FileName>test.log</FileName>
      <FileRotationOptions rotateFileOnStartup="true">
        <FileRotationType>SIZE</FileRotationType>
        <MaxFileSizeInMB>10</MaxFileSizeInMB>
        <MaxFilesToRetain>10</MaxFilesToRetain>
      </FileRotationOptions>
  </File>
  <logLevel>ERROR</logLevel>
</MessageLogging>

Dateirotation basierend auf der Dateigröße.

Dateirotation: Zeit

<MessageLogging name="LogPolicy">
  <File>
    <Message>This is a test message. Message id : {request.header.messageid}</Message>
    <FileName>test.log</FileName>
    <FileRotationOptions rotateFileOnStartup="true">
      <FileRotationType>TIME</FileRotationType>
      <RotationFrequency unit="minute">10</RotationFrequency>
      <MaxFilesToRetain>10</MaxFilesToRetain>
    </FileRotationOptions>
  </File>
  <logLevel>ERROR</logLevel>
</MessageLogging>

Dateirotation basierend auf der Zeit.

Dateirotation: Zeit und Größe

<MessageLogging name="LogPolicy">
  <File>
    <Message>This is a test message. Message id : {request.header.messageid}</Message>
    <FileName>test.log</FileName>
    <FileRotationOptions rotateFileOnStartup="true">
      <FileRotationType>TIME_SIZE</FileRotationType>
      <MaxFileSizeInMB>10</MaxFileSizeInMB>
      <MaxFilesToRetain>10</MaxFilesToRetain>
      <RotationFrequency unit="minute">10</RotationFrequency>
    </FileRotationOptions>
  </File>
  <logLevel>ERROR</logLevel>
</MessageLogging>

Dateirotation basierend auf Zeit und Größe.

Für den Stream aktiviert

<MessageLogging name="LogPolicy">
  <File>
  ....
  ....
  </File>
  <BufferMessage>true</BufferMessage>
</MessageLogging>

Nachrichtenprotokollierung mit Stream


Elementverweis

Konfigurieren Sie mit den Elementen in der folgenden Tabelle den Richtlinientyp von MessageLogging.

Informationen zum Senden von Syslog an Splunk, Sumo Logic oder Loggly finden Sie unter Drittanbieter-Logverwaltungsdienste konfigurieren.

Feldname Feldbeschreibung
Message

Erstellen Sie die Nachricht, die an den Syslog gesendet werden soll. Kombinieren Sie Text mit Variablen, um die gewünschten Informationen zu erfassen. Beispiele

Host Der Hostname oder die IP-Adresse des Servers, an den der Syslog gesendet werden soll. Wenn Sie dieses Element nicht angeben, wird "localhost" als Standard verwendet.
Port Port, an dem der Syslog ausgeführt wird. Wenn Sie dieses Element nicht angeben, ist der Standardwert 514.
Protocol TCP oder UDP (Standardeinstellung). UDP ist leistungsfähiger, aber das TCP-Protokoll garantiert die Zustellung von Nachrichtenlogs an den Syslog-Server. Zum Senden von Syslog-Nachrichten über TLS/SSL wird nur TCP unterstützt.
FormatMessage

true oder false (Standard)

Optional, für die Verwendung mit Loggly ist jedoch <FormatMessage>true</FormatMessage> erforderlich.

Mit diesem Element können Sie das Format von Apigee-generierten Inhalten steuern, die der Nachricht vorangestellt werden. Ist die Richtlinie auf "true" gesetzt, wird der Syslog-Nachricht eine feste Anzahl von Zeichen vorangestellt, sodass Sie diese Informationen aus den Nachrichten herausfiltern können. Hier ist ein Beispiel für das feste Format:

<14>1 2016-02-23T09:24:39.039+0000 e49cd3a9-4cf6-48a7-abb9-7ftfe4d97d00 Apigee - - - Message starts here

Die von Apigee generierten Informationen umfassen:

  • <14> – ein Prioritätswert (siehe Syslog-Protokoll) basierend auf der Log-Ebene und der Einrichtungsebene der Nachricht.
  • 1 – Die aktuelle Syslog-Version.
  • Datum mit UTC-Versatz (UTC = +0000).
  • Nachrichtenprozessor-UUID.
  • "Apigee - - - "

Bei Einstellung auf "false" (Standardwert) werden der Nachricht diese festgelegten Zeichen nicht vorangestellt.

PayloadOnly

true oder false (Standard)

Mit diesem Element wird das Format von Apigee generierten Nachrichten so festgelegt, dass sie nur den Text der Syslog-Nachricht enthalten, ohne die von FormatMessage angegebenen vorangestellten Zeichen.

Wenn Sie dieses Element nicht einfügen oder leer lassen, wird der Standardwert false verwendet.

Siehe FormatMessage.

SSLInfo

Ermöglicht die Protokollierung von Nachrichten über SSL/TLS. Wird mit dem Unterelement <Enabled>true</Enabled> verwendet.

Wenn Sie dieses Element nicht angeben oder es leer lassen, ist der Standardwert "false" (kein TLS/SSL).


<SSLInfo>
    <Enabled>true</Enabled>
</SSLInfo>

Sie können das <SSL-Info>-Tag genauso konfigurieren wie auf einem TargetEndpoint, einschließlich der Aktivierung von bidirektionalem TLS/SSL, wie in der API-Proxy-Konfigurationsreferenz beschrieben. Es wird nur das TCP-Protokoll unterstützt.

logLevel

Optional:

Gültige Werte: INFO (Standard), ALERT, WARN, ERROR

Sie können eine bestimmte Informationsmenge festlegen, die im Nachrichtenprotokoll enthalten sein soll.

Wenn Sie das Element FormatMessage mit der Einstellung "true" verwenden, wirkt sich die Einstellung logLevel auf den berechneten Prioritätswert (die Zahl in den spitzen Klammern) in den von Apigee generierten Informationen aus.

Schemas


Nutzungshinweise

Wenn Sie eine MessageLogging-Richtlinie an einen API-Proxy-Flow anhängen, sollten Sie diesen in die ProxyEndpoint-Antwort in einem speziellen Ablauf namens PostClientFlow einfügen. Der PostClientFlow wird ausgeführt, nachdem die Antwort an den anfordernden Client gesendet wurde. Dadurch wird sichergestellt, dass alle Messwerte für Logging verfügbar sind. Weitere Informationen zur Verwendung von PostClientFlow finden Sie in der API-Proxy-Konfigurationsreferenz.

Der PostClientFlow hat zwei Möglichkeiten:

  1. Es wird nur als Teil des Antwortflusses ausgeführt.
  2. Es ist der einzige Fluss, der ausgeführt wird, wenn der Proxy den Fehlerstatus erreicht.

Da sie unabhängig davon ausgeführt wird, ob der Proxy erfolgreich war oder fehlgeschlagen ist, können Sie MessageLogging-Richtlinien in den PostClientFlow einfügen und so dafür sorgen, dass sie immer ausgeführt werden.

Das folgende Debug-Image zeigt eine MessageLogging-Richtlinie, die als Teil des PostClientFlow ausgeführt wird, nachdem die DefaultFaultRule ausgeführt wurde:

In diesem Beispiel hat die Richtlinie "API-Schlüssel überprüfen" den Fehler aufgrund eines ungültigen Schlüssels verursacht.

Im Folgenden sehen Sie die ProxyEndpoint-Definition mit PostClientFlow:

<ProxyEndpoint name="default">
  ...
  <PostClientFlow>
    <Response>
      <Step>
        <Name>Message-Logging-1</Name>
      </Step>
    </Response>
  </PostClientFlow>
  ...
</ProxyEndpoint>

Apigee protokolliert Nachrichten als einfachen Text. Sie können das Logging so konfigurieren, dass darin Variablen enthalten sind, z. B. das Datum und die Uhrzeit, zu der die Anfrage oder Antwort empfangen wurde, die Nutzeridentität der Anfrage sowie die Quell-IP-Adresse, von der die Anfrage gesendet wird, usw. Apigee protokolliert Lognachrichten asynchron. Dies bedeutet, dass keine Latenz entsteht, wenn Sie Callouts blockieren.

Die MessageLogging-Richtlinie schreibt protokollierte Nachrichten im Speicher in einen Zwischenspeicher. Der Nachrichten-Logger liest Nachrichten aus dem Zwischenspeicher und schreibt sie in das von Ihnen konfigurierte Ziel. Jedes Ziel hat einen eigenen Zwischenspeicher.

Wenn die Schreibrate für den Zwischenspeicher über die Leserate hinausgeht, schlagen das Pufferüberlauf und das Logging fehl. In diesem Fall kann die Logdatei eine Meldung mit folgendem Inhalt enthalten:

Log message size exceeded. Increase the max message size setting

Erhöhen Sie das Attribut max.log.message.size.in.kb (Standardwert = 128 KB) in der Datei message-logging.properties.

Standardwerte für Variablen in Nachrichtenvorlagen

Standardwerte können für jede Variable in der Nachrichtenvorlage separat angegeben werden. Wenn beispielsweise die Variable request.header.id nicht aufgelöst werden kann, wird der Wert durch den Wert unknown ersetzt.

<Message>This is a test message. id = {request.header.id:unknown}</Message>

Für alle nicht aufgelösten Variablen kann ein gemeinsamer Standardwert angegeben werden. Dazu legen Sie das Attribut defaultVariableValue für das Element Message fest:

<Message defaultVariableValue="unknown">This is a test message. id = {request.header.id}</Message>

Dienste für die Logverwaltung von Drittanbietern konfigurieren

Mit der MessageLogging-Richtlinie können Sie Syslog-Nachrichten an Dienste von Drittanbietern für die Logverwaltung wie Splunk, Sumo Logic und Loggly senden. Wenn Sie Syslog an einen dieser Dienste senden möchten, lesen Sie in der Dokumentation dieses Dienstes nach, wie Sie den Host, den Port und das Protokoll des Dienstes konfigurieren. Legen Sie dann das Syslog-Element für diese Richtlinie entsprechend fest.

Weitere Informationen finden Sie in der folgenden Dokumentation zum Konfigurieren der Konfiguration von Drittanbieter-Logs:

  • Splunk (Produktversion auswählen)
    Siehe auch diesen Apigee-Community-Beitrag an: Lognachrichten in Splunk
  • Sumo Logic
    • Weitere Informationen erhalten Sie im folgenden Beitrag zur Apigee-Community: Logging mit Sumo Logic einrichten
    • Ein vollständiges Beispiel für die Verwendung von Sumo Logic als Logging-Dienst finden Sie im folgenden Beitrag zur Apigee-Community. Die Lösung verwendet eine einzige JavaScript-Richtlinie, um HTTP POST-Anfragen an Sumo Logic HTTP Source Collector zu senden: Logging in Sumo Logic mit JavaScript und HTTP
  • Loggly
    Bei der Verwendung von Loggly ist <FormatMessage>true</FormatMessage> in der Richtlinie als untergeordnetes Element des <Syslog>-Elements erforderlich.
    Weitere Informationen zum Nachrichten-Logging finden Sie in diesem Beitrag der Apigee-Community: 7 Lognachrichten in Loggly anmelden

Fehlerreferenz

In diesem Abschnitt werden die zurückgegebenen Fehlercodes und Fehlermeldungen beschrieben, die von Apigee festgelegt werden, wenn die Richtlinie einen Fehler auslöst. Diese Informationen sind wichtig, wenn Sie Fehlerregeln zur Verarbeitung von Fehlern entwickeln. Weitere Informationen finden Sie unter Was Sie über Richtlinienfehler wissen müssen und Fehler beheben.

Laufzeitfehler

Diese Fehler können bei Ausführung der Richtlinie auftreten.

Fehlercode HTTP-Status Ursache
steps.messagelogging.StepDefinitionExecutionFailed 500 Siehe Fehlerstring.

Bereitstellungsfehler

Diese Fehler können auftreten, wenn Sie einen Proxy mit dieser Richtlinie bereitstellen.

Fehlername Ursache Beheben
InvalidProtocol Die Bereitstellung der MessageLogging-Richtlinie kann mit diesem Fehler fehlschlagen, wenn das im <Protocol>-Element angegebene Protokoll nicht gültig ist. Gültige Protokolle sind TCP und UDP. Zum Senden von Syslog-Nachrichten über TLS/SSL wird nur TCP unterstützt.
InvalidPort Die Bereitstellung der MessageLogging-Richtlinie kann mit diesem Fehler fehlschlagen, wenn die Portnummer nicht im <Port>-Element angegeben oder ungültig ist. Die Portnummer muss eine Ganzzahl größer als null sein.

Fehlervariablen

Diese Variablen werden bei Laufzeitfehlern festgelegt. Weitere Informationen finden Sie unter Was Sie über Richtlinienfehler wissen müssen.

Variablen Wo Beispiel
fault.name="fault_name" fault_name ist der Name des Fehlers, der in der obigen Tabelle Laufzeitfehler aufgeführt ist. Der Fehlername ist der letzte Teil des Fehlercodes. fault.name Matches "StepDefinitionExecutionFailed"
messagelogging.policy_name.failed policy_name ist der benutzerdefinierte Name der Richtlinie, die den Fehler ausgelöst hat. messagelogging.ML-LogMessages.failed = true

Beispiel für eine Fehlerantwort

{
   "fault":{
      "detail":{
         "errorcode":"steps.messagelogging.StepDefinitionExecutionFailed"
      },
      "faultstring":"Execution failed"
   }
}

Beispiel für eine Fehlerregel

<FaultRule name="MessageLogging">
    <Step>
        <Name>ML-LogMessages</Name>
        <Condition>(fault.name Matches "StepDefinitionExecutionFailed") </Condition>
    </Step>
    <Condition>(messagelogging.ML-LogMessages.failed = true) </Condition>
</FaultRule>


Ablaufvariablen

Die folgenden Variablen werden bei einem Richtlinienfehler ausgefüllt.

  • messagelogging.failed
  • messagelogging.{stepdefinition-name}.failed

Weitere Informationen