Norme di MessageLogging

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

icona delle norme

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 rintracciare i problemi nell'ambiente di runtime dell'API.

Queste norme sono estensibili e il loro utilizzo potrebbe avere implicazioni in termini di costi o di utilizzo, a seconda della licenza Apigee. Per informazioni sui tipi di criteri e sulle implicazioni di utilizzo, consulta 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 ulteriori informazioni sull'abilitazione delle API per un progetto Google Cloud, consulta Abilitazione e disabilitazione dei servizi.
  • L'elemento <Syslog> registra i messaggi in syslog, un protocollo standard per l'invio di messaggi di log di sistema o di eventi a un server specifico. Per utilizzare questo metodo, devi disporre di un server syslog. In caso contrario, puoi utilizzare servizi di gestione dei log pubblici, come Splunk, Sumo Logic e Loggly. Vedi 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.

Elemento <MessageLogging>

Definisce un criterio <MessageLogging>.

Valore predefinito Consulta la scheda Policy predefinita 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>api</ResourceType>
    </CloudLogging>
    <logLevel>ALERT</logLevel>
</MessageLogging>

Questo elemento ha i seguenti attributi comuni a tutti i criteri:

Attributo Predefinito Obbligatorio? Descrizione
name N/D Obbligatorio

Il nome interno del criterio. Il valore dell'attributo name può contenere lettere, numeri, spazi, trattini, trattini bassi e punti. Questo valore non può superare i 255 caratteri.

Se vuoi, utilizza l'elemento <DisplayName> per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.
continueOnError falso Facoltativo Imposta su false per restituire un errore quando un criterio non va a buon fine. Questo è un comportamento previsto per la maggior parte dei criteri. Imposta su true per continuare l'esecuzione del flusso anche dopo un fallimento del 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 Ritirato Questo attributo è stato ritirato.

La tabella seguente 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 syslog.

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>api</ResourceType>
    </CloudLogging>
</MessageLogging>

Questo esempio illustra l'utilizzo dei modelli di messaggi. Poiché l'elemento Message contiene le variabili del 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 sarebbe {"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 informazioni su ogni messaggio di richiesta che la tua API riceve dalle app consumer. Il valore 3f509b58 rappresenta una coppia chiave-valore specifica del servizio Loggly. Se hai un account Loggly, sostituisci la chiave Loggly. Il messaggio di log generato verrà compilato con quattro valori: l'organizzazione, il proxy API e il nome dell'ambiente associato alla transazione, insieme al valore di un parametro di query nel messaggio di richiesta. Il formato dei timestamp sarà simile a 230704-13:42:17.376, come 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 registrazione dei messaggi di terze parti tramite TLS/SSL aggiungendo il blocco <SSLInfo>.

Riferimento all'elemento secondario

Le sezioni seguenti 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 contentType, il cui valore può essere text/plain o application/json per i messaggi di testo e JSON rispettivamente. Vedi gli esempi.
Label No Etichetta da allegare al messaggio di log, se presente. Questi saranno 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 in modo che utilizzi 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, vedi Utilizzare l'autenticazione Google.

Il account di servizio che colleghi al proxy API al momento del deployment deve avere un ruolo con l'autorizzazione logging.logEntries.create. A meno che tu non abbia bisogno di un controllo più granulare, ti consigliamo di utilizzare il ruolo predefinito più inclusivo roles/logging.logWriter per ilaccount di serviziot. Per saperne di più sui ruoli Identity and Access Management (IAM) per <CloudLogging>, consulta la guida al controllo dell'accesso.

Deployment dei proxy in Apigee hybrid

Se utilizzi Apigee Hybrid, l' account di servizio runtime che crei per Apigee Hybrid deve rappresentare l'account di servizio proxy per effettuare chiamate autenticate per suo conto. Di conseguenza, il account di servizio di runtime di Apigee Hybrid deve disporre del ruolo iam.serviceAccountTokenCreator per il account di serviziont proxy.

<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, sono disponibili servizi di gestione dei log pubblici, come Splunk, Sumo Logic e Loggly. Consulta Configurazione di servizi di gestione dei log di terze parti.

Nome campo Obbligatorio? Descrizione campo
Message Sì

Il messaggio da registrare. Il messaggio ha un attributo contentType, il cui valore può essere text/plain o application/json per i messaggi di testo e JSON rispettivamente. Vedi gli esempi.
Host No Il nome host o l'indirizzo IP del server a cui deve essere inviato syslog. Se non includi questo elemento, il valore predefinito è localhost.
Port No Porta su cui è in esecuzione syslog. Se non includi questo elemento, il valore predefinito è 514.
Protocol No TCP o UDP (impostazione predefinita). Sebbene UDP sia più efficiente, il protocollo TCP garantisce la consegna del log dei messaggi al server syslog. Per l'invio di messaggi syslog tramite TLS/SSL, è supportato solo TCP.
FormatMessage No, ma <FormatMessage>true</FormatMessage> è obbligatorio per l'utilizzo con Loggly.

true o false (impostazione predefinita)

Questo elemento ti consente di controllare il formato dei contenuti generati da Apigee anteposti al messaggio. Se impostato su true, il messaggio syslog è preceduto da un numero fisso di caratteri, che ti consente di filtrare queste informazioni dai messaggi. Ecco un esempio per il formato fisso:

<14>1 2023-03-20T09:24:39.039+0000 e49cd3a9-4cf6-48a7-abb9-7ftfe4d97d00 Apigee - - - Message starts here

Le informazioni generate da Apigee includono:

  • <14> - Un punteggio di priorità (vedi il protocollo Syslog) basato sul livello di log e sul livello di funzionalità del messaggio.
  • 1 - La versione attuale di syslog.
  • Data con un offset UTC (UTC = +0000).
  • UUID del processore di messaggi.
  • "Apigee - - - "

Se è impostato su false (valore predefinito), al messaggio non vengono anteposti questi caratteri fissi.
PayloadOnly No

true o false (impostazione predefinita)

Questo elemento imposta il formato dei messaggi generati da Apigee in modo che contengano 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 è false.

Vedi FormatMessage.
DateFormat No

Una stringa di modello di formattazione da utilizzare per formattare il timestamp di ogni messaggio di log. Per impostazione predefinita, Apigee utilizza yyyy-MM-dd'T'HH:mm:ss.SSSZ. Il comportamento di questo modello è descritto nella documentazione della classe SimpleDateFormat di Java. Secondo questa definizione, yyyy nella stringa di formato verrà sostituito con un anno a 4 cifre, MM verrà sostituito con un numero di mese a 2 cifre e così via.

SSLInfo No

Consente di registrare i messaggi tramite SSL/TLS. Utilizza con l'elemento secondario <Enabled>true</Enabled>.

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 in un TargetEndpoint, inclusa l'attivazione di TLS/SSL bidirezionale, come descritto in Riferimento alla configurazione del proxy API. È supportato solo il protocollo TCP.

<logLevel>

I valori validi per l'elemento <logLevel> sono: INFO (valore predefinito), ALERT, WARN, ERROR.

Imposta un livello specifico di informazioni da includere nel log dei messaggi.

Se utilizzi l'elemento FormatMessage (impostandolo su true), l'impostazione <logLevel> influisce sul punteggio di priorità calcolato (il numero tra le parentesi angolari) nelle informazioni generate da Apigee anteposte al messaggio.

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 per due motivi:

  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 debug 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>

Apigee 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.

Apigee registra il messaggio in modo asincrono: la risposta viene restituita mentre i log sono ancora in fase di scrittura. Di conseguenza, non viene introdotta alcuna latenza nell'API bloccando i callout. Potrebbero verificarsi casi in cui un log non viene scritto senza che venga restituito un errore, ma questi eventi sono rari.

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.

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, potresti trovare uno dei seguenti messaggi nel file di log:

  • Utilizzo di <CloudLogging>: 
    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 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:

Messaggi di errore

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Cause
steps.messagelogging.StepDefinitionExecutionFailed 500 See fault string.
steps.messagelogging.InvalidGoogleCloudLogName 500 This error is thrown when the LogName does not evaluate to the valid format of projects/{project}/logs/{logid}.
steps.messagelogging.InvalidJsonMessage 500 This error is thrown when the contentType attributes value has been chosen as application/json but the actual message value is not a valid JSON string,
steps.messagelogging.TooManyPendingLoggingRequest 500 This error is thrown when there are more than 2500 pending requests that are yet to be written to Cloud Logging. The 2500 limit is for each Apigee runtime pod. For example, if the traffic is distributed over two instances of Apigee runtime pods, the effective limit is 5000 requests.
-

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Cause Fix
InvalidProtocol The deployment of the MessageLogging policy can fail with this error if the protocol specified within the <Protocol> element is not valid. The valid protocols are TCP and UDP. For sending syslog messages over TLS/SSL, only TCP is supported.
InvalidPort The deployment of the MessageLogging policy can fail with this error if the port number is not specified within the <Port> element or if it is not valid. The port number must be an integer greater than zero.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name Matches "StepDefinitionExecutionFailed"
messagelogging.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. messagelogging.ML-LogMessages.failed = true

Example error response

{  
   "fault":{
      "detail":{
         "errorcode":"steps.messagelogging.StepDefinitionExecutionFailed"
      },
      "faultstring":"Execution failed"
   }
}

Example fault rule

<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