Criterio MessageLogging

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

Cosa

Uno dei modi migliori per tenere traccia dei problemi nell'ambiente di runtime delle API è registrare i messaggi. Puoi collegare e configurare un criterio MessageLogging sulla tua API per registrare i messaggi personalizzati su un disco locale (solo Edge per Cloud privato) o su SysLog.

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>

Riferimento elemento

Utilizza i seguenti elementi per configurare il tipo di criterio MessageLogging.

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

Schemi

Note sull'utilizzo

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

PostClientFlow è speciale per due motivi:

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 dal fatto che il proxy abbia esito positivo o negativo, puoi inserire i criteri di MessageLogging in PostClientFlow per avere la certezza che vengano sempre eseguiti.

La seguente immagine di traccia mostra un criterio MessageLogging eseguito come parte di PostClientFlow, dopo l'esecuzione di defaultFaultRule:

In questo esempio, il criterio di verifica della 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 il logging in modo da includere variabili come la data e l'ora in cui la richiesta o la risposta è stata ricevuta, 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 alcuna 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 e poi li scrive nella destinazione configurata. Ogni destinazione ha il proprio buffer.

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

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 il cloud privato 4.16.01 e versioni successive, imposta la proprietà conf_message-logging_max.log.message.size.in.kb nel file /opt/apigee/customer/application/message-processor.properties e riavvia il processore di messaggi.

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 sulle risposte di 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 un errore. Per ulteriori informazioni e un esempio, consulta Variabili messaggio.

Controllo del timestamp dei messaggi di log in Edge per il cloud privato

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 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 verrà sostituito con un numero di mesi a due cifre e così via. Il formato riportato sopra potrebbe generare una stringa nel seguente formato:

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

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

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

..sostituendo i trattini con barre e accorciandoli a un 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, crealo:
   > vi /opt/apigee/customer/application/message-processor.properties
2. Imposta le proprietà in base alle tue esigenze:
   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. Riavvia il processore di messaggi Edge:
   > /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

Posizione del file di log in Edge per il cloud privato

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 sui 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 del 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é è commentata per impostazione predefinita. Per ulteriori informazioni, consulta la sezione Impostazione di un token attualmente commentato.

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 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 il formato {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à 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 landscape

Edge per Private Cloud 4.15.07 e versioni precedenti

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

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

Puoi cambiare la posizione del 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 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à imposterebbe la directory di logging su /opt/apigee4/var/log/custom/folder/messagelog/ (tieni presente 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 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 sui processori di messaggi. I messaggi sono archiviati nella directory specificata dalle proprietà riportate sopra 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 nell'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 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 host, porta e 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
  • Consulta 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 in cui viene utilizzato Sumo Logic come servizio di logging, vedi il seguente post della community Apigee. La soluzione utilizza un singolo criterio JavaScript per effettuare richieste HTTP POST al raccoglitore di origini HTTP Sumo Logic: https://community.apigee.com/articles/32286/logging-to-sumo-logic-using-javascript-and-http.html
• Loggly
  Quando si utilizza Loggly, <FormatMessage>true</FormatMessage> è obbligatorio nel criterio come elemento secondario dell'elemento <Syslog>.
  Leggi anche questo post della community Apigee per ulteriori informazioni sul logging dei messaggi a 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 alle variabili