Como usar a ferramenta Trace

Esta é a documentação do Apigee Edge.
Acesse Documentação da Apigee X. informações

O que é a ferramenta Trace?

O Trace é uma ferramenta para solução de problemas e monitoramento de proxies de API em execução no Apigee Edge. Trace permite a sondagem dos detalhes de cada etapa por um fluxo de proxy de 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 ler 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 interface do Edge:

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

   Edge clássico (nuvem privada)

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

   1. Faça login em http://ms-ip:9000, em que ms-ip é o Endereço IP ou 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 foi implantada.
4. Clique em Trace para acessar a visualização da ferramenta Trace.
5. Use o menu suspenso Implantação para rastrear para selecionar quais ambiente de implantação e revisão de proxy que você quer rastrear.
6. Clique em Iniciar sessão de rastreamento. Quando a sessão do Trace está ativa, o proxy de API registra os detalhes de cada etapa do pipeline de processamento. Enquanto a sessão do Trace está em execução, as mensagens e os dados contextuais são capturados do tráfego em tempo real.
   

   

7. Se não houver tráfego em tempo real passando pelo proxy, basta enviar uma solicitação à API. Use a ferramenta que quiser para enviar a solicitação, como curl, Postman ou com qualquer ferramenta conhecida. Também é possível enviar a solicitação diretamente da própria ferramenta Trace. Basta inserir URL e clique em Enviar. Observação: só é possível enviar uma solicitação GET de a ferramenta Trace, mas não uma solicitação POST.
   
   Observação:uma sessão do Trace é compatível com 10 transações de solicitação/resposta por usando o proxy de API selecionado. Na nuvem de borda, com dois processadores de mensagens processamento de tráfego, 20 transações de solicitação/resposta são suportadas. Uma sessão de rastreamento automaticamente será interrompido após 10 minutos se você não interrompê-lo manualmente.
   
8. Quando você capturar um número suficiente de solicitações, clique em Parar rastreamento Sessão.
9. Uma lista de transações de solicitação/resposta capturadas é exibida no menu à esquerda. Clique em qualquer uma as transações para visualizar 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 do 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.

Como refinar a captura de mensagens usando filtros

É possível filtrar quais solicitações aparecem na ferramenta Trace ao especificar o cabeçalho e/ou a consulta valores de parâmetros. Os filtros permitem segmentar chamadas específicas que podem estar causando problemas. Por exemplo, você pode precisar focar em solicitações que tenham conteúdo específico ou solicitações que chegarem de parceiros ou aplicativos específicos. É possível filtrar por:

• Cabeçalhos HTTP: limite o rastreamento somente a chamadas que contenham um cabeçalho. Essa é uma boa maneira de ajudá-lo a resolver problemas. Você pode enviar um cabeçalho para desenvolvedor de aplicativos e peça para ele incluir o nome na chamada que está causando problemas. Em seguida, Apigee Edge só gravará chamadas com esse cabeçalho específico para que você possa examinar os resultados.
• Parâmetros de consulta: somente chamadas com um valor específico de um parâmetro serão gravadas.

O que você precisa saber sobre o recurso Filtro

• É preciso reiniciar sua sessão do Trace depois de especificar os parâmetros no filtro campos.
• Os parâmetros de filtro são unidos por AND. Todos os pares de nome/valor do cabeçalho e/ou consulta especificados deve estar presente na solicitação para uma correspondência bem-sucedida.
• A correspondência de padrões não é suportada na ferramenta Filtros.
• Os parâmetros e valores de filtro diferenciam maiúsculas de minúsculas.

Como criar um trace filtro

1. Se uma sessão de trace estiver em execução, interrompa-a clicando em Stop Trace Sessão.
2. Clique em Filtros no canto superior esquerdo da ferramenta Trace para expandir a 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. Ambos os parâmetros devem ser presentes na solicitação de uma correspondência.
   
   
   
4. Inicie a sessão de rastreamento.
5. Chame suas APIs. Somente solicitações que incluam todos os cabeçalhos e/ou consulta especificados parâmetros produzem uma correspondência bem-sucedida.

No exemplo acima, esta chamada de API aparecerá no Trace:

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

Mas isso não vai:

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.
• Observando os detalhes da fase, é possível verificar os cabeçalhos que estão sendo enviados ao back-end, exibir 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.

Como selecionar opções de exibição

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

Como fazer o download dos resultados do trace

É possível fazer o download de um arquivo XML com resultados de rastreamento brutos para visualização e pesquisa off-line em um texto editor. O arquivo mostra os detalhes completos da sessão de áudio, 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.

Mostrando solicitações como curl

Após rastrear uma chamada de API feita para um servidor de destino, é possível visualizar a solicitação como um curl kubectl. Isso é particularmente útil para depuração por alguns motivos:

• Como o proxy de API pode modificar a solicitação, é útil ver como a solicitação do proxy o servidor de destino é diferente da solicitação original. O comando curl representa o estado solicitação.
• Para payloads de mensagens maiores, o curl permite ver os cabeçalhos e as mensagens HTTP conteúdo em um único lugar. Atualmente,há um limite de aproximadamente 1.000 caracteres. Para uma dica sobre ultrapassar esse limite, consulte nesta postagem na Comunidade.

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

Para conferir as solicitações como curl após receber uma chamada de API no Trace, selecione a opção "Solicitação enviada para servidor de destino" no diagrama do mapa de transações e, em seguida, clique no botão Mostrar curl. em "Solicitação enviada ao servidor de destino" coluna no painel "Detalhes da fase".

Uso do Trace no suporte da Apigee

By default, Apigee Edge allows Apigee Support to use the Trace tool on your API proxies to provide support. You may disable this option at any time. However, disabling this option may limit Apigee Support's ability to provide you with support.

To disable Apigee Support from using the Trace tool:

1. Sign in to https://apigee.com/edge.
2. Select Admin > Privacy & Security in the left navigation bar.
3. Click the Enable Apigee Support to Trace toggle to disable use of the Trace tool by Apigee Support.