Política de TraceCapture

Política extensível

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

Visualizar

Este produto ou recurso está sujeito aos "Termos das Soluções Pré-GA" na seção "Termos Gerais de Serviço" dos Termos Específicos de Serviço. Os produtos e recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

A política TraceCapture permite adicionar mais variáveis aos dados de trace do ambiente de execução da Apigee. Se você tiver ativado o rastreamento distribuído para o ambiente de execução da Apigee, o ambiente de execução, por padrão, rastreará um conjunto de variáveis predefinidas. Saiba mais em Variáveis de trace padrão no relatório de rastreamento. No entanto, se você quiser que o ambiente de execução da Apigee rastreie outros fluxos, políticas ou variáveis personalizadas, use a política TraceCapture. Use essa política no fluxo de solicitação ou de resposta. No relatório de rastreamento distribuído, você pode ver as variáveis adicionadas pela política TraceCapture no período TraceCaptureExecution.

Esta é uma política extensível. O uso dela pode ter implicações no custo ou na utilização, dependendo da sua licença da Apigee. Para informações sobre tipos de política e implicações de uso, consulte Tipos de política.

<TraceCapture>

Define a política TraceCapture.

Valor padrão	N/A
Obrigatório?	Obrigatório
Tipo	Tipo complexo
Elemento pai	N/A
Elemento filho	<DisplayName> <IgnoreUnresolvedVariables> <ThrowExceptionOnLimit> <Variables>

O elemento <TraceCapture> usa a seguinte sintaxe:

Sintaxe

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

Exemplo

O exemplo a seguir mostra a definição da 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 tem os seguintes atributos comuns a todas as políticas:

Atributo	Padrão	Obrigatório?	Descrição
name	N/A	Valor	O nome interno da política. O valor do atributo name pode conter letras, números, espaços, hifens, sublinhados e pontos. Esse valor não pode exceder 255 caracteres. Opcionalmente, use o elemento <DisplayName> para rotular a política no editor de proxy da IU de gerenciamento com um nome de linguagem natural diferente.
continueOnError	falso	Opcional	Defina como false para retornar um erro quando uma política falhar. Esse é o comportamento esperado para a maioria das políticas. Defina como true para que a execução do fluxo continue, mesmo depois que uma política falhar. Consulte também: As regras de falha são acionadas SOMENTE em um estado de erro (sobre continueOnError) Como corrigir falhas no fluxo atual
enabled	true	Opcional	Defina como true para aplicar a política. Defina como false para desativar a política. A política não será aplicada mesmo que permaneça vinculada a um fluxo.
async	falso	Obsoleto	Esse atributo está obsoleto.

A tabela a seguir fornece uma descrição de alto nível dos elementos-filhos de <TraceCapture>:

Elemento filho	Obrigatório?	Descrição
<DisplayName>	Opcional	Especifica um nome personalizado para a política.
<Variables>	Opcional	Especifica a lista de variáveis a serem rastreadas.
<IgnoreUnresolvedVariables>	Opcional	Determina se o processamento é interrompido quando uma variável não resolvida é encontrada.
<ThrowExceptionOnLimit>	Opcional	Especifica se uma variável precisa ser truncada se o tamanho dela exceder o limite de 256 bytes.
Outros elementos filhos
<MergeBehavior>	Opcional	Especifica o comportamento de mesclagem para as mensagens de resposta.

Referência a elementos filhos

Esta seção descreve os elementos filhos de <TraceCapture>.

<DisplayName>

Use além do atributo name para rotular a política no editor de proxy da IU de gerenciamento com um nome de som diferente e mais natural.

O elemento <DisplayName> é comum a todas as políticas.

Valor padrão	N/A
Obrigatório?	Opcional. Se você omitir <DisplayName>, o valor do atributo name da política será usado
Tipo	String
Elemento pai	<PolicyElement>
Elemento filho	Nenhum

O elemento <DisplayName> usa a seguinte sintaxe:

Sintaxe

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

Exemplo

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

O elemento <DisplayName> não tem atributos ou elementos filhos.

<Variables>

Especifica a lista de variáveis a serem rastreadas.

Valor padrão	N/A
Obrigatório?	Obrigatório
Tipo	Tipo complexo
Elemento pai	<TraceCapture>
Elemento filho	<Variable>

O elemento <Variables> usa a seguinte sintaxe:

Sintaxe

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

Exemplo

O exemplo a seguir rastreia as variáveis de fluxo 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>

Observação:

• Não é possível rastrear as variáveis private e policy.secret.
• A Apigee recomenda configurar no máximo 15 variáveis para o Cloud Trace e no máximo 25 para o Jaeger.

<Variable>

Especifica as variáveis a serem adicionadas aos dados de trace.

Valor padrão	N/A
Obrigatório?	Obrigatório
Tipo	Tipo complexo
Elemento pai	<Variables>
Elemento filho	Nenhum

O elemento <Variable> usa a seguinte sintaxe:

Sintaxe

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

Exemplo

No exemplo a seguir, definimos a variável de trace trace-variable-1 para o valor da variável de fluxo flow-variable-1:

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

Se a variável de fluxo flow-variable-1 não estiver disponível, trace-variable-1 será definido como o valor padrão default-val-1.

A tabela a seguir descreve os atributos de <Variable>:

Atributo	Obrigatório?	Tipo	Descrição
name	Obrigatório	String	Um nome para fazer referência aos dados coletados para a variável especificada. Esse nome ficará visível no relatório de rastreamento distribuído.
ref	Obrigatório	String	A variável em que você está coletando os dados de trace. Essa variável pode ser uma variável de fluxo predefinida pela Apigee ou uma variável personalizada no proxy de API.

Observação: é possível especificar um valor padrão opcional para uma variável. Se a variável especificada em ref não for definida em uma solicitação ou resposta, os dados do trace terão o valor padrão para a variável.

<IgnoreUnresolvedVariables>

Determina se o processamento é interrompido quando uma variável não resolvida é encontrada.

Valor padrão	N/A
Obrigatório?	Opcional
Tipo	Booleano
Elemento pai	<TraceCapture>
Elemento filho	Nenhum

Defina como true para ignorar variáveis não resolvidas e continuar o processamento. Caso contrário, false. O valor padrão é true.

Definir <IgnoreUnresolvedVariables> como true é diferente de definir o continueOnError do <TraceCapture> como true. Se você definir continueOnError como true, a Apigee vai ignorar todos os erros, e não apenas os erros nas variáveis.

O elemento <IgnoreUnresolvedVariables> usa a seguinte sintaxe:

Sintaxe

<IgnoreUnresolvedVariables>BOOLEAN_VALUE</IgnoreUnresolvedVariables>

Exemplo

O exemplo a seguir define <IgnoreUnresolvedVariables> como false:

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>

Observação: o valor padrão do elemento é false.

<ThrowExceptionOnLimit>

Especifica o comportamento da política quando o tamanho da variável excede o limite de 256 bytes.

• Se definida como true, a política vai gerar um erro se um tamanho de variável exceder o limite.
• Se definida como false, a política vai truncar a variável que excede o limite. A variável é truncada para o tamanho do limite.

Observação: o valor padrão do elemento é false.

Valor padrão	N/A
Obrigatório?	Opcional
Tipo	Booleano
Elemento pai	<TraceCapture>
Elemento filho	Nenhum

O elemento <ThrowExceptionOnLimit> usa a seguinte sintaxe:

Sintaxe

<ThrowExceptionOnLimit>BOOLEAN_VALUE</ThrowExceptionOnLimit>

Exemplo

O exemplo a seguir define a <ThrowExceptionOnLimit> como true:

<ThrowExceptionOnLimit>false</ThrowExceptionOnLimit>

Códigos de erro

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.