Norme di MessageLogging

Stai visualizzando la documentazione di Apigee Edge.
Vai alla documentazione di Apigee X. info

Cosa

Uno dei modi migliori per rilevare i problemi nell'ambiente di runtime dell'API è registrare i messaggi. Puoi associare e configurare un criterio di logging dei messaggi nell'API per registrare messaggi personalizzati su un disco locale (solo Edge per Private Cloud) o in syslog.

Esempi

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

Riferimento elemento

Utilizza i seguenti elementi per configurare il tipo di criterio di registrazione dei messaggi.

<FileName>/opt/apigee/var/log/messages/mylog.log</FileName>

<FileName>mylog.log</FileName>

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

Schemi

Note sull'utilizzo

Quando colleghi un criterio di logging dei messaggi a un flusso di proxy API, ti consigliamo di posizionarlo nella risposta ProxyEndpoint, in un flusso speciale chiamato PostClientFlow. PostClientFlow viene eseguito dopo l'invio della risposta al client richiedente, il che garantisce che tutte le metriche siano disponibili per la registrazione. Per informazioni dettagliate sull'utilizzo di PostClientFlow, consulta il riferimento per la configurazione dei proxy API.

PostClientFlow è speciale in due modi:

1. Viene eseguito solo nell'ambito del flusso di risposta.
2. È l'unico flusso eseguito dopo che il proxy entra nello stato di errore.

Poiché viene eseguito indipendentemente dal fatto che il proxy sia riuscito o meno, puoi inserire i criteri di registrazione dei messaggi in PostClientFlow e avere la certezza che vengano sempre eseguiti.

L'immagine di traccia seguente mostra un criterio di registrazione dei messaggi in esecuzione nell'ambito di PostClientFlow, dopo l'esecuzione di DefaultFaultRule:

In questo esempio, il criterio Verifica chiave API ha causato l'errore a causa di una chiave non valida.

Di seguito è riportata la definizione di ProxyEndpoint che include PostClientFlow:

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

Edge registra i messaggi come testo semplice e puoi configurare la registrazione in modo da includere variabili, ad esempio la data e l'ora in cui è stata ricevuta la richiesta o la risposta, l'identità utente nella richiesta, l'indirizzo IP di origine da cui è stata inviata la richiesta e così via. Edge registra i messaggi in modo asincrono, il che significa che non viene introdotta alcuna latenza che potrebbe essere causata dal blocco dei callout nella tua API.

Il criterio di registrazione dei messaggi scrive i messaggi registrati in memoria in un buffer. Il logger dei messaggi legge i messaggi dal buffer e poi li scrive nella destinazione configurata. Ogni destinazione ha il proprio buffer.

Gli utenti potrebbero riscontrare ritardi nella ricezione dei messaggi di log inviati a un nuovo endpoint syslog. Questo accade a causa di un comportamento di "avvio a freddo" intenzionale nel criterio. Quando viene configurata una nuova destinazione di registrazione, oltre alle destinazioni di registrazione esistenti, il Message Processor (MP) potrebbe prima mettere in coda 1000 messaggi di log in memoria prima di inviarli. Ciò può comportare un ritardo iniziale in ambienti con traffico ridotto. Questo ritardo iniziale non è osservabile per i tipici workload di produzione, poiché i messaggi dovrebbero accumularsi rapidamente. Una volta raggiunta la soglia, i messaggi di log verranno recapitati come previsto. L'esecuzione di un riavvio controllato del Message Processor può anche attivare il recapito dei messaggi in coda man mano che vengono rimossi dalla coda.

Se la frequenza di scrittura nel buffer aumenta oltre la frequenza di lettura, il buffer si riempie e il logging non va a buon fine. In questo caso, nel file di log potresti trovare un messaggio contenente quanto segue:

Log message size exceeded. Increase the max message size setting

Se riscontri questo problema in Edge for Private Cloud 4.15.07 e versioni precedenti, individua il message-logging.properties file e utilizza questa soluzione:

Aumenta la proprietà max.log.message.size.in.kb (valore predefinito = 128 KB) nel file message-logging.properties.

Per Edge for Private Cloud 4.16.01 e versioni successive, imposta la proprietà conf/message-logging.properties+max. log.message.size.in.kb nel file /opt/apigee/customer/application/message-processor.properties e riavvia il Message Processor. Tieni presente che questa proprietà è inizialmente commentata per impostazione predefinita.

Nota:le variabili del messaggio di risposta in Edge non sono disponibili dal flusso di errori. Inoltre, queste variabili non sono disponibili in PostClientFlow se il flusso precedente era il flusso di errore. Se vuoi registrare le informazioni sulla risposta da PostClientFlow, utilizza l'oggetto message. Puoi utilizzare questo oggetto per accedere alle intestazioni e ad altre informazioni della risposta, indipendentemente dal fatto che sia stato rilevato o meno un errore. Per ulteriori informazioni ed esempi, consulta la sezione VARIABILI DI MESSAGGIO.

Controllo del timestamp del messaggio di log in Edge for Private Cloud

Per impostazione predefinita, il timestamp in tutti i messaggi di log ha il seguente formato:

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

Questo valore predefinito a livello di sistema può essere ignorato per le destinazioni syslog utilizzando l'elemento DateFormat. Il comportamento di questo modello è descritto nella documentazione della classe SimpleDateFormat di Java. In base a questa definizione, yyyy verrà sostituito con un anno di 4 cifre, MM con un numero di mese di 2 cifre e così via. Il formato riportato sopra potrebbe generare una stringa di questo tipo:

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

Puoi utilizzare la proprietà conf_system_apigee.syslogger.dateFormat nell'Edge Message Processor per controllare il formato. Ad esempio, modificando il formato del messaggio in:

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

..sostituire i trattini con barre e accorciare l'anno a due cifre, registra un timestamp nel formato:

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

Per modificare il formato:

1. Apri il file message-processor.properties in un editor. Se il file non esiste, creane uno:
   > vi /opt/apigee/customer/application/message-processor.properties
2. Imposta le proprietà come preferisci:
   conf_system_apigee.syslogger.dateFormat=yy/MM/dd'T'HH:mm:ss.SSSZ
3. Salva le modifiche.
4. Assicurati che il file delle proprietà sia di proprietà dell'utente "apigee":
   > chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
5. Riavviare il gestore dei messaggi Edge:
   > /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

Posizione del file di log in Edge for Private Cloud

Edge for Private Cloud 4.16.01 e versioni successive

Per impostazione predefinita, i log dei messaggi del cloud privato si trovano nella seguente directory sui nodi del Message Processor:

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

Puoi modificare la posizione predefinita dei log modificando le proprietà nel file message-logging.properties nei Message Processor:

• bin_setenv_data_dir: imposta il percorso principale per l'archiviazione dei file di log. Ad esempio: bin_setenv_data_dir=/opt/apigee/var/log
• conf_message-logging_log.root.dir: se lo imposti su un percorso relativo, ad esempio conf/message-logging.properties+log.root.dir=custom/folder/, the path is appended to the bin_setenv_data_dir location.
  
  Se lo imposti su un percorso assoluto, ad esempio conf/message-logging.properties+log.root.dir=/opt/apigee/var/log/messages, i log dei messaggi verranno archiviati in /opt/apigee/var/log/messages/messagelog/. Un percorso assoluto ha la precedenza su bin_setenv_data_dir.
  
  Tieni presente che devi fare riferimento alla proprietà come conf/message-logging.properties+log.root.dir perché è commentata per impostazione predefinita. Per saperne di più, consulta Impostare un token attualmente commentato.

Se vuoi memorizzare i file di log in una struttura di file flat in modo che tutti i file di log vengano inseriti nella stessa directory, imposta conf/message-logging.properties+enable.flat.directory.structure su true nel file message-logging.properties. I messaggi vengono archiviati nella directory specificata dalle proprietà sopra indicate e i nomi dei file hanno la forma {org}_{environment}_{api_proxy_name}_{revision}_{logging_policy_name}_{filename}.

Per impostare queste proprietà:

1. Apri il file message-processor.properties in un editor. Se il file non esiste, creane uno:
   > vi /opt/apigee/customer/application/message-processor.properties
2. Imposta le proprietà come preferisci:
   conf/message-logging.properties+log.root.dir=/opt/apigee/var/log/messages
3. Salva le modifiche.
4. Assicurati che il file delle proprietà sia di proprietà dell'utente "apigee":
   > chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
5. Riavvia il componente Edge:
   > /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

Edge for Private Cloud 4.15.07 e versioni precedenti

Per impostazione predefinita, i log dei messaggi si trovano nella seguente posizione sui processori di messaggi:

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

Puoi modificare la posizione predefinita dei log modificando le seguenti proprietà nel file message-logging.properties sugli elaboratori dei messaggi:

• data.dir: imposta il percorso di base per l'archiviazione dei file di log. Ad esempio, data.dir=/opt/apigee4/var/log
• log.root.dir: se lo imposti su un percorso relativo, ad esempio log.root.dir=custom/folder/, il percorso viene aggiunto alla posizione data.dir.

Ad esempio, la combinazione delle due proprietà imposta la directory di log su /opt/apigee4/var/log/custom/folder/messagelog/ (tieni presente che /messagelog viene aggiunto automaticamente).

Se imposti un percorso assoluto, ad esempio log.root.dir=/opt/apigee4/var/log/messages, i log dei messaggi verranno archiviati in /opt/apigee4/var/log/messages/messagelog/. Un percorso assoluto in log.root.dir ha la precedenza su data.dir.

Se vuoi archiviare i file di log in una struttura di file flat in modo che tutti i file di log vengano inseriti nella stessa directory, imposta la proprietà enable.flat.directory.structure su true nel file message-logging.properties su Message Processors. I messaggi vengono archiviati nella directory specificata dalle proprietà precedenti e i nomi dei file hanno la forma {org}_{environment}_{api_proxy_name}_{revision}_{logging_policy_name}_{filename}.

Valori predefiniti per le variabili nel modello di messaggio

I valori predefiniti possono essere specificati separatamente per ogni variabile nel modello di messaggio. Ad esempio, se la variabile request.header.id non può essere risolta, il relativo valore viene sostituito con il valore unknown.

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

È possibile specificare un valore predefinito comune per tutte le variabili non risolte impostando l'attributo defaultVariableValue sull'elemento Message:

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

Configurazione di servizi di gestione dei log di terze parti

Il criterio di logging dei messaggi ti consente di inviare messaggi syslog a servizi di gestione dei log di terze parti, come Splunk, Sumo Logic e Loggly. Se vuoi inviare syslog a uno di questi servizi, consulta la documentazione del servizio per configurare l'host, la porta e il protocollo del servizio, quindi imposta di conseguenza l'elemento Syslog in questo criterio.

Per la configurazione della gestione dei log di terze parti, consulta la seguente documentazione:

• Splunk (seleziona la versione del prodotto)
  Leggi anche questo post della community Apigee: https://community.apigee.com/content/kbentry/13298/log-messages-into-splunk.html
• Sumo Logic
  • Consulta anche questo post della community Apigee: https://community.apigee.com/questions/5226/setting-up-logging-with-sumo-logic-which-host-shou.html
  • Per un esempio completo che utilizza Sumo Logic come servizio di logging, consulta il seguente post della community Apigee. La soluzione utilizza un unico criterio JavaScript per effettuare richieste HTTP POST a Sumo Logic HTTP Source Collector: https://community.apigee.com/articles/32286/logging-to-sumo-logic-using-javascript-and-http.html
• Loggly
  Quando utilizzi Loggly, <FormatMessage>true</FormatMessage> è obbligatorio nel criterio come elemento secondario dell'elemento <Syslog>.
  Per ulteriori informazioni sul logging dei messaggi in Loggly, consulta anche questo post della community di Apigee: https://community.apigee.com/content/kbentry/14798/log-messages-into-loggly.html

Messaggi di errore

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Example error response

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

Example fault rule

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

Variabili di flusso

Le seguenti variabili vengono compilate in caso di errore della norma.

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

Argomenti correlati

• Variabili esposte da Edge: Riferimento alle variabili