Norme di TraceCapture

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

icona delle norme

Panoramica

Il criterio TraceCapture ti consente di aggiungere variabili aggiuntive ai dati di traccia del runtime Apigee. Se hai abilitato il tracciamento distribuito per il runtime Apigee, il runtime traccia per impostazione predefinita un insieme di variabili predefinite. Per ulteriori informazioni, vedi Variabili di traccia predefinite nel report di tracciamento. Tuttavia, se vuoi che il runtime Apigee monitori flussi, criteri o variabili personalizzate aggiuntivi, utilizza il criterio TraceCapture. Puoi utilizzare questo criterio nel flusso di richiesta o di risposta. Nel report sul monitoraggio distribuito, puoi visualizzare le variabili aggiunte dal criterio TraceCapture nell'intervallo TraceCaptureExecution.

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 criteri e sulle implicazioni per l'utilizzo, consulta Tipi di criteri.

<TraceCapture>

Definisce il criterio Trace Capture.

Valore predefinito N/D
Obbligatorio? Obbligatorio
Tipo Tipo complesso
Elemento principale N/D
Elementi secondari <DisplayName>
<IgnoreUnresolvedVariables>
<ThrowExceptionOnLimit>
<Variables>

La sintassi dell'elemento <TraceCapture> è la seguente:

Sintassi

<?xml version="1.0" encoding="UTF-8"?>
<TraceCapture continueOnError="true" enabled="true" name="DistributedTraceCapture-1">
    <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
    <Variables>
        <Variable name="TRACE_VARIABLE_NAME" ref="FLOW_VARIABLE_NAME">DEFAULT_VALUE</Variable>
        <Variable name="TRACE_VARIABLE_NAME" ref="FLOW_VARIABLE_NAME">DEFAULT_VALUE</Variable>
    </Variables>
    <IgnoreUnresolvedVariables>BOOLEAN_VALUE</IgnoreUnresolvedVariables>
    <ThrowExceptionOnLimit>BOOLEAN_VALUE</ThrowExceptionOnLimit>
</TraceCapture>

Esempio

L'esempio seguente mostra la definizione del criterio Trace Capture:

<?xml version="1.0" encoding="UTF-8"?>
<TraceCapture continueOnError="true" enabled="true" name="DistributedTraceCapture-1">
    <DisplayName>Distributed-Trace-Capture-Policy-1</DisplayName>
    <Variables>
        <Variable name="trace-variable-1" ref="flow-variable-1">default-val-1</Variable>
        <Variable name="trace-variable-2" ref="flow-variable-2">default-val-2</Variable>
    </Variables>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <ThrowExceptionOnLimit>false</ThrowExceptionOnLimit>
</TraceCapture>

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 seguente tabella fornisce una descrizione generale degli elementi secondari di <TraceCapture>:

Elemento secondario Obbligatorio? Descrizione
<DisplayName> Facoltativo Specifica un nome personalizzato per il criterio.
<Variables> Facoltativo Specifica l'elenco di variabili da tracciare.
<IgnoreUnresolvedVariables> Facoltativo Specifica se l'elaborazione si interrompe quando viene rilevata una variabile non risolta.
<ThrowExceptionOnLimit> Facoltativo Specifica se una variabile deve essere troncata se le sue dimensioni superano il limite di 256 byte.
Altri elementi secondari
<MergeBehavior> Facoltativo Specifica il comportamento di unione per i messaggi di risposta.

Riferimento all'elemento secondario

In questa sezione vengono descritti gli elementi secondari di <TraceCapture>.

<DisplayName>

Da utilizzare insieme all'attributo name per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso e più naturale.

L'elemento <DisplayName> è comune a tutti i criteri.

Valore predefinito N/D
Obbligatorio? Facoltativo. Se ometti <DisplayName>, viene utilizzato il valore dell'attributo name del criterio.
Tipo Stringa
Elemento principale <PolicyElement>
Elementi secondari Nessuno

La sintassi dell'elemento <DisplayName> è la seguente:

Sintassi

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

Esempio

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

L'elemento <DisplayName> non ha attributi o elementi secondari.

<Variables>

Specifica l'elenco di variabili da tracciare.

Valore predefinito N/D
Obbligatorio? Obbligatorio
Tipo Tipo complesso
Elemento principale <TraceCapture>
Elementi secondari <Variable>

La sintassi dell'elemento <Variables> è la seguente:

Sintassi

<Variables>
    <Variable name="TRACE_VARIABLE_NAME" ref="FLOW_VARIABLE_NAME">DEFAULT_VALUE</Variable>
    <Variable name="TRACE_VARIABLE_NAME" ref="FLOW_VARIABLE_NAME">DEFAULT_VALUE</Variable>
</Variables>

Esempio

L'esempio seguente traccia le variabili di flusso flow-variable-1 e flow-variable-2:

<Variables>
    <Variable name="trace-variable-1" ref="flow-variable-1">default-val-1</Variable>
    <Variable name="trace-variable-2" ref="flow-variable-2">default-val-2</Variable>
</Variables>

<Variable>

Specifica le variabili da aggiungere nei dati di traccia.

Valore predefinito N/D
Obbligatorio? Obbligatorio
Tipo Tipo complesso
Elemento principale <Variables>
Elementi secondari Nessuno

La sintassi dell'elemento <Variable> è la seguente:

Sintassi
<Variable name="TRACE_VARIABLE_NAME" ref="FLOW_VARIABLE_NAME">DEFAULT_VALUE</Variable>
Esempio

L'esempio seguente imposta la variabile di traccia trace-variable-1 su valore della variabile di flusso flow-variable-1:

<Variable name="trace-variable-1" ref="flow-variable-1">default-val-1</Variable>

Se la variabile di flusso flow-variable-1 non è disponibile, trace-variable-1 viene impostato sul valore predefinito default-val-1.

Nella tabella seguente vengono descritti gli attributi di <Variable>:

Attributo Obbligatorio? Tipo Descrizione
name Obbligatorio Stringa Un nome che fa riferimento ai dati raccolti per la variabile specificata. Questo nome sarà visibili nel report di tracciamento distribuito.
ref Obbligatorio Stringa La variabile per la quale stai raccogliendo i dati traccia. Questa variabile può essere un flusso variabile predefinita da Apigee o da una variabile personalizzata nel proxy API.

<IgnoreUnresolvedVariables>

Determina se l'elaborazione si interrompe quando viene rilevata una variabile non risolta.

Valore predefinito N/D
Obbligatorio? Facoltativo
Tipo Booleano
Elemento principale <TraceCapture>
Elementi secondari Nessuno

Imposta su true per ignorare le variabili non risolte e continuare l'elaborazione. altrimenti false. La il valore predefinito è true.

L'impostazione di <IgnoreUnresolvedVariables> su true è diversa dall'impostazione di <TraceCapture> Da continueOnError a true. Se imposti continueOnError su true, Apigee ignora tutti gli errori, non solo gli errori nelle variabili.

L'elemento <IgnoreUnresolvedVariables> utilizza la seguente sintassi:

Sintassi

<IgnoreUnresolvedVariables>BOOLEAN_VALUE</IgnoreUnresolvedVariables>

Esempio

L'esempio seguente imposta <IgnoreUnresolvedVariables> su false:

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>

<ThrowExceptionOnLimit>

Specifica il comportamento del criterio quando le dimensioni della variabile superano il limite di 256 byte.

  • Se impostato su true, il criterio genera un errore se la dimensione di una variabile supera il limite.
  • Se impostato su false, il criterio tronca la variabile che supera il limite. La variabile viene troncata in base alle dimensioni del limite.
Valore predefinito N/D
Obbligatorio? Facoltativo
Tipo Booleano
Elemento principale <TraceCapture>
Elementi secondari Nessuno

La sintassi dell'elemento <ThrowExceptionOnLimit> è la seguente:

Sintassi

<ThrowExceptionOnLimit>BOOLEAN_VALUE</ThrowExceptionOnLimit>

Esempio

Nell'esempio seguente, il valore <ThrowExceptionOnLimit> viene impostato su true.

<ThrowExceptionOnLimit>false</ThrowExceptionOnLimit>

Codici 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 quando il criterio viene eseguito.

Codice di errore Stato HTTP Causa
steps.tracecapture.UnresolvedVariable 500

Questo errore si verifica se una variabile specificata nel criterio TraceCapture è:

  • Fuori ambito (non disponibile nel flusso specifico in cui viene eseguito il criterio)
  • o
  • Impossibile risolvere (non è definito)
steps.tracecapture.VariableValueLimitExceeded 500

Questo errore si verifica se l'elemento <ThrowExceptionOnLimit> è impostato su true e le dimensioni di una variabile superano i 256 byte.

Variabili di errore

Ogni volta che si verificano errori di esecuzione in un criterio, Apigee genera messaggi di errore. Puoi visualizzare questi messaggi nella risposta. Spesso i messaggi di errore generati dal sistema potrebbero non essere pertinenti nel contesto del tuo prodotto. Ti consigliamo di personalizzare i messaggi di errore in base alle tipo di errore per rendere i messaggi più significativi.

Per personalizzare i messaggi di errore, puoi utilizzare le regole di errore o il criterio RaiseFault. Per informazioni sulle differenze tra le regole di errore e il criterio RaiseFault, vedi FaultRules e il criterio RaiseFault. Devi verificare le condizioni utilizzando l'elemento Condition sia nelle regole di errore sia nel criterio RaiseFault. Apigee fornisce variabili di errore univoche per ogni criterio e i valori delle variabili di errore vengono impostati quando un criterio attiva errori di runtime. Utilizzando queste variabili, puoi verificare la presenza di condizioni di errore specifiche e intraprendere le azioni appropriate. Per ulteriori informazioni sulla verifica dell'errore , consulta Condizioni di creazione.

La tabella seguente descrive le variabili di errore specifiche di questo criterio.

Variabili Dove Esempio
fault.name fault.name può corrispondere a uno dei guasti elencati nella tabella Errori di runtime. Il nome dell'errore è l'ultima parte del codice dell'errore. fault.name Matches "UnresolvedVariable"
tracecapture.POLICY_NAME.failed POLICY_NAME è il nome specificato dall'utente del criterio che ha generato l'errore. tracecapture.trace-capture-1.failed = true
Per ulteriori informazioni sugli errori relativi alle norme, consulta Informazioni importanti sugli errori relativi alle norme.