Norme di TraceCapture

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 di servizio generali dei Termini di servizio specifici. I prodotti e le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni delle fasi di lancio.

Il criterio TraceCapture consente di aggiungere variabili aggiuntive ai dati di traccia del runtime Apigee. Se hai attivato la tracciabilità distribuita per il runtime Apigee, il runtime, per impostazione predefinita, traccia un insieme di variabili predefinite. Per saperne di più, vedi Variabili di traccia predefinite nel report di tracciamento. Tuttavia, se vuoi che il runtime Apigee tracci ulteriori variabili di flusso, criteri o personalizzate, utilizza il criterio TraceCapture. Puoi utilizzare questo criterio nel flusso di richiesta o di risposta. Nel report di tracciamento distribuito, puoi visualizzare le variabili aggiunte dalla norma TraceCapture nell'intervallo TraceCaptureExecution.

Queste norme sono estendibili e il loro utilizzo potrebbe avere implicazioni in termini di costi o utilizzo, a seconda della licenza Apigee. Per informazioni sui tipi di policy e sulle implicazioni di utilizzo, consulta Tipi di policy.

<TraceCapture>

Definisce il criterio TraceCapture.

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

<?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/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: Le regole di errore vengono attivate SOLO in uno stato di errore (informazioni su continueOnError) Gestione degli errori all'interno del 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	Ritirato	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 la policy.
<Variables>	Facoltativo	Specifica l'elenco delle 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

Questa sezione descrive gli elementi secondari di <TraceCapture>.

<DisplayName>

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, more natural-sounding name.

The <DisplayName> element is common to all policies.

Default Value	N/A
Required?	Optional. If you omit <DisplayName>, the value of the policy's name attribute is used.
Type	String
Parent Element	<PolicyElement>
Child Elements	None

The <DisplayName> element uses the following syntax:

Syntax

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

Example

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

The <DisplayName> element has no attributes or child elements.

<Variables>

Specifica l'elenco delle 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 ai dati di tracciamento.

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

L'elemento <Variable> utilizza la seguente sintassi:

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 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 è impostata 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. Questa variabile 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	Nessuno

Imposta true per ignorare le variabili non risolte e continuare l'elaborazione; altrimenti false. Il valore predefinito è true.

Impostare <IgnoreUnresolvedVariables> su true è diverso dall'impostazione di continueOnError di <TraceCapture> su true. 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

L'esempio seguente imposta <IgnoreUnresolvedVariables> su false:

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>

Nota: il valore predefinito dell'elemento è false.

<ThrowExceptionOnLimit>

Specifica il comportamento del criterio quando la dimensione della variabile supera il limite di 256 byte.

• Se impostata su true, la policy genera un errore se una dimensione 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.

Nota: il valore predefinito dell'elemento è false.

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

L'elemento <ThrowExceptionOnLimit> utilizza la seguente sintassi:

Sintassi

<ThrowExceptionOnLimit>BOOLEAN_VALUE</ThrowExceptionOnLimit>

Esempio

L'esempio seguente imposta il valore <ThrowExceptionOnLimit> su true.

<ThrowExceptionOnLimit>false</ThrowExceptionOnLimit>

Codici 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.tracecapture.UnresolvedVariable	500	This error occurs if a variable specified in the TraceCapture policy is either: Out of scope (not available in the specific flow where the policy is being executed) or Can't be resolved (is not defined)
steps.tracecapture.VariableValueLimitExceeded	500	This error occurs if the <ThrowExceptionOnLimit> element is set to true and the size of any variable exceeds 256 bytes.

Fault variables

Whenever there are execution errors in a policy, Apigee generates error messages. You can view these error messages in the error response. Many a time, system generated error messages might not be relevant in the context of your product. You might want to customize the error messages based on the type of error to make the messages more meaningful.

To customize the error messages, you can use either fault rules or the RaiseFault policy. For information about differences between fault rules and the RaiseFault policy, see FaultRules vs. the RaiseFault policy. You must check for conditions using the Condition element in both the fault rules and the RaiseFault policy. Apigee provides fault variables unique to each policy and the values of the fault variables are set when a policy triggers runtime errors. By using these variables, you can check for specific error conditions and take appropriate actions. For more information about checking error conditions, see Building conditions.

The following table describes the fault variables specific to this policy.

Variables	Where	Example
fault.name	The fault.name can match to any of the faults listed in the Runtime errors table. The fault name is the last part of the fault code.	fault.name Matches "UnresolvedVariable"
tracecapture.POLICY_NAME.failed	POLICY_NAME is the user-specified name of the policy that threw the fault.	tracecapture.trace-capture-1.failed = true

For more information about policy errors, see What you need to know about policy errors.