Criterio MessageLogging

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

Cosa

Uno dei modi migliori per rilevare i problemi nell'ambiente di runtime delle API è registrare i messaggi. Puoi collegare e configurare un criterio MessageLogging nella tua API per registrare i messaggi personalizzati su un disco locale (solo Edge per il cloud privato) o in syslog.

Campioni

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

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

Schema

Note sull'utilizzo

Quando colleghi un criterio MessageLogging a un flusso di proxy API, valuta la possibilità di inserirlo nella risposta ProxyEndpoint, in un flusso speciale denominato PostClientFlow. PostClientFlow viene eseguito dopo l'invio della risposta al client richiedente, per garantire che tutte le metriche siano disponibili per il logging. Per maggiori dettagli sull'utilizzo di PostClientFlow, consulta Riferimento alla configurazione del proxy API.

PostClientFlow è speciale in due modi:

1. È stata eseguita solo come parte del flusso di risposta.
2. È l'unico flusso eseguito dopo che il proxy entra nello stato di errore.

Poiché viene eseguito indipendentemente dall'esito positivo o negativo del proxy, puoi inserire i criteri MessageLogging in PostClientFlow e avere la certezza che vengano sempre eseguiti.

L'immagine di traccia seguente mostra un criterio MessageLogging in esecuzione come parte di PostClientFlow, dopo l'esecuzione della regola predefinitaFaultRule:

In questo esempio, il criterio Verify API Key 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>

I messaggi dei log perimetrale sono sotto forma di testo semplice e puoi configurare il logging in modo da includere variabili, ad esempio la data e l'ora in cui sono state ricevute la richiesta o la risposta, l'identità dell'utente nella richiesta, l'indirizzo IP di origine da cui è stata inviata la richiesta e così via. I messaggi dei log perimetrali vengono inviati in modo asincrono, il che significa che nell'API non viene introdotta nessuna latenza che potrebbe essere causata dal blocco dei callout.

Il criterio MessageLogging scrive i messaggi registrati in memoria in un buffer. Il logger dei messaggi legge i messaggi dal buffer, quindi scrive nella destinazione configurata. Ogni destinazione ha il proprio buffer.

Se la frequenza di scrittura nel buffer aumenta oltre la velocità di lettura, l'overflow del buffer e il logging non riusciranno. In questo caso, nel file di log potrebbe essere visualizzato un messaggio contenente quanto segue:

Log message size exceeded. Increase the max message size setting

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

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

Per Edge per 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 processore di messaggi. Tieni presente che inizialmente questa proprietà è commentata per impostazione predefinita.

Nota: le variabili dei messaggi di risposta in Edge non sono disponibili nel flusso di errori. Inoltre, queste variabili non sono disponibili in PostClientFlow se il flusso precedente era il flusso di errori. Se vuoi registrare le informazioni di risposta da PostClientFlow, utilizza l'oggetto message. Puoi utilizzare questo oggetto per ottenere le intestazioni e altre informazioni dalla risposta, indipendentemente dal fatto che si sia verificato o meno un errore. Per ulteriori informazioni e un esempio, consulta Variabili del messaggio.

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

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

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

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

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

Puoi utilizzare la proprietà conf_system_apigee.syslogger.dateFormat sul processore di messaggi Edge per controllare quel formato. Ad esempio, se cambi il formato del messaggio in:

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

..sostituendo i trattini con barre e abbreviando il testo in base all'anno a due cifre, viene registrato un timestamp nel modulo:

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, crealo:
   > 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à appartenga all'utente 'apigee':
   > chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
5. Riavvia il processore di messaggi Edge:
   > /opt/apigee/apigee-service/bin/apigee-service edge-message-processor riavvio

Posizione del file di log in Edge per Private Cloud

Edge per Private Cloud 4.16.01 e versioni successive

Per impostazione predefinita, i log dei messaggi del cloud privato si trovano nella seguente directory all'interno dei nodi del processore di messaggi:

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

Puoi cambiare la posizione di log predefinita modificando le proprietà nel file message-logging.properties nei processori di messaggi:

• 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é è commentato per impostazione predefinita. Per saperne di più, consulta Impostare un token attualmente con commenti.

Se vuoi archiviare i file di log in una struttura 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à precedenti e i nomi dei file assumono la forma di {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, crealo:
   > 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à appartenga all'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 riavvio

Edge per Private Cloud 4.15.07 e precedenti

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

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

Puoi cambiare la posizione di log predefinita modificando le seguenti proprietà nel file message-logging.properties sui processori dei messaggi:

• data.dir - Imposta il percorso principale per l'archiviazione dei file di log. Ad esempio, data.dir=/opt/apigee4/var/log
• log.root.dir - Se la 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à imposterebbe la directory di logging su /opt/apigee4/var/log/custom/folder/messagelog/ (nota che /messagelog viene aggiunto automaticamente).

Se lo imposti su un percorso assoluto, ad esempio log.root.dir=/opt/apigee4/var/log/messages, i log dei messaggi saranno 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 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 nei processori di messaggi. I messaggi vengono archiviati nella directory specificata dalle proprietà precedenti e i nomi dei file assumono il formato {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 suo 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 dei servizi di gestione dei log di terze parti

Il criterio MessageLogging 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 l'elemento Syslog su questo criterio di conseguenza.

Consulta la seguente documentazione per la configurazione della gestione dei log di terze parti:

• 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
  • Vedi anche questo post della community Apigee: https://community.apigee.com/questions/5226/setting-up-logging-with-sumo-logic-what-host-shou.html
  • Per un esempio completo di utilizzo di Sumo Logic come servizio di logging, vedi il seguente post della community Apigee. La soluzione utilizza un singolo criterio JavaScript per effettuare richieste POST HTTP 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>.
  Consulta anche questo post della community Apigee per ulteriori informazioni sul logging dei messaggi in Loggly: https://community.apigee.com/content/kbentry/14798/log-messages-into-loggly.html

Messaggi di errore

Questa sezione descrive i codici e i messaggi di errore restituiti e le variabili di errore impostate da Edge quando questo criterio attiva un errore. Queste informazioni sono importanti per sapere se si stanno sviluppando regole di errore per gestire gli errori. Per scoprire di più, consulta gli articoli Cosa devi sapere sugli errori relativi alle norme e Gestione degli errori.

Errori di runtime

Questi errori possono verificarsi quando il criterio viene eseguito.

Errori di deployment

Questi errori possono verificarsi quando esegui il deployment di un proxy contenente questo criterio.

Variabili di errore

Queste variabili vengono impostate quando si verifica un errore di runtime. Per maggiori informazioni, consulta la sezione Cosa devi sapere sugli errori relativi ai criteri.

Esempio di risposta di errore

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

Esempio di regola di errore

<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 del criterio.

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

Argomenti correlati

• Variabili esposte da Edge: riferimento variabili