Cette page s'applique à Apigee et à Apigee hybrid.
Consultez la documentation d'Apigee Edge.
Présentation
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 | ND |
| 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 Vous pouvez également utiliser l'élément |
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 :
|
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 | Requis ? | 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 | ND |
| 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 | Aucune |
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 | ND |
| 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>
<Variable>
Spécifie les variables à ajouter dans les données de trace.
| Valeur par défaut | ND |
| Obligatoire ? | Obligatoire |
| Type | Type complexe |
| Élément parent |
<Variables> |
| Éléments enfants | Aucune |
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 | Requis ? | 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 |
Requis | 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. |
<IgnoreUnresolvedVariables>
Détermine si le traitement s'arrête lorsqu'une variable non résolue est rencontrée.
| Valeur par défaut | ND |
| Requis ? | 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>
<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.
| Valeur par défaut | ND |
| Requis ? | Facultatif |
| Type | Booléen |
| Élément parent |
<TraceCapture> |
| Éléments enfants | Aucune |
L'élément <ThrowExceptionOnLimit> utilise la syntaxe suivante :
Syntaxe
<ThrowExceptionOnLimit>BOOLEAN_VALUE</ThrowExceptionOnLimit>
Exemple
L'exemple suivant définit l'élément <ThrowExceptionOnLimit>true.
<ThrowExceptionOnLimit>false</ThrowExceptionOnLimit>
Codes d'erreur
Cette section décrit les codes d'erreur et les messages d'erreur renvoyés et les variables d'erreur définies par Apigee lorsque cette règle déclenche une erreur. Ces informations sont importantes si vous développez des règles de défaillance afin de gérer les pannes. Pour en savoir plus, consultez les pages Ce que vous devez savoir à propos des erreurs liées aux règles et Gérer les pannes.
Erreurs d'exécution
Ces erreurs peuvent se produire lors de l'exécution de la règle.
| Code d'erreur | État HTTP | Cause |
|---|---|---|
steps.tracecapture.UnresolvedVariable |
500 |
Cette erreur se produit si une variable spécifiée dans la règle TraceCapture répond à l'une des conditions suivantes :
|
steps.tracecapture.VariableValueLimitExceeded |
500 |
Cette erreur se produit si l'élément |
Variables de panne
Chaque fois qu'une règle comporte des erreurs d'exécution, Apigee génère des messages d'erreur. Vous pouvez afficher ces messages d'erreur dans la réponse d'erreur. Souvent, les messages d'erreur générés par le système peuvent ne pas être pertinents dans le contexte de votre produit. Vous pouvez personnaliser les messages d'erreur en fonction du type d'erreur pour rendre les messages plus significatifs.
Pour personnaliser les messages d'erreur, vous pouvez utiliser des règles d'erreur ou la règle RaiseFault. Pour en savoir plus sur les différences entre les règles d'erreur et la règle RaiseFault, consultez la section Règles d'erreur et règle RaiseFault.
Vous devez vérifier les conditions à l'aide de l'élément Condition dans les règles d'erreur et dans la règle RaiseFault.
Apigee fournit des variables d'erreur propres à chaque règle et les valeurs des variables d'erreur sont définies lorsqu'une règle déclenche des erreurs d'exécution.
En utilisant ces variables, vous pouvez vérifier des conditions d'erreur spécifiques et prendre les mesures appropriées. Pour en savoir plus sur la vérification des conditions d'erreur, consultez la page Conditions de création.
Le tableau suivant décrit les variables d'erreur spécifiques à cette règle.
| Variables | Où : | Exemple |
|---|---|---|
fault.name |
L'élément fault.name peut correspondre à n'importe quelle erreur affichée dans le tableau Erreurs d'exécution.
Le nom d'erreur est la dernière partie du code d'erreur. |
fault.name Matches "UnresolvedVariable" |
tracecapture.POLICY_NAME.failed |
POLICY_NAME est le nom spécifié par l'utilisateur de la règle qui a provoqué l'erreur. | tracecapture.trace-capture-1.failed = true |