Criterio MessageLogging

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Cosa

Il criterio MessageLogging ti consente di registrare messaggi personalizzati in Cloud Logging o syslog. Puoi utilizzare le informazioni nei log per varie attività, ad esempio per rilevare i problemi nell'ambiente di runtime dell'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 sull'utilizzo, consulta Tipi di criteri.

Esistono due modi per utilizzare il criterio di logging dei messaggi:

• L'elemento <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 maggiori informazioni sull'attivazione delle API per un progetto Google Cloud, consulta Attivare e disattivare i servizi.
• Log dell'elemento <Syslog> in syslog, un protocollo standard l'invio di messaggi di log di sistema o di evento a un server web. Per utilizzare questo metodo, devi disporre di un server syslog. In caso contrario, puoi utilizzare servizi pubblici di gestione dei log, come Splunk, Sumo Logic e Loggly. Consulta Configurare i 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>.

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:

La tabella seguente fornisce una descrizione generale degli elementi secondari di <MessageLogging>:

Esempi

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

{"{message.queryparam.key}": "{message.queryparam.value}"}

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

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

Riferimento all'elemento secondario

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

<CloudLogging>

Utilizza l'elemento <CloudLogging> per registrare i messaggi in Cloud Logging.

<Label>
    <Key>key1</Key>
    <Value>value1</Value>
</Label>

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à del l'account di servizio specificato nelle richieste in uscita a Cloud Logging. Per maggiori dettagli, consulta 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 saperne di più sui ruoli Identity and Access Management (IAM) per <CloudLogging>, consulta la Guida al controllo dell'accesso.

<Syslog>

Utilizza l'elemento <Syslog> per configurare i messaggi in cui registrare i messaggi 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.

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

&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. Viene 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 mettere i criteri MessageLogging in PostClientFlow e assicurare che vengano sempre eseguiti.

L'immagine di debug seguente mostra un criterio di registrazione dei messaggi in esecuzione nell'ambito 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à 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. In alcuni casi, un log potrebbe non essere 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 poi li scrive nella destinazione configurata. Ciascuna di destinazione ha il proprio buffer.

Se la frequenza di scrittura nel buffer aumenta oltre la frequenza di lettura, il buffer si riempie e il logging non va a buon fine. In questo caso, nel file di log potresti trovare uno dei seguenti messaggi:

• 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 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 relativo 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 di registrazione dei messaggi 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 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:

• Splunk (seleziona la versione del prodotto)
  Vedi anche questo post della community Apigee: Registrare i messaggi in Splunk
• Sumo Logic
  • Vedi anche questo post della community Apigee: Configurare la registrazione con Sumo Logic
  • Per un esempio completo che utilizza Sumo Logic come servizio di logging, consulta il seguente post della community Apigee. La soluzione utilizza un singolo criterio JavaScript per eseguire HTTP POST richieste a Sumo Logic HTTP Source Collector: Accedere a Sumo Logic utilizzando JavaScript e HTTP
• Loggly
  Quando utilizzi Loggly, <FormatMessage>true</FormatMessage> è obbligatorio in il criterio come elemento secondario dell'elemento <Syslog>.
  Per ulteriori informazioni sul logging dei messaggi in Loggly, consulta anche questo post della community di Apigee: Log dei messaggi in Loggly

Messaggi di errore

Questa sezione descrive i codici di errore e i messaggi di errore restituiti e le variabili di errore impostate da Apigee quando questo criterio attiva un errore. Queste informazioni sono importanti se stai sviluppando regole di errore per gestire gli errori. Per scoprire di più, consulta Informazioni importanti sugli errori relativi alle norme e Gestione degli errori.

Errori di runtime

Questi errori possono verificarsi durante l'esecuzione del criterio.

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, consulta Informazioni importanti 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 mancato rispetto dei criteri.

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

Argomenti correlati

• Variabili esposte da Apigee: Riferimento alle variabili di flusso