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
Syslog
<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>
Un uso comune del tipo di criterio MessageLogging è l'accesso a un account syslog. Se configurato per syslog, un proxy API inoltrerà i messaggi di log da Apigee Edge a un server syslog remoto. Un server syslog deve essere già disponibile. In caso contrario, saranno disponibili i servizi di gestione dei log pubblici, come Splunk, Sumo Logic e Loggly. Consulta Configurazione dei servizi di gestione dei log di terze parti.
Ad esempio, immagina di dover registrare le informazioni su ogni messaggio di richiesta che l'API riceve dalle app consumer. Il valore 3f509b58
rappresenta un valore chiave specifico del servizio loggly. Se disponi di un account loggly, sostituisci la chiave loggly. Il messaggio di log generato verrà compilato con quattro valori: organizzazione, proxy API e nome dell'ambiente associati alla transazione, insieme al valore di un parametro di query nel messaggio della richiesta.
Se disponi di un deployment Edge per il cloud privato, puoi anche scrivere messaggi di log in un file.
SysLog su TLS/SSL
<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>
Puoi inviare messaggi a provider di logging dei messaggi di terze parti tramite TLS/SSL aggiungendo il blocco <SSLInfo>
.
Rotazione file: dimensioni
<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>
Rotazione dei file basata sulle sue dimensioni.
Rotazione file: data e ora
<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>
Rotazione dei file in base all'ora.
Rotazione file: ora e dimensione
<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>
Rotazione dei file in base a ora e dimensioni.
Abilitato per lo streaming
<MessageLogging name="LogPolicy"> <File> .... .... </File> <BufferMessage>true</BufferMessage> </MessageLogging>
Logging dei messaggi abilitato per lo streaming
Riferimento elemento
Utilizza i seguenti elementi per configurare il tipo di criterio MessageLogging.
Nome campo | Descrizione del campo | |
---|---|---|
Destinazione file locale. Il logging dei file è supportato solo nei deployment Edge per il cloud privato. Per informazioni sulla posizione in cui vengono archiviati i file, vedi Posizione dei file di log in Edge per Private Cloud. |
Message |
Crea il messaggio da inviare al file di log, combinando testo e variabili per acquisire le informazioni desiderate. Visualizza gli esempi. |
FileName |
Nome del file di log in cui viene registrato il messaggio. | |
FileRotationOptions |
||
rotateFileOnStartup |
Attributo. Valori validi: Se il criterio viene impostato su true, il file di log viene ruotato a ogni riavvio del motore di messaggistica. |
|
FileRotationType |
Specifica il criterio di rotazione (size o time ) di un file di log. |
|
MaxFileSizeInMB |
(Se selezioni size come tipo di rotazione)
Specifica le dimensioni di un file di log che attiva lo spostamento dei messaggi di log da parte del server in un
file separato. Una volta che il file di log raggiunge la dimensione specificata, il server rinomina il file di log attuale. |
|
RotationFrequency |
(alla selezione di time come tipo di rotazione)
Specifica per quanto tempo il server attiva lo spostamento dei messaggi di log in un file
separato. Una volta trascorso l'intervallo specificato, il file di log corrente viene rinominato. |
|
MaxFilesToRetain |
Specifica il numero massimo di file da conservare nel contesto delle impostazioni di rotazione. Il valore predefinito è 8. Se specifichi zero (0), i file di log vengono conservati per un periodo indeterminato, ma in base alle tue impostazioni di rotazione dei file, anche se nessuno dei file viene eliminato o rinominato. Pertanto, per evitare futuri errori di esaurimento del disco, imposta il valore su un valore maggiore di zero o implementa un normale sistema automatizzato di eliminazione o archiviazione dei file di log conservati più vecchi. |
|
BufferMessage |
Se è abilitato il flusso HTTP per il proxy, i messaggi di richiesta/risposta non vengono inseriti nel buffer. Se vuoi registrare contenuti che richiedono l'analisi del messaggio di flusso, imposta BufferMessage su true. Per un esempio, consulta la scheda di esempio "Abilitato per lo streaming". Valore predefinito: false |
|
Una destinazione syslog. Per inviare syslog a Splunk, Sumo Logic o Loggly, consulta Configurare i servizi di gestione dei log di terze parti. |
Message |
Crea il messaggio da inviare al syslog, combinando testo e variabili per acquisire le informazioni desiderate. Visualizza gli esempi. Nota: le variabili di risposta non saranno disponibili in PostClientFlow dopo un flusso di errori. Utilizza le variabili di messaggio per registrare le informazioni di risposta sia per le situazioni di errore che per quelle con esito positivo. Vedi anche Note sull'utilizzo. |
Host |
Il nome host o l'indirizzo IP del server a cui deve essere inviato il syslog. Se non includi questo elemento, il valore predefinito è localhost. | |
Port |
Porta su cui è in esecuzione il syslog. Se non includi questo elemento, il valore predefinito è 514. | |
Protocol |
TCP o UDP (impostazione predefinita). Nonostante le prestazioni migliori del protocollo UDP, il protocollo TCP garantisce la consegna dei log dei messaggi al server syslog. Per l'invio di messaggi syslog tramite TLS/SSL, è supportato solo TCP. | |
FormatMessage |
Facoltativo, ma è obbligatorio Questo elemento consente di controllare il formato dei contenuti generati da Apigee anteposti al messaggio. Se il criterio è impostato su true, il messaggio syslog è preceduto da un numero fisso di caratteri, così puoi escludere queste informazioni dai messaggi. Ecco un esempio per il formato fisso:
Le informazioni generate da Apigee includono:
Se il criterio viene impostato su false (impostazione predefinita), il messaggio non viene anteposto ai caratteri fissi. |
|
PayloadOnly |
Questo elemento imposta il formato dei messaggi generati da Apigee in modo che contenga solo il corpo del messaggio syslog, senza i caratteri anteposti specificati da FormatMessage. Se non includi questo elemento o lo lasci vuoto, il valore predefinito è Vedi FormatMessage. |
|
DateFormat |
Campo facoltativo. Una stringa modello di formattazione da utilizzare per formattare il timestamp di ciascun messaggio di log.
Per impostazione predefinita, Apigee utilizza |
|
SSLInfo |
Consente di registrare i messaggi tramite SSL/TLS. Da utilizzare con l'elemento secondario Se non includi questo elemento o lo lasci vuoto, il valore predefinito è false (nessun TLS/SSL). <SSLInfo> <Enabled>true</Enabled> </SSLInfo> Puoi configurare il tag <SSLInfo> come faresti su un TargetEndpoint, compresa l'abilitazione del protocollo TLS/SSL a due vie, come descritto in Riferimento alla configurazione del proxy API. È supportato solo il protocollo TCP. |
|
logLevel |
Campo facoltativo. Valori validi: Imposta un livello specifico di informazioni da includere nel log dei messaggi. Se utilizzi l'elemento |
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:
- È stata eseguita solo come parte del flusso di risposta.
- È 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:
- Apri il file message-processor.properties in un editor. Se il file non esiste, crealo:
> vi /opt/apigee/customer/application/message-processor.properties - Imposta le proprietà come preferisci:
conf_system_apigee.syslogger.dateFormat=yy/MM/dd'T'HH:mm:ss.SSSZ - Salva le modifiche.
- Assicurati che il file delle proprietà appartenga all'utente 'apigee':
> chown apigee:apigee /opt/apigee/customer/application/message-processor.properties - 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 esempioconf/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 subin_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à:
- Apri il file message-processor.properties in un editor. Se il file non esiste, crealo:
> vi /opt/apigee/customer/application/message-processor.properties - Imposta le proprietà come preferisci:
conf/message-logging.properties+log.root.dir=/opt/apigee/var/log/messages - Salva le modifiche.
- Assicurati che il file delle proprietà appartenga all'utente 'apigee':
> chown apigee:apigee /opt/apigee/customer/application/message-processor.properties - 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.
Codice di errore | Stato HTTP | Causa |
---|---|---|
steps.messagelogging.StepDefinitionExecutionFailed |
500 | Vedi stringa di errore. |
Errori di deployment
Questi errori possono verificarsi quando esegui il deployment di un proxy contenente questo criterio.
Nome errore | Causa | Correggi |
---|---|---|
InvalidProtocol |
Il deployment del criterio MessageLogging può non riuscire con questo errore se il protocollo specificato nell'elemento <Protocol> non è valido. I protocolli validi sono TCP e UDP.
Per l'invio di messaggi syslog su TLS/SSL è supportato solo il protocollo TCP. |
build |
InvalidPort |
Il deployment del criterio MessageLogging può non riuscire con questo errore se il numero di porta non è specificato nell'elemento <Port> o se non è valido. Il numero di porta deve essere un numero intero maggiore di zero. |
build |
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.
Variabili | Dove | Esempio |
---|---|---|
fault.name="fault_name" |
fault_name è il nome dell'errore, come indicato nella tabella Errori di runtime riportata sopra. Il nome del guasto è l'ultima parte del codice di errore. | fault.name Matches "StepDefinitionExecutionFailed" |
messagelogging.policy_name.failed |
policy_name è il nome specificato dall'utente del criterio che ha generato l'errore. | messagelogging.ML-LogMessages.failed = true |
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