Criterio MessageLogging

Stai visualizzando la documentazione di Apigee Edge.
Vai alla sezione 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 nell'API per registrare i messaggi personalizzati in un su disco locale (per Edge solo per cloud privato) o su 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 MessageLogging.

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

Schemi

Note sull'utilizzo

Quando colleghi un criterio MessageLogging a un flusso di proxy API, valuta la possibilità di inserirlo nel Risposta ProxyEndpoint, in un flusso speciale chiamato PostClientFlow. PostClientFlow esegue Dopo che la risposta viene inviata al cliente richiedente, per garantire la disponibilità di tutte le metriche 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 mettere i criteri MessageLogging in PostClientFlow e assicurare che vengano sempre eseguiti.

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

In questo esempio, il criterio di verifica della chiave API ha causato l'errore a causa di un errore non valido chiave.

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 perimetrali sono come testo semplice e puoi configurare il logging in modo da includere variabili, 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. Messaggio dei log perimetrali in modo asincrono, vale a dire che non viene introdotta nessuna latenza che potrebbe essere causata dal blocco dei callout alla tua API.

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

Se la velocità di scrittura nel buffer aumenta oltre la velocità di lettura, il buffer supera e il logging non andrà a buon fine. In questo caso, nel log potrebbe essere visualizzato un messaggio contenente quanto segue. file:

Log message size exceeded. Increase the max message size setting

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

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

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: il messaggio di risposta in Edge non sono disponibili dal flusso di errori. Inoltre, queste variabili non sono disponibile in PostClientFlow se il flusso precedente era il flusso di errore. Se vuoi registrare la risposta informazioni da PostClientFlow, utilizza l'oggetto message. Puoi utilizza questo oggetto per ottenere le intestazioni e altre informazioni dalla risposta, che siano o meno è stato un errore. Vedi Messaggio variabili per ulteriori informazioni e per un esempio.

Controllo del messaggio di log timestamp in Edge per il cloud privato

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

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

È possibile eseguire l'override di questa impostazione predefinita a livello di sistema per le destinazioni syslog utilizzando Elemento DateFormat. Il comportamento di questo modello è descritto nel 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 il 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 usare conf_system_apigee.syslogger.dateFormat sul processore di messaggi periferici per controllare quel formato. Ad esempio, la modifica del messaggio formato su:

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'elemento 'apigee' utente:
   > 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 su Nodi processore:

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

Puoi cambiare la posizione predefinita per i log modificando le proprietà nella message-logging.properties sui 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 la imposti su un percorso assoluto, ad esempio conf/message-logging.properties+log.root.dir=/opt/apigee/var/log/messages, messaggio I log 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. Consulta la sezione Impostazione di attualmente con commenti.

Se desideri 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 le proprietà di cui sopra e i nomi dei file assumono 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, 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'elemento 'apigee' utente:
   > 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 all'interno del messaggio processori:

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

Puoi cambiare la posizione predefinita per i log modificando le seguenti proprietà nella message-logging.properties sui processori dei messaggi:

• data.dir - Imposta la radice per l'archiviazione dei file di log. Ad esempio, data.dir=/opt/apigee4/var/log
• log.root.dir: se imposti in un percorso relativo, come 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 verranno archiviati in /opt/apigee4/var/log/messages/messagelog/. Un percorso assoluto in log.root.dir ha la precedenza su data.dir.

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

Valori predefiniti per le variabili in 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 il parametro Attributo defaultVariableValue nell'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 alla gestione dei log di terze parti come Splunk, Sumo Logic e Loggly. Se vuoi inviare syslog a uno di questi consulta la documentazione di quel servizio per configurare l'host, la porta e il protocollo quindi imposta di conseguenza l'elemento Syslog su questo criterio.

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

• Splunk (seleziona la versione del prodotto)
  Vedi anche questo post della community Apigee: https://community.apigee.com/content/kbentry/13298/log-messages-into-splunk.html
• Sumo Logica
  .
  • Vedi 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 di utilizzo di Sumo Logic come servizio di logging, consulta quanto segue Post della community Apigee. La soluzione utilizza un singolo criterio JavaScript per eseguire HTTP POST richieste 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 in il criterio come elemento secondario dell'elemento <Syslog>.
  Vedi 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, nonché le variabili di errore impostate da Edge quando questo criterio attiva un errore. È importante sapere se stai sviluppando regole di errore per per gestire gli errori. Per saperne di più, consulta Cosa devi sapere sugli errori relativi ai criteri e sulla gestione di errore.

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 ulteriori informazioni, vedi Cosa devi sapere sugli errori relativi alle norme.

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