Como usar a ferramenta Trace

Você está lendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X. info

O que é a ferramenta Trace?

O Trace é uma ferramenta de solução de problemas e monitoramento de proxies de API em execução no Apigee Edge. O Trace permite testar os detalhes de cada etapa por meio de um fluxo de proxy da API.

Como usar o Trace

O Trace é simples de usar. Você inicia uma sessão de rastreamento, faz uma chamada de API para a plataforma Edge e lê os resultados.

1. Acesse a página Proxies de API, conforme descrito abaixo.
   

   Edge

   Para acessar a página de proxies da API usando a IU do Edge:

   1. Faça login em apigee.com/edge.
   2. Selecione Develop > API Proxies na barra de navegação à esquerda.

   Classic Edge (nuvem privada)

   Para acessar a página de proxies de API usando a IU clássica do Edge:

   1. Faça login em http://ms-ip:9000, em que ms-ip é o endereço IP ou o nome DNS do nó do servidor de gerenciamento.
   2. Selecione APIs > Proxies de API na barra de navegação superior.
2. Selecione um proxy de API na página "Proxies de API".
3. Verifique se a API que você quer rastrear está implantada.
4. Clique em Trace para acessar a visualização da ferramenta Trace.
5. Use o menu suspenso Implantação para rastreamento para selecionar o ambiente de implantação e a revisão de proxy que você quer rastrear.
6. Clique em Iniciar sessão de Trace. Quando a sessão de trace está ativa, o proxy de API registra detalhes de cada etapa no pipeline de processamento. Enquanto a sessão de rastreamento está em execução, mensagens e dados contextuais são capturados do tráfego em tempo real.
   

   

7. Se não houver tráfego ativo passando pelo proxy, basta enviar uma solicitação para a API. Use a ferramenta que quiser para enviar a solicitação, como curl, Postman ou qualquer ferramenta conhecida. Ou envie a solicitação diretamente da ferramenta Trace. Basta inserir o URL e clicar em Enviar. Observação:só é possível enviar uma solicitação GET da ferramenta Trace, mas não uma solicitação POST.
   
   Observação:uma sessão de rastreamento pode oferecer suporte a 10 transações de solicitação/resposta por processador de mensagens usando o proxy de API selecionado. Na nuvem de borda, com dois processadores de mensagens lidando com o tráfego, 20 transações de solicitação/resposta são compatíveis. Uma sessão de rastreamento é interrompida automaticamente após 10 minutos, a menos que você a interrompa manualmente.
   
8. Quando você tiver capturado um número suficiente de solicitações, clique em Interromper sessão de Trace.
9. Uma lista de transações de solicitação/resposta capturadas aparece no menu à esquerda. Clique em qualquer uma das transações para ver os resultados detalhados.

Como ler um trace

A ferramenta de trace tem duas partes principais: o mapa de transações e os detalhes da fase:

• O mapa de transações usa ícones para marcar cada etapa notável que ocorre durante uma transação de proxy da API, incluindo execução de políticas, etapas condicionais e transições. Passe o cursor sobre qualquer ícone para ver informações resumidas. As etapas do fluxo de solicitação aparecem na parte superior do mapa de transações e nas etapas do fluxo de resposta na parte inferior.
• A seção de detalhes da fase da ferramenta lista informações sobre o processamento interno do proxy, incluindo variáveis que foram definidas ou lidas, os cabeçalhos de solicitação e resposta, entre outros. Clique em qualquer ícone para ver os detalhes da fase dessa etapa.

Este é um exemplo de mapa de ferramentas de trace com os principais segmentos de processamento de proxy rotulados:

Mapa de transações da ferramenta de trace

Legenda do mapa de transações

A tabela a seguir descreve a intenção dos ícones que você verá no mapa de transações. Esses ícones marcam cada uma das etapas de processamento notáveis durante o fluxo do proxy.

Ícones de mapa de transações

	O app cliente que envia uma solicitação para o ProxyEndpoint do proxy da API.
	Os círculos marcam os endpoints transicionais no fluxo de proxy. Eles aparecem quando uma solicitação é enviada pelo cliente, quando a solicitação vai para o destino, quando a resposta volta do destino e quando a resposta volta para o cliente.
	As barras altas indicam o início de um segmento de fluxo no fluxo do proxy de API. Os segmentos de fluxo são: solicitação de ProxyEndpoint, solicitação de TargetEndpoint, resposta de TargetEndpoint e resposta ProxyEndpoint. Um segmento inclui o PreFlow, fluxos condicionais e PostFlow. Consulte Como configurar fluxos para mais informações.
	Indica que as ações do Google Analytics ocorreram em segundo plano.
	Um fluxo condicional que gera o valor "true". Para uma introdução sobre os fluxos condicionais, consulte Como configurar fluxos. Algumas condições são geradas pelo Edge. Por exemplo, esta é uma expressão que o Edge usa para verificar se ocorreu um erro no ProxyEndpoint: ((error.state equals PROXY_REQ_FLOW) or (error.state equals PROXY_RESP_FLOW))
	Um fluxo condicional que gera o valor "false". Para uma introdução sobre os fluxos condicionais, consulte Como configurar fluxos. Algumas condições são geradas pelo Edge. Por exemplo, a expressão a seguir é uma expressão que o Edge usa para verificar se ocorreu um erro no TargetEndpoint: (((error.state equals TARGET_REQ_FLOW) or (error.state equals TARGET_RESP_FLOW)) or ((error.state equals REQ_SENT) or (error.state equals RESP_START)))
	Políticas. Cada tipo de política tem um ícone exclusivo. Este é para à política AssignMessage". Esses ícones permitem ver onde as políticas são executadas na ordem correta e se são bem-sucedidas ou não. Clique no ícone de uma política para ver os resultados da execução e se eles são esperados ou não. Por exemplo, é possível ver se a mensagem foi transformada corretamente ou se está sendo armazenada em cache. As políticas de execução adequada são claramente indicadas pelas marcas de verificação. No caso de um erro, um ponto de exclamação vermelho é exibido no ícone. Dica: preste atenção à dica ou ao cronograma para ver se alguma política está demorando mais que o esperado.
	Aparece quando o destino de back-end é um aplicativo Node.js. Consulte Visão geral do Node.js no Apigee Edge.
	O destino do back-end chamado pelo proxy de API.
	O cronograma indica quanto tempo (em milissegundos) o tempo de processamento levou para ser concluído. A comparação dos segmentos de tempo decorrido ajuda a isolar as políticas que estão demorando mais para serem executadas e atrasando as chamadas de API.
	O Epsilon indica um período menor que um milésimo de segundo.
	Desativada. Aparece em um ícone de política quando uma política é desativada. Uma política pode ser desativada com a API pública. Consulte Referência de configuração do proxy da API.
	Erro. Aparece em um ícone de política quando a condição da etapa da política é avaliada como "false" (consulte Variáveis e condições do fluxo) ou no ícone da política RaiseFault quando uma política RaiseFault é executada.
	Ignorada. Aparece em um ícone de política quando a política não foi executada porque a condição da etapa foi avaliada como "false". Consulte Variáveis e condições de fluxo para mais informações.

Noções básicas sobre os detalhes da fase

A parte Detalhes da fase da ferramenta informa muito sobre o estado do proxy em cada etapa do processamento. Veja alguns detalhes na seção "Detalhes da fase". Clique em qualquer ícone na ferramenta de trace para ver os detalhes da etapa selecionada ou use os botões Próximo/Voltar para ir de uma etapa a outra.

Refinar a captura de mensagens usando filtros

É possível filtrar quais solicitações aparecem na ferramenta Trace especificando valores de cabeçalho e/ou parâmetro de consulta. Com os filtros, você pode segmentar chamadas específicas que podem estar causando problemas. Por exemplo, você pode precisar se concentrar em solicitações com conteúdo específico ou que vêm de parceiros ou apps específicos. É possível filtrar por:

• Cabeçalhos HTTP: limita o trace apenas a chamadas que contêm um cabeçalho específico. Essa é uma boa maneira de ajudar você a resolver problemas. Envie um cabeçalho ao desenvolvedor do app e peça para ele incluir na chamada que está causando problemas. Assim, o Apigee Edge vai registrar apenas chamadas com esse cabeçalho específico para que você possa analisar os resultados.
• Parâmetros de consulta: somente chamadas com um valor específico de um parâmetro serão registradas.

O que você precisa saber sobre o recurso de filtro

• É necessário reiniciar a sessão de rastreamento depois de especificar os parâmetros de filtro nos campos de filtro.
• Os parâmetros de filtro são unidos por AND. Todos os pares de consulta e/ou nome/valor de cabeçalho especificados precisam estar presentes na solicitação para uma correspondência bem-sucedida.
• A correspondência de padrões não é compatível com a ferramenta "Filtros".
• Os parâmetros e valores de filtro diferenciam maiúsculas de minúsculas.

Como criar um filtro de rastreamento

1. Se uma sessão de rastreamento estiver em execução, clique em Interromper sessão de rastreamento.
2. Clique em Filtros no canto superior esquerdo da ferramenta Rastreamento para expandir o campo "Filtros".
   
   
   
3. No campo "Filtros", especifique o parâmetro de consulta e/ou os valores de cabeçalho que você quer filtrar. Neste exemplo, especificamos dois parâmetros de consulta para filtrar. Os dois parâmetros precisam estar presentes na solicitação para uma correspondência bem-sucedida.
   
   
   
4. Inicie a sessão de rastreamento.
5. Chame suas APIs. Somente as solicitações que incluem todos os cabeçalhos e/ou parâmetros de consulta especificados produzem uma correspondência bem-sucedida.

No exemplo acima, essa chamada de API vai aparecer no rastreamento:

http://docs-test.apigee.net/cats?name=Penny&breed=Calico

Mas isso não vai acontecer:

http://docs-test.apigee.net/cats?name=Penny

Como depurar com o Trace

O Trace permite ver muitos detalhes internos sobre um proxy de API. Por exemplo:

• Veja rapidamente quais políticas estão sendo executadas corretamente ou apresentando falha.
• Digamos que você tenha visto em um dos painéis do Google Analytics que uma das suas APIs apresenta uma redução incomum no desempenho. Agora, use o Trace para ajudar a identificar onde o gargalo está ocorrendo. O Trace fornece o tempo, em milissegundos, que cada etapa de processamento leva para ser concluída. Se você perceber que uma etapa está demorando muito, será possível realizar a ação corretiva.
• Ao analisar os detalhes da fase, é possível verificar os cabeçalhos que estão sendo enviados para o back-end, visualizar as variáveis definidas por políticas e assim por diante.
• Ao verificar o caminho base, é possível garantir que uma política esteja encaminhando a mensagem para o servidor correto.

Selecionar opções de visualização

Escolha as opções de visualização para a sessão de trace.

Baixando resultados de trace

É possível fazer o download de um arquivo XML de resultados de traces brutos para visualização e pesquisa off-line em um editor de texto. O arquivo mostra todos os detalhes da sessão de escuta, incluindo o conteúdo de todos os cabeçalhos, variáveis e políticas.

Para fazer o download, clique em Fazer o download da sessão de trace.

Mostrar solicitações como curl

Depois de rastrear uma chamada de API feita a um servidor de destino, é possível ver a solicitação como um comando curl. Isso é especialmente útil para depuração por alguns motivos:

• O proxy de API pode modificar a solicitação. Por isso, é útil ver como a solicitação do proxy para o servidor de destino difere da solicitação original. O comando curl representa a solicitação modificada.
• Para payloads de mensagens maiores, o curl permite ver os cabeçalhos HTTP e o conteúdo da mensagem em um só lugar. No momento,há um limite de cerca de 1.000 caracteres. Para uma dica sobre como ultrapassar esse limite, consulte esta postagem da comunidade.

Por motivos de segurança, o recurso curl mascara o cabeçalho de autorização HTTP.

Para ver as solicitações como curl depois que uma chamada de API é feita no rastreamento, selecione a etapa "Solicitação enviada para o servidor de destino" no diagrama do mapa de transações e clique no botão Mostrar curl na coluna "Solicitação enviada para o servidor de destino" no painel "Detalhes da fase".

Uso do Trace no suporte da Apigee

Por padrão, o Apigee Edge permite que o suporte da Apigee use a ferramenta Trace nos proxies de API para fornecer suporte. Você pode desativar essa opção a qualquer momento. No entanto, desativar essa opção pode limitar a capacidade do suporte da Apigee de oferecer suporte a você.

Para impedir que o suporte da Apigee use a ferramenta Trace:

1. Faça login em https://apigee.com/edge.
2. Selecione Administrador > Privacidade e segurança na barra de navegação à esquerda.
3. Clique no botão Ativar suporte da Apigee ao Trace para desativar o uso da ferramenta Trace pelo suporte da Apigee.