MessageLogging-Richtlinie

Sie sehen die Dokumentation zu Apigee Edge.
Zur Apigee X-Dokumentation 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 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 MessageLogging-Richtlinientyp 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 „API-Schlüssel verifizieren“ 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 in der Anfrage, die Quell-IP-Adresse, von der die Anfrage gesendet wurde, usw. enthält. Edge protokolliert die Nachricht asynchron, was bedeutet, dass keine Latenz, die durch blockierende Callouts verursacht werden kann, in Ihre API eingebracht wird.

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 für Private Cloud 4.15.07 und früher 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_max.log.message.size.in.kb in der Datei /opt/apigee/customer/application/message-processor.properties fest und starten Sie den Message Processor neu.

Hinweis: Die Variablen von Antwortnachrichten in Edge sind im Fehlerfluss nicht 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 von Lognachrichten 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 Java-Klasse SimpleDateFormat beschrieben. Gemäß dieser Definition wird yyyy durch eine vierstellige Jahreszahl, MM durch eine zweistellige Monatsnummer ersetzt usw. Das obige Format kann zu einem String der folgenden Form führen:

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

Sie können die Eigenschaft conf_system_apigee.syslogger.dateFormat auf dem Edge Message Processor verwenden, um dieses Format zu steuern. Ändern Sie beispielsweise das Nachrichtenformat in:

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

Wenn die Bindestriche durch Schrägstriche ersetzt und auf ein zweistelliges Jahr verkürzt werden, wird ein Zeitstempel im folgenden 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 Attributdatei dem Benutzer „apigee“ gehört:
   > chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
5. Starten Sie den Edge-Nachrichtenprozessor neu:
   > /opt/apigee/apigee-service/bin/apigee-service-Edge-Nachrichtenprozessor-Neustart

Speicherort der Protokolldatei in Edge für Private Cloud

Edge für Private Cloud 4.16.01 und höher

Private Cloud-Meldungslogs befinden sich standardmäßig auf Message Processor-Knoten in folgendem 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 Protokoll ändern, indem Sie die Attribute in der Datei message-logging.properties der Message Processors ändern:

• bin_setenv_data_dir: Legt den Stammpfad für die Speicherung der Logdateien 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 Nachrichtenlogs in /opt/apigee/var/log/messages/messagelog/ gespeichert. Ein absoluter Pfad hat Vorrang vor bin_setenv_data_dir.
  
  Sie müssen das Attribut als conf/message-logging.properties+log.root.dir referenzieren, 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, sodass 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 in den oben genannten Attributen angegeben 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 Attributdatei dem Benutzer „apigee“ 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 niedriger

Meldungslogs befinden sich standardmäßig 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 für Logs ändern, indem Sie die folgenden Attribute in der Datei „message-logging.properties“ für die Nachrichtenprozessoren ändern:

• data.dir: Legt den Stammpfad für die Speicherung der Logdateien fest. Beispiel: data.dir=/opt/apigee4/var/log
• log.root.dir – Wenn Sie einen relativen Pfad angeben, z. B. log.root.dir=custom/folder/, wird der Pfad an den Speicherort 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 wie log.root.dir=/opt/apigee4/var/log/messages festlegen, werden Meldungsprotokolle in /opt/apigee4/var/log/messages/messagelog/ gespeichert. Ein absoluter Pfad in log.root.dir hat Vorrang vor data.dir.

Wenn Sie Protokolldateien in einer flachen Dateistruktur speichern möchten, sodass sich alle Protokolldateien im selben Verzeichnis befinden, setzen Sie die Eigenschaft enable.flat.directory.structure in der Datei message-logging.properties auf Nachrichtenprozessoren auf „true“. Nachrichten werden in dem Verzeichnis gespeichert, das in den oben genannten Attributen angegeben 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 bereitgestellte Variablen: Variablenreferenz