Criterio Trace Capture

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Anteprima

Questo prodotto o funzionalità è soggetto ai "Termini delle Offerte pre-GA" nella sezione Termini generali del servizio dei Termini specifici del servizio. I prodotti e le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per saperne di più, consulta le descrizioni della fase di lancio.

Panoramica

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

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

L'elemento <TraceCapture> utilizza la seguente sintassi:

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: Le regole di errore vengono attivate SOLO in uno stato di errore (su continueOnError) Gestione degli errori nel flusso corrente
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 <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	Consente di specificare se l'elaborazione si interrompe quando viene rilevata una variabile non risolta.
<ThrowExceptionOnLimit>	Facoltativo	Specifica se una variabile deve essere troncata se la dimensione supera il limite di 256 byte.
Altri elementi secondari
<MergeBehavior>	Facoltativo	Specifica il comportamento di unione per i messaggi di risposta.

Riferimento elemento secondario

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

<DisplayName>

Utilizzalo in aggiunta 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/A
Obbligatorio?	Facoltativo. Se ometti <DisplayName>, viene utilizzato il valore dell'attributo name del criterio.
Tipo	Stringa
Elemento principale	<PolicyElement>
Elementi secondari	Nessuna esperienza

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>

L'elemento <Variables> utilizza la seguente sintassi:

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>

Nota:

• Non puoi tracciare le variabili private e policy.secret.
• Apigee consiglia di configurare un massimo di 15 variabili per Cloud Trace e un massimo di 25 variabili per Jaeger.

<Variable>

Specifica le variabili da aggiungere nei dati di traccia.

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

L'elemento <Variable> utilizza la seguente sintassi:

Sintassi

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

Esempio

Nell'esempio seguente la variabile di traccia trace-variable-1 viene impostata sul 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.

La tabella seguente descrive gli attributi di <Variable>:

Attributo	Obbligatorio?	Tipo	Descrizione
name	Obbligatorio	Stringa	Un nome per fare riferimento ai dati raccolti per la variabile specificata. Questo nome sarà visibile nel report di tracciamento distribuito.
ref	Obbligatorio	Stringa	La variabile per cui stai raccogliendo i dati di traccia. Può essere una variabile di flusso predefinita da Apigee o una variabile personalizzata nel proxy API.

Nota: puoi specificare un valore predefinito facoltativo per una variabile. Se la variabile specificata in ref non è definita in una richiesta o in una risposta, i dati di traccia avranno il valore predefinito per la variabile.

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

Imposta il valore su true per ignorare le variabili non risolte e continuare l'elaborazione; in caso contrario, false. Il valore predefinito è true.

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

L'elemento <IgnoreUnresolvedVariables> utilizza la seguente sintassi:

Sintassi

<IgnoreUnresolvedVariables>BOOLEAN_VALUE</IgnoreUnresolvedVariables>

Esempio

Nell'esempio seguente viene impostato il valore <IgnoreUnresolvedVariables> su false:

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>

Nota: il valore predefinito dell'elemento è false.

<ThrowExceptionOnLimit>

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

• Se viene impostato su true, il criterio genera un errore se una dimensione della variabile supera il limite.
• Se viene impostato su false, il criterio tronca la variabile che supera il limite. La variabile viene troncata in base alla dimensione del limite.

Nota: il valore predefinito dell'elemento è false.

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

L'elemento <ThrowExceptionOnLimit> utilizza la seguente sintassi:

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 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.tracecapture.UnresolvedVariable	500	Questo errore si verifica se una variabile specificata nel criterio Trace Capture è: Fuori ambito (non disponibile nel flusso specifico in cui viene eseguito il criterio) o Non può essere risolto (non è definito)
steps.tracecapture.VariableValueLimitExceeded	500	Questo errore si verifica se l'elemento <ThrowExceptionOnLimit> è impostato su true e le dimensioni di qualsiasi 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 di errore nella risposta di errore. Molte volte, i messaggi di errore generati dal sistema potrebbero non essere pertinenti nel contesto del prodotto. Per rendere i messaggi più significativi, potresti voler personalizzare i messaggi in base al tipo.

Per personalizzare i messaggi di errore, puoi utilizzare regole di errore o il criterio AlzaFault. Per informazioni sulle differenze tra le regole di errore e il criterio AlzaFault, consulta Confronto tra le regole di errore e il criterio AlzaFault. Devi verificare le condizioni utilizzando l'elemento Condition sia nelle regole di errore sia nel criterio AlzaFault. Apigee fornisce variabili di errore univoche per ciascun criterio e i relativi valori vengono impostati quando un criterio attiva gli errori di runtime. Utilizzando queste variabili, puoi verificare le condizioni di errore specifiche e intraprendere le azioni appropriate. Per saperne di più sul controllo delle condizioni di errore, consulta Condizioni degli edifici.

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

Variabili	Dove	Esempio
fault.name	fault.name può corrispondere a qualsiasi errore elencato nella tabella Errori di runtime. Il nome del guasto è l'ultima parte del codice di 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 dei criteri, consulta la sezione Cosa devi sapere sugli errori dei criteri.