Política de TraceCapture

Esta página se aplica a Apigee y Apigee hybrid.

Consulta la documentación de Apigee Edge.

Vista previa

Este producto o función está sujeto a los "Términos de las Ofertas de Acceso Previo a la Disponibilidad General" de la sección Términos Generales de los Servicios de los Términos Específicos de los Servicios. Los productos y las funciones previos a la disponibilidad general están disponibles tal cual y pueden tener una compatibilidad y asistencia limitadas. Para obtener más información, consulta las descripciones de las fases de lanzamiento.

La política TraceCapture te permite añadir variables adicionales a los datos de seguimiento del tiempo de ejecución de Apigee. Si has habilitado el rastreo distribuido en el tiempo de ejecución de Apigee, este rastrea de forma predeterminada un conjunto de variables predefinidas. Para obtener más información, consulta Variables de seguimiento predeterminadas en el informe de seguimiento. Sin embargo, si quiere que el tiempo de ejecución de Apigee rastree variables de flujo, de política o personalizadas adicionales, utilice la política TraceCapture. Puedes usar esta política en el flujo de solicitudes o en el de respuestas. En el informe de seguimiento distribuido, puede ver las variables añadidas por la política TraceCapture en el TraceCaptureExecution.

Esta política es una política extensible y su uso puede tener implicaciones en cuanto a costes o utilización, en función de tu licencia de Apigee. Para obtener información sobre los tipos de políticas y las implicaciones de uso, consulta Tipos de políticas.

<TraceCapture>

Define la política TraceCapture.

Valor predeterminado	N/A
¿Es obligatorio?	Obligatorio
Tipo	Tipo complejo
Elemento principal	N/A
Elementos secundarios	<DisplayName> <IgnoreUnresolvedVariables> <ThrowExceptionOnLimit> <Variables>

El elemento <TraceCapture> utiliza la siguiente sintaxis:

Sintaxis

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

Ejemplo

En el ejemplo siguiente se muestra la definición de la política 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>

Este elemento tiene los siguientes atributos, que son comunes a todas las políticas:

Atributo	Predeterminado	¿Es obligatorio?	Descripción
name	N/A	Obligatorio	El nombre interno de la política. El valor del atributo name puede contener letras, números, espacios, guiones, guiones bajos y puntos. Este valor no puede superar los 255 caracteres. Opcionalmente, usa el elemento <DisplayName> para etiquetar la política en el editor de proxy de la interfaz de gestión con un nombre diferente en lenguaje natural.
continueOnError	falso	Opcional	Asigna el valor false para devolver un error cuando falle una política. Este es el comportamiento esperado de la mayoría de las políticas. Asigna el valor true para que la ejecución del flujo continúe incluso después de que falle una política. Consulta también: Las reglas de errores solo se activan cuando hay un error (sobre continueOnError) Gestionar fallos en el flujo actual
enabled	true	Opcional	Asigna el valor true para aplicar la política. Selecciona false para desactivar la política. La política no se aplicará aunque siga adjunta a un flujo.
async	falso	Obsoleto	Este atributo está obsoleto.

En la siguiente tabla se ofrece una descripción general de los elementos secundarios de <TraceCapture>:

Elemento secundario	¿Es obligatorio?	Descripción
<DisplayName>	Opcional	Especifica un nombre personalizado para la política.
<Variables>	Opcional	Especifica la lista de variables que se van a monitorizar.
<IgnoreUnresolvedVariables>	Opcional	Especifica si el procesamiento se detiene cuando se encuentra una variable sin resolver.
<ThrowExceptionOnLimit>	Opcional	Especifica si se debe truncar una variable si su tamaño supera el límite de 256 bytes.
Otros elementos secundarios
<MergeBehavior>	Opcional	Especifica el comportamiento de combinación de los mensajes de respuesta.

Referencia de elemento secundario

En esta sección se describen los elementos secundarios de <TraceCapture>.

<DisplayName>

Se usa junto con el atributo name para etiquetar la política en el editor de proxy de la interfaz de usuario de gestión con un nombre diferente que suene más natural.

El elemento <DisplayName> es común a todas las políticas.

Valor predeterminado	N/A
¿Es obligatorio?	Opcional. Si omite <DisplayName>, se usará el valor del atributo name de la política.
Tipo	Cadena
Elemento principal	<PolicyElement>
Elementos secundarios	Ninguno

El elemento <DisplayName> utiliza la siguiente sintaxis:

Sintaxis

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

Ejemplo

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

El elemento <DisplayName> no tiene atributos ni elementos secundarios.

<Variables>

Especifica la lista de variables que se van a monitorizar.

Valor predeterminado	N/A
¿Es obligatorio?	Obligatorio
Tipo	Tipo complejo
Elemento principal	<TraceCapture>
Elementos secundarios	<Variable>

El elemento <Variables> utiliza la siguiente sintaxis:

Sintaxis

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

Ejemplo

En el siguiente ejemplo se hace un seguimiento de las variables de flujo flow-variable-1 y 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:

• No puedes monitorizar las variables private y policy.secret.
• Apigee recomienda configurar un máximo de 15 variables para Cloud Trace y un máximo de 25 variables para Jaeger.

<Variable>

Especifica las variables que se van a añadir a los datos de la traza.

Valor predeterminado	N/A
¿Es obligatorio?	Obligatorio
Tipo	Tipo complejo
Elemento principal	<Variables>
Elementos secundarios	Ninguno

El elemento <Variable> utiliza la siguiente sintaxis:

Sintaxis

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

Ejemplo

En el ejemplo siguiente se asigna a la variable de seguimiento trace-variable-1 el valor de la variable de flujo flow-variable-1:

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

Si la variable de flujo flow-variable-1 no está disponible, trace-variable-1 se asigna al valor predeterminado default-val-1.

En la siguiente tabla se describen los atributos de <Variable>:

Atributo	¿Es obligatorio?	Tipo	Descripción
name	Obligatorio	Cadena	Nombre que se usará para hacer referencia a los datos recogidos de la variable especificada. Este nombre se mostrará en el informe de seguimiento distribuido.
ref	Obligatorio	Cadena	La variable de la que está recogiendo los datos de la traza. Esta variable puede ser una variable de flujo predefinida por Apigee o una variable personalizada de tu proxy de API.

Nota: Puedes especificar un valor predeterminado opcional para una variable. Si la variable especificada en ref no está definida en una solicitud o una respuesta, los datos de la traza tendrán el valor predeterminado de la variable.

<IgnoreUnresolvedVariables>

Determina si el procesamiento se detiene cuando se encuentra una variable sin resolver.

Valor predeterminado	N/A
¿Es obligatorio?	Opcional
Tipo	Booleano
Elemento principal	<TraceCapture>
Elementos secundarios	Ninguno

Asigna el valor true para ignorar las variables sin resolver y continuar con el procesamiento. De lo contrario, asigna el valor false. El valor predeterminado es true.

Asignar el valor true a <IgnoreUnresolvedVariables> no es lo mismo que asignar el valor true a continueOnError de <TraceCapture>. Si asigna el valor true a continueOnError, Apigee ignora todos los errores, no solo los de las variables.

El elemento <IgnoreUnresolvedVariables> utiliza la siguiente sintaxis:

Sintaxis

<IgnoreUnresolvedVariables>BOOLEAN_VALUE</IgnoreUnresolvedVariables>

Ejemplo

En el siguiente ejemplo se asigna false a <IgnoreUnresolvedVariables>:

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>

Nota: El valor predeterminado del elemento es false.

<ThrowExceptionOnLimit>

Especifica el comportamiento de la política cuando el tamaño de la variable supera el límite de 256 bytes.

• Si se define como true, la política genera un error si el tamaño de una variable supera el límite.
• Si se define como false, la política trunca la variable que supere el límite. La variable se trunca al tamaño del límite.

Nota: El valor predeterminado del elemento es false.

Valor predeterminado	N/A
¿Es obligatorio?	Opcional
Tipo	Booleano
Elemento principal	<TraceCapture>
Elementos secundarios	Ninguno

El elemento <ThrowExceptionOnLimit> utiliza la siguiente sintaxis:

Sintaxis

<ThrowExceptionOnLimit>BOOLEAN_VALUE</ThrowExceptionOnLimit>

Ejemplo

En el siguiente ejemplo se asigna el valor true a <ThrowExceptionOnLimit>.

<ThrowExceptionOnLimit>false</ThrowExceptionOnLimit>

Códigos de error

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.