MessageLogging-Richtlinie

Sie lesen die Dokumentation zu Apigee Edge.
Rufen Sie die Dokumentation zu Apigee X auf. Weitere Informationen

Was

Eine der besten Möglichkeiten, Probleme in der API-Laufzeitumgebung zu ermitteln, besteht darin, Nachrichten zu protokollieren. Sie können eine MessageLogging-Richtlinie an Ihre API anhängen und diese konfigurieren, um benutzerdefinierte Nachrichten auf einem lokalen Laufwerk (nur Edge für Private Cloud) oder in Syslog zu protokollieren.

Samples

<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>
    <DateFormat>yyyy-MM-dd'T'HH:mm:ss.SSSZ</DateFormat>
  </Syslog>
  <logLevel>ALERT</logLevel>
</MessageLogging>

<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>
    <DateFormat>yyMMdd-HH:mm:ss.SSS</DateFormat>
  </Syslog>
  <logLevel>WARN</logLevel>
</MessageLogging>

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

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

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

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

Elementverweis

Verwenden Sie die folgenden Elemente, um den Richtlinientyp „MessageLogging“ zu konfigurieren.

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

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 Trace-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 zum Überprüfen des API-Schlüssels 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>

Edge protokolliert Nachrichten als einfachen Text und Sie können das Logging so konfigurieren, dass Variablen wie das Datum und die Uhrzeit des Empfangs der Anfrage oder Antwort, die Nutzeridentität bei der Anfrage, die Quell-IP-Adresse, von der die Anfrage gesendet wurde, usw. einbezogen werden. Edge-Logmeldungen werden asynchron gesendet, d. h., Ihre API erhält keine Latenz, die durch das Blockieren von Callouts verursacht werden könnte.

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

Wenn dieses Problem in Edge for Private Cloud 4.15.07 und niedriger auftritt, suchen Sie die Datei message-logging.properties und verwenden Sie diese Lösung:

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

Legen Sie für Edge for Private Cloud 4.16.01 und höher das Attribut conf/message-logging.properties+max. log.message.size.in.kb in der Datei /opt/apigee/customer/application/message-processor.properties fest und starten Sie den Message Processor neu. Diese Eigenschaft ist anfänglich standardmäßig auskommentiert.

Hinweis: Die Variablen für Antwortnachrichten in Edge sind nicht im Fehlerfluss verfügbar. Diese Variablen sind auch nicht im PostClientFlow verfügbar, wenn der vorherige Ablauf der Fehlerfluss war. Wenn Sie Antwortinformationen aus dem PostClientFlow protokollieren möchten, verwenden Sie das message-Objekt. Mit diesem Objekt können Sie Header und andere Informationen aus der Antwort abrufen, unabhängig davon, ob ein Fehler aufgetreten ist oder nicht. Weitere Informationen und ein Beispiel finden Sie unter Nachrichtenvariablen.

Zeitstempel der Log-Nachricht in Edge für Private Cloud steuern

Standardmäßig hat der Zeitstempel in allen Logeinträgen folgendes Format:

yyyy-MM-dd'T'HH:mm:ss.SSSZ

Diese systemweite Standardeinstellung kann für Syslog-Ziele mit dem Element DateFormat überschrieben werden. Das Verhalten dieser Vorlage wird in der Dokumentation zur SimpleDateFormat-Klasse von Java beschrieben. Gemäß dieser Definition wird yyyy durch ein vierstelliges Jahr, MM durch eine zweistellige Monatsnummer usw. ersetzt. Das obige Format kann zu einem String der folgenden Form führen:

2022-09-28T22:38:11.721+0000

Sie können das Attribut conf_system_apigee.syslogger.dateFormat im Edge Message Processor verwenden, um dieses Format zu steuern. Ändern Sie das Nachrichtenformat beispielsweise so:

yy/MM/dd'T'HH:mm:ss.SSSZ

...die Bindestriche durch Schrägstriche ersetzen und auf ein zweistelliges Jahr gekürzt werden, wird ein Zeitstempel in folgendem Format erfasst:

22/09/28T22:38:11.721+0000

So ändern Sie das Format:

1. Öffnen Sie die Datei message-processor.properties in einem Editor. Wenn die Datei nicht vorhanden ist, erstellen Sie sie:
   > vi /opt/apigee/customer/application/message-processor.properties
2. Legen Sie die Attribute wie gewünscht fest:
   conf_system_apigee.syslogger.dateFormat=yy/MM/dd'T'HH:mm:ss.SSSZ
3. Speichern Sie die Änderungen.
4. Achten Sie darauf, dass die Eigenschaftendatei dem „Apigee-Nutzer“ gehört:
   > chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
5. Starten Sie den Edge Message Processor neu:
   > /opt/apigee/apigee-service/bin/apigee-service Edge-message-processor neustart

Speicherort der Logdatei in Edge für die Private Cloud

Edge für Private Cloud 4.16.01 und höher

Standardmäßig befinden sich die Nachrichtenlogs der privaten Cloud auf Message Processor-Knoten im folgenden Verzeichnis:

/opt/apigee/var/log/edge-message-processor/messagelogging/org_name/environment/api_proxy_name/revision/logging_policy_name/

Sie können den Standardspeicherort für das Log ändern, indem Sie Attribute in der Datei „message-logging.properties“ in den Message Processors ändern:

• bin_setenv_data_dir – legt den Stammpfad für den Logdateispeicher fest. Beispiel:bin_setenv_data_dir=/opt/apigee/var/log
• conf_message-logging_log.root.dir – Wenn Sie dafür einen relativen Pfad wie conf/message-logging.properties+log.root.dir=custom/folder/, the path is appended to the bin_setenv_data_dir location. festlegen
  
  Wenn Sie dafür einen absoluten Pfad wie conf/message-logging.properties+log.root.dir=/opt/apigee/var/log/messages festlegen, werden die Nachrichtenlogs in /opt/apigee/var/log/messages/messagelog/ gespeichert. Ein absoluter Pfad hat Vorrang vor bin_setenv_data_dir.
  
  Sie müssen auf das Attribut als conf/message-logging.properties+log.root.dir verweisen, da es standardmäßig auskommentiert ist. Weitere Informationen finden Sie unter Token festlegen, das derzeit auskommentiert ist.

Wenn Sie Logdateien in einer flachen Dateistruktur speichern möchten, damit sich alle Logdateien im selben Verzeichnis befinden, setzen Sie conf/message-logging.properties+enable.flat.directory.structure in der Datei „message-logging.properties“ auf „true“. Nachrichten werden in dem Verzeichnis gespeichert, das durch die oben angegebenen Attribute festgelegt wurde. Die Dateinamen haben das Format {org}_{environment}_{api_proxy_name}_{revision}_{logging_policy_name}_{filename}.

So legen Sie diese Eigenschaften fest:

1. Öffnen Sie die Datei message-processor.properties in einem Editor. Wenn die Datei nicht vorhanden ist, erstellen Sie sie:
   > vi /opt/apigee/customer/application/message-processor.properties
2. Legen Sie die Attribute wie gewünscht fest:
   conf/message-logging.properties+log.root.dir=/opt/apigee/var/log/messages
3. Speichern Sie die Änderungen.
4. Achten Sie darauf, dass die Eigenschaftendatei dem „Apigee-Nutzer“ gehört:
   > chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
5. Starten Sie die Edge-Komponente neu:
   > /opt/apigee/apigee-service/bin/apigee-service Edge-message-processor neustart

Edge für Private Cloud 4.15.07 und frühere Versionen

Standardmäßig befinden sich die Meldungslogs an folgendem Speicherort auf Nachrichtenprozessoren:

/opt/apigee4/var/log/apigee/message-processor/messagelog/{org}/{environment}/{api_proxy_name}/{revision}/{logging_policy_name}/

Sie können den Standardspeicherort der Logs ändern, indem Sie die folgenden Attribute in der Datei message-logging.properties auf den Nachrichtenprozessoren bearbeiten:

• data.dir – Legt den Stammpfad für den Logdateispeicher fest. Zum Beispiel: data.dir=/opt/apigee4/var/log
• log.root.dir: Wenn Sie dafür einen relativen Pfad wie log.root.dir=custom/folder/ festlegen, wird der Pfad an den Speicherort von data.dir angehängt.

Die Kombination der beiden Attribute würde beispielsweise das Logging-Verzeichnis unter /opt/apigee4/var/log/custom/folder/messagelog/ festlegen (beachten Sie, dass /messagelog automatisch hinzugefügt wird).

Wenn Sie dies auf einen absoluten Pfad festlegen, wie z. B. log.root.dir=/opt/apigee4/var/log/messages, werden Meldungsprotokolle in /opt/apigee4/var/log/messages/messagelog/ gespeichert. Ein absoluter Pfad in log.root.dir hat Vorrang vor data.dir.

Wenn Sie Logdateien in einer flachen Dateistruktur speichern möchten, damit sich alle Logdateien im selben Verzeichnis befinden, setzen Sie das Attribut enable.flat.directory.structure in der Datei message-logging.properties von Nachrichtenprozessoren auf „true“. Nachrichten werden in dem Verzeichnis gespeichert, das durch die oben angegebenen Attribute festgelegt wurde. Die Dateinamen haben das Format {org}_{environment}_{api_proxy_name}_{revision}_{logging_policy_name}_{filename}.

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: https://community.apigee.com/content/kbentry/13298/log-messages-into-splunk.html
• Sumo Logic
  • Außerdem können Sie sich auch folgenden Beitrag zur Apigee-Community ansehen: https://community.apigee.com/questions/5226/setting-up-logging-with-sumo-logic-which-host-shou.html
  • 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: https://community.apigee.com/articles/32286/logging-to-sumo-logic-using-javascript-and-http.html
• Loggly
  Bei der Verwendung von Loggly ist <FormatMessage>true</FormatMessage> in der Richtlinie als untergeordnetes Element des <Syslog>-Elements erforderlich.
  Weitere Informationen zum Logging von Nachrichten finden Sie in diesem Beitrag der Apigee-Community unter https://community.apigee.com/content/kbentry/14798/log-messages-into-loggly.html

Fehlerreferenz

In diesem Abschnitt werden die Fehlercodes und Fehlermeldungen beschrieben, die zurückgegeben werden, sowie die Fehlervariablen, die von Edge festgelegt werden, wenn diese 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.

Bereitstellungsfehler

Diese Fehler können auftreten, wenn Sie einen Proxy bereitstellen, der diese Richtlinie enthält.

Fehlervariablen

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

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

• Von Edge sichtbare Variablen: Variablenreferenz