Criterio MessageLogging

Questa pagina si applica a Apigee e Apigee ibridi.

Visualizza documentazione di Apigee Edge.

icona norme

Cosa

Il criterio MessageLogging consente di registrare messaggi personalizzati in Cloud Logging o syslog. Puoi utilizzare lo le informazioni nei log per varie attività, come rilevamento dei problemi nell'ambiente di runtime delle API.

Questo criterio è una norma estendibile e il suo utilizzo potrebbe comportare costi o di utilizzo delle applicazioni, a seconda della licenza Apigee. Per informazioni sui tipi di norme e le implicazioni per l'utilizzo, consulta Tipi di criteri.

Esistono due modi per utilizzare il criterio MessageLogging:

  • La <CloudLogging> registra i messaggi in Cloud Logging. Per utilizzare questo metodo, devi abilitare il metodo API Cloud Logging per il tuo progetto Google Cloud. Per ulteriori informazioni informazioni sull'abilitazione delle API per un progetto Google Cloud, consulta Attivazione e disattivazione dei Servizi.
  • Log dell'elemento <Syslog> in syslog, un protocollo standard l'invio di messaggi di log di sistema o di evento a un o server web. 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. Consulta Configurazione dei servizi di gestione dei log di terze parti.

Nota: non è possibile utilizzare entrambi gli elementi <CloudLogging> e ai <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 name può contenere lettere, numeri, spazi, trattini, trattini bassi e punti. Questo valore non può superare i 255 caratteri.

Facoltativamente, 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 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 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>gce_instance</ResourceType>
    </CloudLogging>
</MessageLogging>

Questo esempio illustra l'utilizzo di modelli di messaggi. Poiché l'elemento Message contiene il flusso variabili

{"{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 le informazioni su ogni messaggio di richiesta che L'API riceve dalle app consumer. Il valore 3f509b58 rappresenta una coppia chiave-valore specifiche del servizio loggly. Se disponi di un account loggly, sostituisci la chiave loggly. La il messaggio di log generato verrà compilato con quattro valori: Organization, API proxy e il nome dell'ambiente associato alla transazione, insieme al valore di una query nel messaggio di richiesta. Il formato dei timestamp sarà simile a 230704-13:42:17.376, in base al formato specificato in 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 parametro Blocco <SSLInfo>.

Riferimento elemento secondario

Le seguenti sezioni descrivono gli elementi secondari di <MessageLogging>.

<CloudLogging>

Utilizzare 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 rispettivamente per i messaggi di testo e JSON. Visualizza gli esempi.
Label No Etichetta da allegare al messaggio di log, se presente. Tali valori saranno sotto forma di una 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 Autenticazione Google. Apigee utilizzerà le credenziali corrispondenti all'identità del l'account di servizio specificato nelle richieste in uscita a Cloud Logging. Per ulteriori dettagli, vedi Utilizzare l'autenticazione Google. L'account di servizio che colleghi al proxy API al momento del deployment deve avere un ruolo con logging.logEntries.create autorizzazione. Per saperne di più sui ruoli Identity and Access Management (IAM) per <CloudLogging>, consulta la Guida al controllo dell'accesso.

&lt;Syslog&gt;

Utilizza l'elemento <Syslog> per configurare i messaggi in cui registrare syslog. Quando utilizzi <Syslog>, un proxy API inoltra i messaggi di log da Apigee a un controller server syslog. Per utilizzare questo metodo, devi disporre di un server syslog. In caso contrario, gestione log pubblici come Splunk, Sumo Logic e Loggly. vedi Configurazione dei 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 rispettivamente per i messaggi di testo e JSON. Visualizza gli esempi.
Host No Il nome host o l'indirizzo IP del server in cui syslog deve essere inviato. Se non includi questo elemento, il valore predefinito è localhost.
Port No Porta su cui è in esecuzione il syslog. Se non includi per questo elemento, il valore predefinito è 514.
Protocol No TCP o UDP (impostazione predefinita). Sebbene il protocollo UDP sia più performante, Il protocollo TCP garantisce la consegna dei log dei messaggi al server syslog. Per l'invio di syslog per i messaggi su TLS/SSL, è supportato solo il protocollo TCP.
FormatMessage No, ma il campo <FormatMessage>true</FormatMessage> è obbligatorio per utilizzarlo con Loggly.

true o false (valore predefinito)

Questo elemento consente di controllare il formato dei contenuti generati da Apigee anteposto al . Se impostato su true, il messaggio syslog è preceduto da un numero fisso di caratteri, che ti consente di escludere queste informazioni dai messaggi. Di seguito è riportato un esempio per la configurazione formato:

<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 di log e di struttura del messaggio.
  • 1 - La versione attuale di syslog.
  • Data con offset UTC (UTC = +0000).
  • UUID del processore di messaggi.
  • "Apigee - - - "

Se il criterio viene impostato su false (impostazione predefinita), il messaggio non viene anteposto a quelli corretti caratteri.
PayloadOnly No

true o false (valore predefinito)

Questo elemento imposta il formato dei messaggi generati da Apigee in modo che contenga solo il corpo dei il 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 modello di formattazione da utilizzare per formattare il timestamp di ciascun messaggio di log. Per impostazione predefinita, Apigee utilizza yyyy-MM-dd'T'HH:mm:ss.SSSZ. Il comportamento di questo modello è descritto nella documentazione Classe SimpleDateFormat di Java. In base a questa definizione, yyyy nella stringa del formato verrà sostituita con l'anno a quattro cifre, MM sostituito con un numero del mese a 2 cifre e così via.

SSLInfo No

Consente di registrare i messaggi tramite SSL/TLS. Da utilizzare con elemento secondario <Enabled>true</Enabled>.

Se non includi questo elemento o lo lasci vuoto, il valore predefinito è false (no TLS/SSL).

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

Puoi configurare il tag &lt;SSLInfo&gt; come faresti su un TargetEndpoint, inclusa l'abilitazione del protocollo TLS/SSL a due vie, come descritto in Riferimento per la configurazione dei proxy API. Solo il protocollo TCP supportati.

&lt;logLevel&gt;

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), il parametro 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 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.

La seguente immagine di debug mostra un criterio MessageLogging in esecuzione nell'ambito 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>

Apigee registra i messaggi come testo semplice e puoi configurare il logging per 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.

Apigee registra i messaggi in modo asincrono: la risposta è mentre è ancora in corso la scrittura dei log. Di conseguenza, non viene introdotta alcuna latenza alla tua API bloccando i callout. Potrebbero esserci potrebbero verificarsi casi in cui un log non viene scritto senza che venga restituito un errore, ma queste situazioni sono rari.

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 presente uno dei seguenti messaggi file:

  • Utilizzo di <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) nella message-logging.properties file.

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:

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

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