Règle TraceCapture

Cette page s'applique à Apigee et à Apigee hybrid.

Consultez la documentation d'Apigee Edge.

Preview

Ce produit ou cette fonctionnalité sont soumis aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Les produits et fonctionnalités de pré-DG sont proposés "en l'état" et peuvent avoir une compatibilité limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

La règle TraceCapture vous permet d'ajouter des variables supplémentaires aux données de trace de votre environnement d'exécution Apigee. Si vous avez activé le traçage distribué pour l'environnement d'exécution Apigee, l'environnement d'exécution trace par défaut un ensemble de variables prédéfinies. Pour en savoir plus, consultez la section Variables de trace par défaut dans le rapport de traçage. Cependant, si vous souhaitez que l'environnement d'exécution Apigee trace un flux, une règle ou des variables personnalisées supplémentaires, utilisez la règle TraceCapture. Vous pouvez utiliser cette règle dans le flux de requêtes ou dans le flux de réponses. Dans votre rapport de traçage distribué, vous pouvez afficher les variables ajoutées par la règle TraceCapture dans le segment TraceCaptureExecution.

Cette règle est une règle extensible et son utilisation peut avoir des conséquences sur le coût ou l'utilisation, en fonction de votre licence Apigee. Pour en savoir plus sur les types de règles et les implications en termes d'utilisation, consultez la section Types de règles.

<TraceCapture>

Définit la règle TraceCapture.

Valeur par défaut	N/A
Obligatoire ?	Obligatoire
Type	Type complexe
Élément parent	ND
Éléments enfants	<DisplayName> <IgnoreUnresolvedVariables> <ThrowExceptionOnLimit> <Variables>

L'élément <TraceCapture> utilise la syntaxe suivante :

Syntaxe

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

Exemple

L'exemple suivant montre la définition de la règle 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>

Cet élément possède les attributs suivants qui sont communs à toutes les règles :

Attribut	Par défaut	Obligatoire ?	Description
name	ND	Obligatoire	Nom interne de la règle. La valeur de l'attribut name peut contenir des lettres, des chiffres, des espaces, des tirets, des traits de soulignement et des points. Cette valeur ne peut pas dépasser 255 caractères. Vous pouvez également utiliser l'élément <DisplayName> pour ajouter un libellé à la règle dans l'éditeur de proxy de l'interface utilisateur de gestion avec un nom différent, en langage naturel.
continueOnError	faux	Facultatif	Définissez sur false pour afficher une erreur en cas d'échec d'une règle. Il s'agit du comportement attendu pour la plupart des règles. Définissez sur true pour que l'exécution du flux se poursuive même après l'échec d'une règle. Voir aussi : Les règles d'erreur sont déclenchées UNIQUEMENT en cas d'erreur (à propos de continueOnError) Gérer les pannes dans le flux actuel
enabled	true	Facultatif	Définissez sur true pour appliquer la règle. Définissez sur false pour désactiver la règle. La règle ne sera pas appliquée même si elle reste associée à un flux.
async	faux	Obsolète	Cet attribut est obsolète.

Le tableau suivant fournit une description détaillée des éléments enfants de <TraceCapture> :

Élément enfant	Obligatoire ?	Description
<DisplayName>	Facultatif	Spécifie le nom personnalisé de la règle.
<Variables>	Facultatif	Spécifie la liste des variables à tracer.
<IgnoreUnresolvedVariables>	Facultatif	Spécifie si le traitement s'arrête lorsqu'une variable non résolue est rencontrée.
<ThrowExceptionOnLimit>	Facultatif	Spécifie si une variable doit être tronquée si la taille de la variable dépasse la limite de 256 octets.
Autres éléments enfants
<MergeBehavior>	Facultatif	Spécifie le comportement de fusion des messages de réponse.

Référence d'élément enfant

Cette section décrit les éléments enfants de <TraceCapture>.

<DisplayName>

Utilisez-le, en plus de l'attribut name, pour appliquer un libellé à la règle dans l'éditeur de proxys de l'interface de gestion en utilisant un nom différent et plus naturel.

L'élément <DisplayName> est commun à toutes les règles.

Valeur par défaut	N/A
Obligatoire ?	Facultatif. Si vous omettez <DisplayName>, la valeur de l'attribut name de la règle est utilisée.
Type	Chaîne
Élément parent	<PolicyElement>
Éléments enfants	Aucun

L'élément <DisplayName> utilise la syntaxe suivante :

Syntaxe

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

Exemple

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

L'élément <DisplayName> ne comporte aucun attribut ni élément enfant.

<Variables>

Spécifie la liste des variables à tracer.

Valeur par défaut	N/A
Obligatoire ?	Obligatoire
Type	Type complexe
Élément parent	<TraceCapture>
Éléments enfants	<Variable>

L'élément <Variables> utilise la syntaxe suivante :

Syntaxe

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

Exemple

L'exemple suivant trace les variables de flux flow-variable-1 et 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>

Remarque :

• Vous ne pouvez pas tracer les variables private et policy.secret.
• Apigee vous recommande de configurer un maximum de 15 variables pour Cloud Trace et un maximum de 25 variables pour Jaeger.

<Variable>

Spécifie les variables à ajouter dans les données de trace.

Valeur par défaut	N/A
Obligatoire ?	Obligatoire
Type	Type complexe
Élément parent	<Variables>
Éléments enfants	Aucun

L'élément <Variable> utilise la syntaxe suivante :

Syntaxe

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

Exemple

L'exemple suivant définit la variable de trace trace-variable-1 sur la valeur de la variable de flux flow-variable-1 :

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

Si la variable de flux flow-variable-1 n'est pas disponible, trace-variable-1 est défini sur la valeur par défaut default-val-1.

Le tableau suivant décrit les attributs de <Variable> :

Attribut	Obligatoire ?	Type	Description
name	Obligatoire	Chaîne	Nom permettant de référencer les données collectées pour la variable spécifiée. Ce nom sera visible dans votre rapport de traçage distribué.
ref	Obligatoire	Chaîne	Variable pour laquelle vous collectez les données de trace. Cette variable peut être une variable de flux prédéfinie par Apigee ou une variable personnalisée dans votre proxy d'API.

Remarque : Vous pouvez spécifier une valeur par défaut facultative pour une variable. Si la variable spécifiée dans ref n'est pas définie dans une requête ou dans une réponse, les données de trace auront la valeur par défaut de la variable.

<IgnoreUnresolvedVariables>

Détermine si le traitement s'arrête lorsqu'une variable non résolue est rencontrée.

Valeur par défaut	N/A
Obligatoire ?	Facultatif
Type	Booléen
Élément parent	<TraceCapture>
Éléments enfants	Aucun

Définissez la valeur sur true pour ignorer les variables non résolues et poursuivre le traitement, sinon false. La valeur par défaut est true.

Définir <IgnoreUnresolvedVariables> sur true n'est pas la même chose que définir la valeur continueOnError de <TraceCapture> sur true. Si vous définissez continueOnError sur true, Apigee ignore toutes les erreurs, et pas seulement les erreurs dans les variables.

L'élément <IgnoreUnresolvedVariables> utilise la syntaxe suivante :

Syntaxe

<IgnoreUnresolvedVariables>BOOLEAN_VALUE</IgnoreUnresolvedVariables>

Exemple

L'exemple suivant définit <IgnoreUnresolvedVariables> sur false :

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>

Remarque : La valeur par défaut de l'élément est false.

<ThrowExceptionOnLimit>

Spécifie le comportement de la règle lorsque la taille de la variable dépasse la limite de 256 octets.

• S'il est défini sur true, la règle génère une erreur si la taille d'une variable dépasse la limite.
• S'il est défini sur false, la règle tronque la variable qui dépasse la limite. La variable est tronquée à la taille de la limite.

Remarque : La valeur par défaut de l'élément est false.

Valeur par défaut	N/A
Obligatoire ?	Facultatif
Type	Booléen
Élément parent	<TraceCapture>
Éléments enfants	Aucun

L'élément <ThrowExceptionOnLimit> utilise la syntaxe suivante :

Syntaxe

<ThrowExceptionOnLimit>BOOLEAN_VALUE</ThrowExceptionOnLimit>

Exemple

L'exemple suivant définit l'élément <ThrowExceptionOnLimit> sur true.

<ThrowExceptionOnLimit>false</ThrowExceptionOnLimit>

Codes d'erreur

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.