Esta página se aplica à Apigee e à Apigee híbrida.
Confira a documentação da
Apigee Edge.
Visão geral
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 Opcionalmente, use o elemento |
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:
|
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>
<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 da API. |
<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>
<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.
| 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>true:
<ThrowExceptionOnLimit>false</ThrowExceptionOnLimit>
Códigos de erro
Esta seção descreve os códigos de falha e as mensagens de erro que são retornadas e as variáveis de falha definidas pela Apigee quando essa política aciona um erro. Essas informações são importantes para saber se você está desenvolvendo regras de falha para lidar com falhas. Para saber mais, consulte O que você precisa saber sobre erros de política e Como lidar com falhas.
Erros de execução
Esses erros podem ocorrer quando a política é executada.
| Código de falha | Status HTTP | Causa |
|---|---|---|
steps.tracecapture.UnresolvedVariable |
500 |
Esse erro ocorrerá se uma variável especificada na política TraceCapture estiver:
|
steps.tracecapture.VariableValueLimitExceeded |
500 |
Esse erro ocorrerá se o elemento |
Variáveis de falha
Sempre que houver erros de execução em uma política, a Apigee gerará mensagens de erro. Essas mensagens de erro podem ser visualizadas na resposta de erro. Muitas vezes, as mensagens de erro geradas pelo sistema podem não ser relevantes no contexto do produto. Personalize as mensagens de erro com base no tipo específico para torná-las mais úteis.
Para personalizar as mensagens de erro, use regras de falha ou a política RaiseFault. Para
informações sobre as diferenças entre as regras de falha e a política RaiseFault, consulte
FaultRules vs. a política RaiseFault.
Verifique as condições usando o elemento Condition nas regras de falha e na política RaiseFault.
A Apigee fornece variáveis de falha exclusivas para cada política, e os valores das variáveis de falha são definidos quando uma política aciona erros de ambiente de execução.
Ao usar essas variáveis, é possível verificar se há condições de erro específicas e agir conforme adequado. Para mais informações sobre como verificar condições de
erro, consulte Como criar condições.
A tabela a seguir descreve as variáveis de falha específicas da política.
| Variáveis | Onde | Exemplo |
|---|---|---|
fault.name |
O fault.name pode corresponder a qualquer uma das falhas listadas na tabela Erros de ambiente de execução.
O nome da falha é a última parte do código de falha. |
fault.name Matches "UnresolvedVariable" |
tracecapture.POLICY_NAME.failed |
POLICY_NAME é o nome da política especificada pelo usuário que gerou a falha. | tracecapture.trace-capture-1.failed = true |