Questa pagina si applica a Apigee e Apigee ibrido.
Visualizza la documentazione di Apigee Edge.
Cosa
Il criterio MessageLogging consente di registrare messaggi personalizzati in Cloud Logging o syslog. Puoi utilizzare le informazioni nei log per varie attività, ad esempio per individuare i problemi nell'ambiente di runtime delle API.
Questo criterio è un criterio estendibile e il suo utilizzo potrebbe avere implicazioni in termini di costi o utilizzo, a seconda della licenza Apigee. Per informazioni sui tipi di criteri e sulle implicazioni per l'utilizzo, consulta la pagina Tipi di criteri.
Esistono due modi per utilizzare il criterio MessageLogging:
- L'elemento
<CloudLogging>
registra i messaggi in Cloud Logging. Per utilizzare questo metodo, devi abilitare le API Cloud Logging per il tuo progetto Google Cloud. Per saperne di più sull'abilitazione delle API per un progetto Google Cloud, consulta Attivazione e disattivazione dei servizi. - L'elemento
<Syslog>
registra i messaggi in syslog, un protocollo standard per l'invio di messaggi di log o di evento di sistema a un server specifico. Per utilizzare questo metodo, devi disporre di un server syslog. In caso contrario, puoi utilizzare i servizi di gestione dei log pubblici, come Splunk, Sumo Logic e Loggly. Consulta Configurazione dei servizi di gestione dei log di terze parti.
Nota: non puoi utilizzare sia l'elemento <CloudLogging>
sia l'elemento
<Syslog>
nello stesso criterio.
<MessageLogging>
elemento
Definisce un criterio <MessageLogging>
.
Valore predefinito | Consulta la scheda Criterio predefinito di seguito |
Obbligatorio? | Obbligatorio |
Tipo | TIPO |
Elemento principale | n/a |
Elementi secondari | <CloudLogging> <Syslog> <logLevel> |
L'elemento <MessageLogging>
utilizza la seguente sintassi:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <MessageLogging continueOnError="false" enabled="true" name="Message-Logging-1"> <DisplayName>Message Logging-1</DisplayName> <Syslog> <!-- Note: You cannot use both the <Syslog> element and the <CloudLogging> element in the same policy. --> <Message>Some message for syslog</Message> <Host>localhost</Host> <Port>514</Port> </Syslog> <CloudLogging> <!-- Note: You cannot use both the <CloudLogging> and the <Syslog> element in the same policy. --> <LogName>projects/{organization.name}/logs/{log.id}</LogName> <Message contentType="application/json">{"{message.queryparam.key}": "{message.queryparam.value}"}</Message> <Labels> <Label> <Key>key1</Key> <Value>value1</Value> </Label> <Label> <Key>key2</Key> <Value>value2</Value> </Label> </Labels> <ResourceType>gce_instance</ResourceType> </CloudLogging> <logLevel>ALERT</logLevel> </MessageLogging>
Questo elemento ha i seguenti attributi comuni a tutti i criteri:
Attributo | Predefinito | Obbligatorio? | Descrizione |
---|---|---|---|
name |
N/A | Obbligatorio |
Il nome interno del criterio. Il valore dell'attributo Facoltativamente, utilizza l'elemento |
continueOnError |
falso | Facoltativo | Imposta su false per restituire un errore in caso di errore del criterio. Questo è un comportamento previsto per
la maggior parte dei criteri. Imposta su true per continuare l'esecuzione del flusso anche dopo un errore nel criterio. Vedi anche:
|
enabled |
true | Facoltativo | Imposta su true per applicare il criterio. Imposta su false per disattivare il
criterio. Il criterio non verrà applicato anche se rimane collegato a un flusso. |
async |
falso | Deprecato | Questo attributo è stato ritirato. |
La seguente tabella fornisce una descrizione generale degli elementi secondari di
<MessageLogging>
:
Nome campo | Descrizione campo |
---|---|
CloudLogging |
Configura i messaggi da registrare in Cloud Logging. |
Syslog |
Configura i messaggi da registrare in |
Esempi
CloudLogging
<MessageLogging name="LogToCloudLogging"> <CloudLogging> <LogName>projects/{organization.name}/logs/{log.id}</LogName> <Message contentType="application/json">{"{message.queryparam.key}": "{message.queryparam.value}"}</Message> <Labels> <Label> <Key>key1</Key> <Value>value1</Value> </Label> <Label> <Key>key2</Key> <Value>value2</Value> </Label> </Labels> <ResourceType>gce_instance</ResourceType> </CloudLogging> </MessageLogging>
Questo esempio illustra l'utilizzo dei
modelli di messaggio. Poiché l'elemento Message
contiene le variabili
di flusso
{"{message.queryparam.key}": "{message.queryparam.value}"}
Quando qualcuno chiama il proxy con i valori
message.queryparam.key = "fruit"
e
message.queryparam.value = "apple"
, la voce di log risultante sarà
{"fruit": "apple"}
.
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>yyMMdd-HH:mm:ss.SSS</DateFormat> </Syslog> <logLevel>ALERT</logLevel> </MessageLogging>
In questo esempio, supponiamo che tu debba 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. Il formato dei timestamp sarà simile a 230704-13:42:17.376
, in base al formato specificato nell'elemento DateFormat
.
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> </Syslog> <logLevel>WARN</logLevel> </MessageLogging>
Puoi inviare messaggi a provider di logging dei messaggi di terze parti tramite TLS/SSL aggiungendo il blocco <SSLInfo>
.
Riferimento elemento secondario
Le seguenti sezioni descrivono gli elementi secondari di <MessageLogging>.
<CloudLogging>
Utilizza l'elemento <CloudLogging>
per registrare i messaggi
in Cloud Logging.
Nome campo | Obbligatorio? | Descrizione |
---|---|---|
LogName |
Sì | Nome del log. Il nome del log deve essere nel formato
projects/{PROJECT_ID}/logs/{LOG_ID} .
Puoi utilizzare le variabili al posto di {PROJECT_ID} e {LOG_ID} . |
Message |
Sì |
Il messaggio da registrare. Il messaggio ha un attributo |
Label |
No | Etichetta da allegare al messaggio di log, se presente.
Si presentano sotto forma di coppia chiave-valore come la seguente:
<Label> <Key>key1</Key> <Value>value1</Value> </Label> |
ResourceType |
No (impostazione predefinita: globale) | Rappresenta la risorsa monitorata che genera i log. |
Autenticazione per Cloud Logging
Per utilizzare l'elemento <CloudLogging>
, devi eseguire il deployment del proxy API per utilizzare
l'autenticazione Google. Apigee utilizzerà le credenziali corrispondenti all'identità
dell'account di servizio specificato nelle richieste in uscita a Cloud Logging. Per maggiori dettagli, consulta la sezione Utilizzare l'autenticazione Google.
L'account di servizio che colleghi al proxy API al momento del deployment deve avere un ruolo con l'autorizzazione
logging.logEntries.create
. Per ulteriori informazioni sui ruoli IAM (Identity and Access Management) per <CloudLogging>
, consulta la guida al controllo dell'accesso.
<Syslog>
Utilizza l'elemento <Syslog>
per configurare i messaggi da registrare in
syslog
.
Quando utilizzi <Syslog>
, un proxy API inoltra i messaggi di log da Apigee a un server syslog remoto. Per utilizzare questo metodo, devi disporre di un server syslog. In caso contrario, saranno disponibili i servizi di gestione dei log pubblici come Splunk, Sumo Logic e Loggly. Consulta Configurare i servizi di gestione dei log di terze parti.
Nome campo | Obbligatorio? | Descrizione campo |
---|---|---|
Message |
Sì |
Il messaggio da registrare. Il messaggio ha un attributo |
Host |
No | 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 |
No | Porta su cui è in esecuzione il syslog. Se non includi questo elemento, il valore predefinito è 514. |
Protocol |
No | 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 |
No, ma è richiesto <FormatMessage>true</FormatMessage> per l'utilizzo con Loggly. |
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 |
No |
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 |
No |
Una stringa modello di formattazione da utilizzare per formattare il timestamp di ciascun messaggio di log.
Per impostazione predefinita, Apigee utilizza |
SSLInfo |
No |
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>
I valori validi per l'elemento <logLevel>
sono: INFO
(predefinito), ALERT
, WARN
, ERROR
.
Imposta un livello specifico di informazioni da includere nel log dei messaggi.
Se utilizzi l'elemento FormatMessage (impostato su true), l'impostazione <logLevel>
influisce sul punteggio di priorità calcolato (il numero tra parentesi angolari) nelle informazioni generate da Apigee anteposte al messaggio.
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 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 debug seguente mostra un criterio MessageLogging in esecuzione come parte di PostClientFlow, dopo l'esecuzione della regola DefaultFaultRule:
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>
Apigee registra i messaggi come testo semplice e puoi configurare il logging in modo da includere variabili, come 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.
Apigee registra i messaggi in modo asincrono: la risposta viene restituita durante la scrittura dei log. Di conseguenza, i callout non vengono introdotti nell'API. Potrebbero verificarsi casi in cui un log non viene scritto senza che venga restituito un errore, ma si tratta di eventi rari.
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 presente uno dei seguenti messaggi:
- In uso:
<CloudLoggingg>
:steps.messagelogging.TooManyPendingLoggingRequest
- Utilizzo di
<Syslog>
:Log message size exceeded. Increase the max message size setting
Aumenta la proprietà max.log.message.size.in.kb
(valore predefinito = 128 kB) nel
file message-logging.properties
.
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: Log messages into Splunk -
Sumo
Logic
- Leggi anche questo post della community Apigee: Configurazione del logging con Sumo Logic
- 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: Logging to Sumo Logic utilizzando JavaScript e HTTP
- Loggly
Quando utilizzi 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 in Loggly: Registrare i messaggi in Loggly
Messaggi di errore
Questa sezione descrive i codici e i messaggi di errore che vengono restituiti e le variabili di errore impostate da Apigee 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. |
steps.messagelogging.InvalidGoogleCloudLogName |
500 |
Questo errore viene generato quando LogName non restituisce il formato valido di projects/{project}/logs/{logid}. |
steps.messagelogging.InvalidJsonMessage |
500 |
Questo errore viene visualizzato quando il valore dell'attributo contentType è stato scelto come application/json , ma il valore effettivo del messaggio non è una stringa JSON valida. |
steps.messagelogging.TooManyPendingLoggingRequest |
500 |
Questo errore viene generato quando sono presenti più di 2500 richieste in attesa ancora da scritte in Cloud Logging. Il limite di 2500 è per ogni pod di runtime Apigee. Ad esempio, se il traffico viene distribuito su due istanze dei pod di runtime Apigee, il limite effettivo è di 5000 richieste. |
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 Apigee: riferimento variabili di flusso