MessageLogging-Richtlinie

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Richtliniensymbol

Was

Mit der MessageLogging-Richtlinie haben Sie die Möglichkeit, benutzerdefinierte Nachrichten in Cloud Logging oder Syslog zu protokollieren. Sie können die Informationen in den Logs für verschiedene Aufgaben verwenden, z. B. zum Ermitteln von Problemen in der API-Laufzeitumgebung.

Diese Richtlinie ist eine erweiterbare Richtlinie, deren Verwendung je nach Apigee-Lizenz Auswirkungen auf die Kosten oder die Nutzung haben kann. Informationen zu Richtlinientypen und Auswirkungen auf die Nutzung finden Sie unter Richtlinientypen.

Es gibt zwei Möglichkeiten zum Verwenden der MessageLogging-Richtlinie:

  • Das Element <CloudLogging> protokolliert Nachrichten in Cloud Logging. Um diese Methode zu verwenden, müssen Sie die Cloud Logging APIs für Ihr Google Cloud-Projekt aktivieren. Weitere Informationen zum Aktivieren von APIs für ein Google Cloud-Projekt finden Sie unter Dienste aktivieren und deaktivieren.
  • Das Element <Syslog> protokolliert Nachrichten in Syslog. Dies ist ein Standardprotokoll zum Senden von Systemlog- oder Ereignisnachrichten an einen bestimmten Server. Für diese Methode benötigen Sie einen Syslog-Server. Alternativ können Sie öffentliche Logverwaltungsdienste wie Splunk, Sumo Logic und Loggly verwenden. Weitere Informationen finden Sie unter Dienste für die Logverwaltung von Drittanbietern konfigurieren.

Hinweis: Sie können das Element <CloudLogging> und das Element <Syslog> nicht in derselben Richtlinie verwenden.

Element <MessageLogging>

Definiert eine <MessageLogging>-Richtlinie.

Standardwert Siehe Standardrichtlinie Tab unten
Erforderlich? Erforderlich
Typ TYPE
Übergeordnetes Element –
Untergeordnete Elemente <CloudLogging>
<Syslog>
<logLevel>

Das <MessageLogging>-Element verwendet die folgende Syntax:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MessageLogging continueOnError="false" enabled="true" name="Message-Logging-1">
    <DisplayName>Message Logging-1</DisplayName>
    <Syslog>
<!-- Note: You cannot use both the <Syslog> element and the <CloudLogging> element in the same policy. -->
        <Message>Some message for syslog</Message>
        <Host>localhost</Host>
        <Port>514</Port>
    </Syslog>
    <CloudLogging>
<!-- Note: You cannot use both the <CloudLogging> and the <Syslog> element in the same policy. -->
        <LogName>projects/{organization.name}/logs/{log.id}</LogName>
        <Message contentType="application/json">{"{message.queryparam.key}": "{message.queryparam.value}"}</Message>
        <Labels>
            <Label>
                <Key>key1</Key>
                <Value>value1</Value>
            </Label>
            <Label>
                <Key>key2</Key>
                <Value>value2</Value>
            </Label>
        </Labels>
        <ResourceType>api</ResourceType>
    </CloudLogging>
    <logLevel>ALERT</logLevel>
</MessageLogging>

Dieses Element hat folgende Attribute, die allen Richtlinien gemeinsam sind:

Attribut Standard Erforderlich? Beschreibung
name - Erforderlich

Der interne Name der Richtlinie. Der Wert des Attributs name kann Buchstaben, Ziffern, Leerzeichen, Bindestriche, Unterstriche und Punkte enthalten. Dieser Wert darf 255 Zeichen nicht überschreiten.

Optional können Sie das Element <DisplayName> verwenden, um die Richtlinie im Proxy-Editor der Verwaltungs-UI mit einem anderen Namen in einer natürlichen Sprache zu versehen.
continueOnError false Optional Legen Sie false fest, um einen Fehler zurückzugeben, wenn eine Richtlinie fehlschlägt. Dies ist für die meisten Richtlinien das erwartete Verhalten. Legen Sie true fest, damit die Ablaufausführung auch nach dem Fehlschlagen einer Richtlinie fortgesetzt wird. Weitere Informationen:
enabled wahr Optional Setzen Sie den Wert auf true, um die Richtlinie zu erzwingen. Legen Sie false fest, um die Richtlinie zu deaktivieren. Die Richtlinie wird nicht durchgesetzt, selbst wenn sie mit einem Ablauf verknüpft ist.
async   false Verworfen Dieses Attribut wurde verworfen.

Die folgende Tabelle enthält eine allgemeine Beschreibung der untergeordneten Elemente von <MessageLogging>:

Feldname Feldbeschreibung
CloudLogging

Nachrichten konfigurieren, die in Cloud Logging geloggt werden sollen.
Syslog

Nachrichten konfigurieren, die in syslog geloggt werden sollen.

Beispiele

CloudLogging

<MessageLogging name="LogToCloudLogging">
    <CloudLogging>
        <LogName>projects/{organization.name}/logs/{log.id}</LogName>
        <Message contentType="application/json">{"{message.queryparam.key}": "{message.queryparam.value}"}</Message>
        <Labels>
            <Label>
                <Key>key1</Key>
                <Value>value1</Value>
            </Label>
            <Label>
                <Key>key2</Key>
                <Value>value2</Value>
            </Label>
        </Labels>
        <ResourceType>api</ResourceType>
    </CloudLogging>
</MessageLogging>

In diesem Beispiel wird die Verwendung von Nachrichtenvorlagen veranschaulicht. Das Element Message enthält folgende Ablaufvariablen:

{"{message.queryparam.key}": "{message.queryparam.value}"}

Daher wäre der resultierende Logeintrag {"fruit": "apple"}, wenn jemand den Proxy mit den Werten message.queryparam.key = "fruit" und message.queryparam.value = "apple" aufruft.

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

Angenommen, Sie müssen Informationen zu jeder Anfragenachricht loggen, 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. Das Format der Zeitstempel wird über die Spezifikationen zur Formatierung im Element DateFormat angegeben und sieht ungefähr so aus: 230704-13:42:17.376.

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.

Verweis auf untergeordnetes Element

In den folgenden Abschnitten werden die untergeordneten Elemente von <MessageLogging> erläutert.

<CloudLogging>

Verwenden Sie das Element <CloudLogging>, um Nachrichten in Cloud Logging zu loggen.

Feldname Erforderlich? Beschreibung
LogName Ja Name des Logs. Der Logname muss das Format projects/{PROJECT_ID}/logs/{LOG_ID} haben. Sie können anstelle von {PROJECT_ID} und {LOG_ID} auch Variablen verwenden.
Message Ja

Die Nachricht, die protokolliert werden soll. Die Nachricht hat das Attribut contentType. Dessen Wert kann entweder text/plain oder application/json für Text- oder JSON-Nachrichten sein kann (Beispiele).
Label Nein Label, das an die Lognachricht angehängt wird, falls vorhanden. Es hat das folgende Schlüssel/Wert-Paar-Format: 
<Label>
    <Key>key1</Key>
    <Value>value1</Value>
</Label>
ResourceType Nein (Standard ist global) Stellt die überwachte Ressource dar, die die Logs generiert.

Authentifizierung für Cloud Logging

Zur Verwendung des Elements <CloudLogging> müssen Sie Ihren API-Proxy für die Google-Authentifizierung bereitstellen. Apigee nutzt Anmeldedaten entsprechend der Identität des Dienstkontos, das Sie in den ausgehenden Anfragen an Cloud Logging angeben. Weitere Informationen finden Sie unter Google-Authentifizierung verwenden. Das Dienstkonto, das Sie zum Zeitpunkt des Deployments Ihrem API-Proxy zuordnen, muss eine Rolle mit der Berechtigung logging.logEntries.create haben. Weitere Informationen zu IAM-Rollen (Identity and Access Management) für <CloudLogging> finden Sie in der Anleitung zur Zugriffssteuerung.

<Syslog>

Um Nachrichten für das Protokollieren in syslog zu konfigurieren, verwenden Sie das Element <Syslog>. Wenn Sie <Syslog> nutzen, leitet ein API-Proxy Lognachrichten von Apigee an einen Remote-Syslog-Server weiter. Für diese Methode benötigen Sie einen Syslog-Server. Alternativ sind öffentliche Log-Verwaltungsdienste wie Splunk, Sumo Logic und Loggly verfügbar. Weitere Informationen finden Sie unter Dienste für die Logverwaltung von Drittanbietern konfigurieren.

Feldname Erforderlich? Feldbeschreibung
Message Ja

Die Nachricht, die protokolliert werden soll. Die Nachricht hat das Attribut contentType. Dessen Wert kann entweder text/plain oder application/json für Text- oder JSON-Nachrichten sein kann (Beispiele).
Host Nein 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 Nein Port, an dem der Syslog ausgeführt wird. Wenn Sie dieses Element nicht angeben, ist der Standardwert 514.
Protocol Nein 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 Nein. Für die Verwendung mit Loggly ist aber die Festlegung von <FormatMessage>true</FormatMessage> erforderlich.

true oder false (Standard)

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 2023-03-20T09: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 Nein

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.
DateFormat Nein

Ein String für eine Formatierungsvorlage, die zum Formatieren des Zeitstempels für jede Lognachricht verwendet wird. Standardmäßig verwendet Apigee yyyy-MM-dd'T'HH:mm:ss.SSSZ. Das Verhalten dieser Vorlage wird in der Dokumentation zur SimpleDateFormat-Klasse von Java beschrieben. Gemäß dieser Definition wird yyyy im Formatstring durch eine vierstellige Jahreszahl, MM durch eine zweistellige Monatszahl usw. ersetzt.

SSLInfo Nein

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>

Gültige Werte für das Element <logLevel> sind: INFO (Standard), ALERT, WARN, ERROR.

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

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

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: Die Antwort wird zurückgegeben, während die Logs noch geschrieben werden. Daher führt das Blockieren von Callouts zu keiner Latenz bei Ihrer API. Es ist möglich, dass ein Log nicht geschrieben, dafür aber kein Fehler zurückgegeben wird. Dies kommt jedoch selten vor.

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 der folgenden Nachrichten enthalten:

  • mit <CloudLoggingg>: 
    steps.messagelogging.TooManyPendingLoggingRequest
  • mit <Syslog>: 
    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 einzelne 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: 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.
steps.messagelogging.InvalidGoogleCloudLogName 500 Dieser Fehler wird ausgegeben, wenn der LogName nicht das gültige Format von projects/{project}/logs/{logid} ergibt.
steps.messagelogging.InvalidJsonMessage 500 Dieser Fehler tritt auf, wenn der Wert des contentType-Attributs als application/json ausgewählt wurde, der tatsächliche Nachrichtenwert aber kein gültiger JSON-String ist.
steps.messagelogging.TooManyPendingLoggingRequest 500 Dieser Fehler tritt auf, wenn mehr als 2.500 ausstehende Anfragen vorliegen, die noch nicht in Cloud Logging geschrieben wurden. Das Limit von 2.500 gilt für jeden Apigee-Laufzeit-Pod. Wenn der Traffic beispielsweise auf zwei Instanzen von Apigee-Laufzeit-Pods verteilt wird, beträgt das effektive Limit 5.000 Anfragen.
-

Bereitstellungsfehler

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

Fehlername Ursache Diverse Fehlerkorrekturen
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