Norme di MessageLogging

Stai visualizzando la documentazione di Apigee Edge.
Consulta la documentazione di Apigee X. info

Cosa

Uno dei modi migliori per individuare i problemi nell'ambiente di runtime dell'API è registrare i messaggi. Puoi collegare e configurare una policy MessageLogging alla tua API per registrare messaggi personalizzati su un disco locale (solo Edge for Private Cloud) 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 policy MessageLogging.

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

<FileName>mylog.log</FileName>

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

Schemi

Note sull'utilizzo

Quando colleghi una policy MessageLogging a un flusso di proxy API, valuta la possibilità di inserirla 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 Riferimento per la configurazione dei proxy API.

PostClientFlow è speciale in due modi:

1. È stato 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 dall'esito positivo o negativo del proxy, puoi inserire i criteri MessageLogging in PostClientFlow e avere la garanzia che vengano sempre eseguiti.

L'immagine di Trace seguente mostra una policy MessageLogging in esecuzione come parte 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à dell'utente nella richiesta, l'indirizzo IP di origine da cui è stata inviata la richiesta e così via. I log edge inviano messaggi in modo asincrono, il che significa che non viene introdotta alcuna latenza che potrebbe essere causata da callout di blocco 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 li scrive nella destinazione che configuri. Ogni destinazione ha il proprio buffer.

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

Se la frequenza di scrittura nel buffer aumenta oltre la frequenza di lettura, il buffer si riempie e la registrazione non riesce. 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 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 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 nel flusso di errori. 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 intestazioni e altre informazioni dalla risposta, indipendentemente dal fatto che si sia verificato un errore. Per ulteriori informazioni ed esempi, consulta la sezione Variabili dei messaggi.

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

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

È possibile eseguire l'override di questo valore predefinito a livello di sistema 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 a 4 cifre, MM con un numero di mese a 2 cifre e così via. Il formato precedente potrebbe generare una stringa di questo tipo:

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

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

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

..sostituendo i trattini con le barre e abbreviando 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, 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 restart

Percorso 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 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 sui 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 imposti questo valore 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 vengono 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 Impostazione di un token attualmente commentato.

Se vuoi archiviare i file di log in una struttura di file piatta 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 hanno 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à 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 restart

Edge for Private Cloud 4.15.07 e versioni precedenti

Per impostazione predefinita, i log dei messaggi si trovano nel seguente percorso sui processori dei 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 sui processori di messaggi:

• data.dir: imposta il percorso radice per l'archiviazione dei file di log. Ad esempio, data.dir=/opt/apigee4/var/log
• log.root.dir: se imposti questo valore 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 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 piatta 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 vengono archiviati nella directory specificata dalle proprietà precedenti e i nomi dei file hanno 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 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 in questo criterio di conseguenza.

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: Log messages into Splunk
• Sumo Logic
  • Consulta anche questo post della community Apigee: Configurazione della registrazione con Sumo Logic, quale host devo utilizzare?
  • Per un esempio completo che utilizza Sumo Logic come servizio di logging, consulta il seguente post della community Apigee. La soluzione utilizza un'unica norma JavaScript per effettuare richieste HTTP POST al raccoglitore di origini HTTP di Sumo Logic: Logging in Sumo Logic utilizzando JavaScript e HTTP
• Loggly
  Quando utilizzi Loggly, <FormatMessage>true</FormatMessage> è obbligatorio nelle norme come elemento secondario dell'elemento <Syslog>.
  Per ulteriori informazioni sulla registrazione dei messaggi in Loggly, consulta anche questo post della community Apigee: Registrare i messaggi in Loggly

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 della policy.

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

Argomenti correlati

• Variabili esposte da Edge: riferimento alle variabili