Como usar a ferramenta Trace

Você está vendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X.
informações

O que é a ferramenta Trace?

O Trace é uma ferramenta para solucionar problemas e monitorar proxies de API em execução na Apigee Edge. O Trace permite sondagem dos detalhes de cada etapa por meio de um fluxo de proxy de API.

Assista este vídeo para uma introdução à ferramenta Trace.

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 de API usando a interface do Edge:

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

    Borda clássica (nuvem privada)

    Para acessar a página de proxies de 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 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 foi implantada.
  4. Clique em Trace para acessar a visualização da ferramenta Trace.
  5. Use o menu suspenso Implantação no Trace para selecionar qual ambiente de implantação e revisão de proxy 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 no 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 nenhum tráfego em tempo real passando pelo proxy, basta enviar uma solicitação à API. Use a ferramenta que quiser enviar a solicitação, como curl, Postman ou qualquer outra que você já conhece. Também é possível enviar a solicitação diretamente da própria 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 do Trace é compatível com 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 processando o tráfego, são aceitas 20 transações de solicitação/resposta. Uma sessão de rastreamento será interrompida automaticamente após 10 minutos se você não a interromper manualmente.
  8. Quando você tiver capturado um número suficiente de solicitações, clique em Interromper sessão de rastreamento.
  9. Uma lista de transações de solicitação/resposta capturada é exibida no menu à esquerda. Clique em qualquer uma das transações para conferir 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 ao ProxyEndpoint do proxy de 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 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 a 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.

Detalhe da fase Descrição
Endpoint de proxy Indica qual fluxo ProxyEndpoint foi selecionado para execução. Um proxy de API pode ter vários endpoints de proxy com nome.
Variáveis

Lista as variáveis de fluxo que foram lidas e atribuídas a um valor por uma política. Consulte também Como gerenciar o estado do proxy com variáveis de fluxo.

Observação:

  • Um sinal de igual (=) indica o valor atribuído à variável.
  • Um sinal de diferente (≠) indica que não foi possível atribuir um valor à variável porque ela é somente leitura ou ocorreu um erro na execução da política.
  • Um campo vazio indica que o valor da variável foi lido.
Cabeçalhos de solicitação Lista os cabeçalhos da solicitação HTTP.
Conteúdo da solicitação Mostra o corpo da solicitação HTTP.
Propriedades As propriedades representam o estado interno do proxy de API. Eles não são mostrados por padrão.
Endpoint de destino Indica qual TargetEndpoint foi selecionado para execução.
Cabeçalhos de resposta Lista os cabeçalhos de resposta HTTP.
Conteúdo da resposta Mostra o corpo da resposta HTTP.
PostClientFlow Mostra informações sobre o PostClientFlow, que é executado depois que a solicitação é retornada ao app cliente solicitante. Somente as políticas do MessageLogging podem ser anexadas ao PostClientFlow. Atualmente, o PostClientFlow é usado principalmente para medir o intervalo de tempo entre os carimbos de data/hora de início e término da mensagem de resposta.

Como refinar a captura de mensagens usando filtros

É possível filtrar quais solicitações vão aparecer na ferramenta Trace especificando valores de cabeçalho e/ou parâmetro de consulta. Os filtros permitem segmentar chamadas específicas que podem estar causando problemas. Por exemplo, talvez seja necessário se concentrar nas solicitações com conteúdo específico ou provenientes de parceiros ou apps específicos. É possível filtrar por:

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

Informações importantes sobre o recurso Filtro

  • É necessário reiniciar sua sessão do Trace 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 nome/valor de consulta e/ou cabeçalho especificados precisam estar presentes na solicitação para que a correspondência seja bem-sucedida.
  • A ferramenta Filtros não oferece suporte a correspondência de padrões.
  • Os valores e parâmetros de filtro diferenciam maiúsculas de minúsculas.

Como criar um filtro de trace

  1. Se uma sessão de rastreamento estiver em execução, clique em Stop Trace Session para interrompê-la.
  2. Clique em Filtros no canto superior esquerdo da ferramenta Trace para expandir o campo "Filtros".

    Na ferramenta de rastreamento, o rótulo da barra lateral "Filtros" aparece dentro de um círculo.
  3. No campo "Filtros", especifique o parâmetro de consulta e/ou os valores do 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 que a correspondência seja bem-sucedida.

    Na ferramenta Trace, em "Filtros", em "Parâmetro de consulta", são definidos dois nomes e valores de
     exemplo.
  4. Inicie a sessão de rastreamento.
  5. Chame as APIs. Somente as solicitações que incluem todos os cabeçalhos e/ou parâmetros de consulta especificados produzem uma correspondência bem-sucedida.

Em "Transações", são exibidos quatro resultados que correspondem a dois parâmetros de consulta predefinidos.

No exemplo acima, a chamada de API será exibida no Trace:

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

No entanto, 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. Exemplo:

  • É possível conferir rapidamente quais políticas estão sendo executadas corretamente ou com 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 pelas 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 as opções de exibição

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

Opção Descrição
Mostrar políticas desativadas Mostrar todas as políticas desativadas. Uma política pode ser desativada com a API pública. Consulte Referência de configuração do proxy da API.
Mostrar fases ignoradas Mostra as fases ignoradas. Uma fase ignorada ocorre 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.
Mostrar todos os FlowInfos Representa transições em um segmento de fluxo.
Comparar automaticamente a fase selecionada Compara a fase selecionada com a anterior. Desative esta opção para ver somente a fase selecionada.
Exibir variáveis Exibe ou oculta variáveis que foram lidas e/ou que receberam um valor.
Mostrar propriedades As propriedades representam o estado interno do proxy de API. (Oculta por padrão.)

Como fazer o download dos resultados de rastros

Você pode fazer o download de um arquivo XML com resultados de rastreamento brutos para visualizar e pesquisar off-line em um editor de texto. O arquivo mostra todos os detalhes da sessão de detecção, incluindo o conteúdo de 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

Depois de rastrear uma chamada de API feita para um servidor de destino, visualize a solicitação como um comando curl. Isso é particularmente ú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, use o curl para ver os cabeçalhos HTTP e o conteúdo da mensagem em um único lugar. Há um limite de cerca de 1.000 caracteres. Para ver uma dica sobre como ultrapassar esse limite, consulte esta postagem na Comunidade.

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

Para ver as solicitações como curl após uma chamada de API chegar no Trace, selecione o estágio "Solicitação enviada ao servidor de destino" no diagrama do mapa de transações e clique no botão Mostrar curl na coluna "Solicitação enviada ao servidor de destino" no painel "Stage Details".

As anotações de imagem destacam o botão "Mostrar curl" e um dos círculos no
    diagrama do mapa de transações.

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.