Como usar a depuração

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

Confira a documentação da Apigee Edge.

Esta seção descreve como criar e gerenciar sessões de depuração e ver os dados de solicitação e resposta usando a API e a interface da Apigee.

Use a opção Debug Offline para visualizar e analisar as sessões de depuração que foram transferidas por download anteriormente.

Como criar uma sessão de depuração

A ferramenta de depuração é simples de usar. Inicie uma sessão de depuração, faça uma chamada de API para a Apigee e veja os dados de solicitação e resposta na UI.

Crie uma sessão de depuração com a interface ou a API da Apigee, conforme descrito nas seções a seguir.

Observação:há um atraso de aproximadamente 15 segundos entre o início de uma sessão de depuração e a ativação dela na Apigee. Isso pode causar perda de solicitações de API nos primeiros 15 a 20 segundos de uma sessão de depuração.

Observação:a ferramenta de depuração está disponível na interface da Apigee. Algumas ações de depuração também podem ser realizadas usando a API.

IU da Apigee

Para criar uma sessão de depuração:

1. No console do Google Cloud , acesse a página Apigee > Desenvolvimento de proxy > Proxies de API.

   Acessar proxies de API

2. Selecione o proxy de API que você quer depurar. Isso exibirá o painel Visão geral do Editor de proxy.
3. Clique na guia Depurar.
4. Clique em Iniciar sessão de depuração. O painel Iniciar sessão de depuração será exibido.

5. No painel Iniciar sessão de depuração:

   1. Selecione o Ambiente em que você quer executar a sessão de depuração.

   2. Opcional: na lista suspensa Filtrar, selecione um filtro a ser aplicado a todas as transações na sessão de depuração que você está criando. O padrão é None (All transactions), que inclui todas as transações nos dados de depuração.

      Para informações sobre o uso de filtros, consulte Como usar filtros em uma sessão de depuração. Para informações sobre os filtros integrados, consulte Como usar filtros predefinidos.

   3. Clique em Iniciar.

A IU da Apigee agora exibe o painel Sessão de depuração em andamento.

A sessão de depuração registra solicitações por 10 minutos ou até que 15 solicitações tenham sido capturadas. É possível ajustar o limite de 10 minutos se você criar a sessão de depuração usando a API. O campo Termina em exibe o tempo restante da sessão.

Nenhuma informação será exibida no painel de depuração até que você envie uma solicitação ao proxy que está depurando no ambiente selecionado para a sessão de depuração.

Depois de enviar a solicitação, ela será exibida no painel de lista Transações. A lista Transações é atualizada a cada cinco segundos.

Para ver ou copiar a saída da transação:

1. Na lista Transações, clique em Ver saída da transação. O painel Saída da transação é exibido.
2. Clique em uma transação individual ou em Todas as transações.
3. Clique em Copiar para copiar a saída da transação para a área de transferência.
4. Clique em Fechar.

Observação:durante uma sessão de depuração ativa, é possível iniciar outra sessão na IU da Apigee. Consulte Como iniciar outra sessão de depuração na IU.

API

Para criar uma sessão de depuração usando a API, emita uma solicitação POST para o seguinte recurso:

https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/apis/$API/revisions/$REV/debugsessions

Também é possível:

• Defina a duração de uma sessão de depuração (em segundos) passando a propriedade timeout como um parâmetro de consulta ou no corpo da solicitação. Se ambos forem especificados, o valor timeout especificado no corpo da solicitação terá precedência.
• Filtre os dados em uma sessão de depuração transmitindo a propriedade filter no corpo da solicitação.

O exemplo a seguir demonstra como criar uma sessão de depuração usando a API.

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/apis/PROXY/revisions/REV/debugsessions" \
      -X POST \
      -H "Authorization: Bearer $TOKEN"
    

Em que $TOKEN está definido como seu token de acesso OAuth 2.0, conforme descrito em Como receber um token de acesso OAuth 2.0. Para informações sobre as opções de curl usadas neste exemplo, consulte Como usar curl. Para uma descrição das variáveis de ambiente que podem ser usadas, consulte Como definir variáveis de ambiente para solicitações de API da Apigee.

Veja a seguir um exemplo de resposta:

{
      "name":"56382416-c4ed-4242-6381-591bbf2788cf",
      "validity":300,
      "count":10,
      "tracesize":5120,
      "timeout":"600"
    }

As solicitações subsequentes para o proxy de API (até que a duração da sessão ou o número máximo de solicitações seja atingido) serão avaliadas e possivelmente armazenadas nos dados da sessão de depuração.

Para mais informações, consulte Criar API de sessão de depuração.

Como configurar a duração de uma sessão de depuração usando a API

Para definir a duração de uma sessão de depuração usando a API, inclua o seguinte como um payload na solicitação de criação da sessão de depuração:

{
      "timeout":"debug_session_length_in_seconds"
    }

O exemplo a seguir cria uma sessão de depuração com apenas 42 segundos de duração:

curl https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/apis/PROXY/revisions/REV/debugsessions"
      -X "POST" \
      -H "Authorization: Bearer $TOKEN" \
      -d ' {
        "timeout":"42"
      } '

Só é possível definir o timeout de uma sessão em solicitações de criação de sessão de depuração. Não é possível alterar a duração de uma sessão depois que ela é criada.

O valor padrão de timeout é 300 (cinco minutos). O valor máximo é de 600 segundos (10 minutos).

Copiar o URL do proxy

O URL do proxy é usado para enviar solicitações ao proxy de API.

Para encontrar e copiar o URL do proxy:

1. No painel Sessão de depuração, campo URL, clique em Copiar.
2. Se uma sessão de depuração não estiver aberta:

   1. No console do Google Cloud , acesse a página Apigee > Gerenciamento > Ambientes > Grupos de ambientes.

      Acessar Grupos de ambientes

   2. O URL é o Nome do host do respectivo ambiente em que você quer executar a sessão de depuração. Selecione e copie o código.

Para selecionar um URL de proxy diferente:

1. No painel Sessão de depuração, campo URL, clique em Editar.
2. Faça as mudanças que quiser e clique em Atualizar.
3. Se uma sessão de depuração não estiver aberta:
   1. Encontre o URL do proxy.
   2. Clique em Mais e em Editar.
   3. Faça as mudanças que quiser e clique em Atualizar.

Como iniciar outra sessão de depuração na IU

É possível criar qualquer número de sessões de depuração na IU.

Durante uma sessão de depuração ativa, é possível iniciar outra sessão na IU da Apigee. Para fazer isso, clique em Fechar no painel Sessão de depuração:

A IU retorna ao painel Iniciar uma sessão do Debug, onde é possível iniciar uma nova sessão de depuração.

Quando uma sessão de depuração termina?

Não é possível simplesmente interromper uma sessão de depuração ativa. No entanto, é possível excluir os dados de uma sessão ativa, conforme descrito em Como excluir dados de uma sessão de depuração.

Ao criar uma sessão de depuração, duas propriedades determinam quando ela termina:

• tempo limite: o tempo de coleta de dados durante uma sessão. A duração padrão depende de como você iniciou a sessão (por meio da IU ou da API). O valor máximo é de 600 segundos (ou 10 minutos).
  Dica:não é possível configurar o tempo limite ao criar uma nova sessão de depuração com a interface da Apigee. No entanto, é possível definir o tempo limite ao criar uma nova sessão de depuração usando a API.
• Contagem: o número máximo de solicitações registradas em uma única sessão para cada processador de mensagens. Como o número de processadores de mensagens na maioria dos clusters é variável, os efeitos da contagem podem ser imprevisíveis. A Apigee não recomenda personalizar essa configuração.

Quando o tempo limite ou a contagem são atingidos, a sessão de depuração para esse processador de mensagens termina.

Os termos a seguir são usados para descrever o estado de uma sessão de depuração:

• sessão ativa é uma sessão de depuração que ainda não atingiu o tempo limite ou excedeu a contagem. Uma sessão ativa ainda está registrando dados de solicitações que não são filtradas.
• sessão concluída é uma sessão de depuração que atingiu o tempo limite ou excedeu a contagem. Uma sessão concluída não registra mais dados sobre novas solicitações, e os dados dela são excluídos em até 24 horas após o término da sessão.

Como ler uma sessão de depuração

Nesta seção, apresentamos uma visão geral de uma sessão de depuração.

Consulte também:

• Painel de transações
• Legenda do painel de transações
• Painel de detalhes da fase

A ferramenta de depuração tem duas partes principais: o painel de transações e os detalhes da fase:

• O painel de transações usa ícones para marcar cada etapa notável que ocorre durante uma transação de proxy de 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 de cima do mapa de transações, e as etapas do fluxo de resposta aparecem na parte de baixo.
• O painel detalhes da fase lista informações sobre o processamento interno do proxy, incluindo variáveis que foram definidas ou lidas, cabeçalhos de solicitação e cabeçalhos de resposta e muito mais. Clique em qualquer ícone para ver os detalhes da fase dessa etapa.

Painel de transações

O painel de transações mostra as etapas da solicitação e da resposta.

Veja um exemplo de painel de transações da ferramenta de depuração com os principais segmentos de processamento de proxy rotulados:

Legenda do painel de transações

Veja a seguir os ícones no painel de transações:

Esta seção descreve os ícones no painel de transações:

• Ícones de política
• Outros ícones

Ícones de política

Cada tipo de política tem um ícone exclusivo. Esses ícones mostram onde as políticas são executadas na ordem correta e se elas foram bem-sucedidas ou não. Clique em um ícone de política para ver os resultados da execução e se eles são os 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 padrão aprimoram suas APIs para controlar o tráfego, melhorar o desempenho, aplicar a segurança e aumentar a utilidade delas, sem exigir que você escreva nenhum código ou modifique serviços de back-end.

As políticas extensíveis permitem adicionar lógica personalizada aos proxies de API. Use essas políticas para adicionar funcionalidades que não são fornecidas pelas políticas padrão.

Consulte Visão geral de referência da política para mais informações sobre políticas e categorias.

Para filtrar a tabela:

• Selecione um tipo e/ou uma categoria de política.
• Clique no cabeçalho da coluna Nome para classificar a tabela por nome de política.
• Digite uma palavra-chave para pesquisar o nome de uma política.

Tipo de política Standard Extensível

Categoria da política IA Fluxo de diálogo Extensão Mediação Segurança Gerenciamento de tráfego

Ícone	Nome	Tipo	Categoria
	Política LLMTokenQuota	Extensível	AI
chat_spark	Política PromptTokenLimit	Extensível	AI
shield_spark	Política SanitizeUserPrompt	Extensível	AI
shield_spark	Política SanitizeModelResponse	Extensível	AI
async	Política SemanticCacheLookup	Extensível	AI
async	Política SemanticCachePopulate	Extensível	AI
manage_search	Política ParseDialogflowRequest	Extensível	Fluxo de diálogo
chat_add_on	Política SetDialogflowResponse	Extensível	Fluxo de diálogo
stacked_line_chart	Política DataCapture	Extensível	Extensão
display_external_input	Política ExternalCallout	Padrão	Extensão
flowsheet	Política FlowCallout	Extensível	Extensão
automação	Política IntegrationCallout	Extensível	Extensão
	Política JavaCallout	Extensível	Extensão
	Política de JavaScript	Extensível	Extensão
add_notes	Política MessageLogging	Extensível	Extensão
chat_paste_go	Política PublishMessage	Padrão	Extensão
	Política PythonScript	Extensível	Extensão
integration_instructions	Política ServiceCallout	Extensível	Extensão
automação	Política SetIntegrationRequest	Extensível	Extensão
waterfall_chart	Política de TraceCapture	Extensível	Extensão
cloud_done	Política AccessEntity	Extensível	Mediação
account_tree	Política AssertCondition	Padrão	Mediação
edit_square	Política AssignMessage	Extensível	Mediação
login	Política ExtractVariables	Extensível	Mediação
	Política GraphQL	Padrão	Mediação
sync_alt	Política HTTPModifier	Padrão	Mediação
sync_alt	Política JSONtoXML	Padrão	Mediação
account_tree	Política KeyValueMapOperations	Extensível	Mediação
sync_alt	Política MonetizationLimitsCheck	Extensível	Mediação
cloud_done	Política OASValidation	Padrão	Mediação
report	Política RaiseFault	Padrão	Mediação
sync_alt	Política ReadPropertySet	Padrão	Mediação
cloud_done	Política SOAPMessageValidation	Padrão	Mediação
sync_alt	Política XMLtoJSON	Padrão	Mediação
cloud_done	Política XSLTransform	Extensível	Mediação
lock	Política AccessControl	Padrão	Segurança
segurança	Política BasicAuthentication	Extensível	Segurança
connect_without_contact	Política de CORS	Padrão	Segurança
lock	Política DecodeJWS	Extensível	Segurança
lock	Política DecodeJWT	Padrão	Segurança
chave de acesso	Política DeleteOAuthV2Info	Extensível	Segurança
lock	Política GenerateSamlAssertion	Extensível	Segurança
lock	Política GenerateJWS	Extensível	Segurança
lock	Política GenerateJWT	Extensível	Segurança
chave de acesso	Política GetOAuthV2Info	Extensível	Segurança
lock	Política HMAC	Padrão	Segurança
segurança	Política JSONThreatProtection	Extensível	Segurança
chave de acesso	Política do OAuthV2	Extensível	Segurança
segurança	Política RegularExpressionProtection	Extensível	Segurança
chave de acesso	Política RevokeOAuthV2	Extensível	Segurança
chave de acesso	Política SetOAuthV2Info	Extensível	Segurança
lock	Política ValidateSamlAssertion	Extensível	Segurança
key	Política VerifyAPIKey	Extensível	Segurança
chave de acesso	Política VerifyIAM	Extensível	Segurança
lock	Política VerifyJWS	Extensível	Segurança
lock	Política VerifyJWT	Padrão	Segurança
segurança	Política XMLThreatProtection	Extensível	Segurança
em cache	Política InvalidateCache	Extensível	Gerenciamento de tráfego
em cache	Política LookupCache	Extensível	Gerenciamento de tráfego
em cache	Política PopulateCache	Extensível	Gerenciamento de tráfego
	Política de cotas	Extensível	Gerenciamento de tráfego
repartition	Política ResetQuota	Extensível	Gerenciamento de tráfego
em cache	Política ResponseCache	Extensível	Gerenciamento de tráfego
emergency_home	Política SpikeArrest	Padrão	Gerenciamento de tráfego

Outros ícones

A tabela a seguir descreve a finalidade dos outros ícones que você verá no painel de transações. Esses ícones marcam cada uma das etapas de processamento notáveis em todo o fluxo do proxy.

Para filtrar a tabela:

• Selecione um tipo de ícone.
• Clique no cabeçalho da coluna Nome para classificar a tabela por nome de ícone.
• Digite uma palavra-chave para pesquisar o nome de um ícone.

Tipo de ícone Transação padrão Status da etapa

Ícone	Nome	Tipo	Descrição
monitor	Aplicativo cliente	Transação padrão	O app cliente que envia uma solicitação ao ProxyEndpoint do proxy de API.
circle	Endpoint de transição	Transação padrão	O círculo marca os endpoints de transição no fluxo de proxy. Eles estão presentes quando uma solicitação chega do cliente, quando a solicitação vai para o destino, quando a resposta volta do destino e quando a resposta volta para o cliente.
stat_0	Segmento de fluxo	Transação padrão	O losango indica 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 de ProxyEndpoint. Um segmento inclui o PreFlow, os fluxos condicionais e o PostFlow. Consulte Fluxos condicionais para mais informações.
	Fluxo condicional verdadeiro	Transação padrão	Um fluxo condicional que é avaliado como verdadeiro (como uma instrução if avaliada como true). Para uma introdução aos fluxos condicionais, consulte Fluxos condicionais. Algumas condições são geradas pelo Apigee. Por exemplo, esta é uma expressão que a Apigee usa para verificar se ocorreu um erro no ProxyEndpoint: ((error.state equals PROXY_REQ_FLOW) or (error.state equals PROXY_RESP_FLOW))
	Fluxo condicional falso	Transação padrão	Um fluxo condicional que gera o valor "false". Para uma introdução aos fluxos condicionais, consulte Fluxos condicionais. Algumas condições são geradas pelo Apigee. Por exemplo, veja a seguir uma expressão que a Apigee 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)))
	Informações do fluxo	Transação padrão	Representa informações contextuais sobre a execução do proxy de API, que varia de acordo com o ponto no fluxo. Isso inclui detalhes sobre a configuração do proxy, o estado de execução atual (por exemplo, PreFlow, PostFlow, hooks de fluxo), detalhes de execução da política e variáveis preenchidas durante a execução da política, para indicar o estado específico do proxy naquele momento.
done_all	Execução do fluxo	Transação padrão	Marca o início ou o fim da execução de um fluxo, indicando o período de um segmento de fluxo distinto, para demarcar visualmente os limites do fluxo e indicar a sequência de execução do fluxo.
commit	Processamento do fluxo	Transação padrão	Indica o processamento ativo em um fluxo, representando o período em que as políticas e a lógica do fluxo são executadas.
bar_chart	Dados capturados pela análise da Apigee	Transação padrão	Indica que as ações do Analytics ocorreram em segundo plano.
location_on	Serviço de back-end	Transação padrão	Serviço de back-end que recebe a solicitação. O destino do back-end chamado pelo proxy de API.
	Desativado	Status da etapa	Aparece em um ícone de política quando uma política é desativada. Uma política pode ser desativada com a API pública. Consulte a referência de configuração do proxy de API.
	Erro	Status da etapa	Aparece em um ícone de política quando a condição de etapa da política é avaliada como "false" (consulte Condições com variáveis de fluxo) ou no ícone da política RaiseFault quando uma política RaiseFault é executada.
	Ignorado	Status da etapa	Aparece em um ícone de política quando a política não foi executada porque a condição de etapa foi avaliada como falsa. Consulte Condições com variáveis de fluxo para mais informações.

Painel de detalhes da fase

O painel de detalhes da fase informa o estado do proxy em cada etapa de processamento.

O painel de detalhes da fase informa muito sobre o estado do proxy em cada etapa de processamento. Confira alguns dos detalhes fornecidos. Clique em qualquer ícone na ferramenta de depuração para ver detalhes da etapa selecionada ou use os botões > Próxima ou < Anterior para passar de uma etapa para outra.

Aviso:a depuração captura o conteúdo da mensagem. Se os payloads de mensagens tiverem informações sensíveis, ative o mascaramento de dados. Para instruções, consulte Como mascarar e ocultar dados.

A tabela a seguir descreve os detalhes fornecidos no painel de detalhes da fase.

Detalhe da fase	Descrição
Variáveis	Lista as variáveis de fluxo que foram lidas e receberam um valor de uma política. Consulte também Como usar variáveis de fluxo. Observação: Um sinal de igual (=) indica o valor que foi atribuído à variável. Um sinal de igual riscado (≠) indica que não foi possível atribuir um valor à variável porque ela é somente leitura ou houve 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.

Cronograma

A linha do tempo indica quanto tempo (em milissegundos) o tempo de processamento levou para ser concluído. Comparar os segmentos de tempo decorrido ajuda a isolar as políticas que estão demorando mais para serem executadas e que estão deixando as chamadas de API mais lentas.

O Epsilon indica um período menor que um milésimo de segundo.

Como abrir e fechar grupos

Nesta seção, descrevemos como expandir e fechar grupos no painel "Transaction".

As etapas da transação, tanto para solicitação quanto para resposta, são agrupadas de acordo com como foram configuradas anteriormente na guia Desenvolver, por fluxo compartilhado. Por exemplo: pré-proxy, pós-proxy, pré-destino e pós-destino.

Cada agrupamento mostra claramente as políticas, condições, fluxos compartilhados e informações de fluxo relevantes.

Os fluxos compartilhados são agrupados e recolhidos por padrão.

As seguintes ações estão disponíveis no painel Transação:

Item	Nome	Descrição
<img <="" alt="collapse all slider" class="screenshot" src="/static/apigee/docs/api-platform/debug/images/collapse_all_slider.png" td="" width="" />	Abrir tudo Fechar tudo	Abrir ou fechar todos os grupos.
	Abrir Fechar	Abrir ou fechar um grupo.

Consulte também:

• Zoom
• Como selecionar opções de visualização na IU

Pesquisar

A pesquisa permite encontrar uma palavra ou frase na solicitação ou resposta.

A pesquisa permite encontrar uma palavra ou frase na solicitação ou resposta.

Observe o seguinte:

• A pesquisa não diferencia maiúsculas de minúsculas.
• A pesquisa se aplica a uma única transação, ou seja, ela não pesquisa em todas as transações da sessão de depuração.
• A pesquisa expande as seções recolhidas, mas não mostra informações sobre nós que são filtrados pelas seleções de Opções de visualização.

Para pesquisar:

1. Digite o texto na caixa de pesquisa.

2. Pressione Enter.

   Os resultados da pesquisa são destacados no painel Transação e no painel Detalhes da fase.

3. Clique em keyboard_arrow_up Voltar ou keyboard_arrow_down Próxima para ir para a etapa seguinte ou anterior.

Zoom

O zoom permite controlar a visualização do painel de transações.

O zoom controla a visualização do painel de transações da seguinte maneira:

Ícone	Descrição
100%	Nível de zoom atual. O padrão é 100%.
fit_screen	Ajustar à tela
zoom_in	Aumentar zoom
zoom_out	Diminuir zoom
youtube_searched_for	Redefinição de zoom

Como depurar com a ferramenta Debug

A depuração permite que você veja muitos detalhes internos sobre um proxy de API. 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, é possível usar a depuração para ajudar a identificar onde o gargalo está ocorrendo. O Debug 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.
• Você pode verificar cabeçalhos que estão sendo enviados para o back-end, visualizar 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.

Observação: a ferramenta de depuração trunca payloads, cabeçalhos e variáveis de fluxo para 10 KB.

Como filtrar dados em uma sessão de depuração

Ao criar uma sessão de depuração, é possível adicionar um filtro a ela para que a Apigee retorne apenas os dados desejados. Um filtro é uma instrução condicional que a Apigee avalia em mensagens de solicitação e resposta para determinar se os dados de depuração precisam ser incluídos na sessão de depuração. Por exemplo, é possível filtrar todas as solicitações com um código de resposta HTTP que é menor que 599 ou comparar valores na solicitação com variáveis personalizadas.

Observe o seguinte:

• As solicitações não incluídas em uma sessão de depuração não são contabilizadas no número máximo de transações na sessão de depuração.
• A Apigee não é compatível com a adição de filtros na string de consulta.
• Depois que a sessão for iniciada, não será possível adicionar um filtro a uma sessão de depuração. Para adicionar um filtro, é preciso criar uma sessão de depuração.

Como usar filtros

Use um filtro ao criar uma sessão de depuração com a IU ou a API da Apigee, conforme descrito nas seções a seguir.

IU da Apigee

Ao criar uma sessão de depuração na interface do usuário, na lista suspensa Filtros, você poderá escolher um filtro predefinido para aplicar na acesse o painel Iniciar uma sessão de depuração ou escolha Filtro personalizado e crie o seu com a sintaxe do filtro.

API

Para criar uma sessão de depuração com um filtro usando a API, inclua o seguinte como um payload na sua solicitação de criação de sessão de depuração:

{
  "filter":"filter_body"
}

Para informações sobre como criar filtros, consulte Sintaxe de filtro.

O exemplo a seguir cria uma sessão de depuração que inclui apenas transações em que o cabeçalho A é igual a 42 e o cabeçalho B é igual a 43, ou o código de falha é ExpectedEOF:

curl -H "Authorization: Bearer $TOKEN" -X "POST"
  https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/apis/PROXY/revisions/REV/debugsessions
  -d ' {
    "filter":"(request.header.A == '42' && request.header.B == '43') || fault.code == 'jsonparser.ExpectedEOF'"
  } '

é possível definir um filtro apenas para solicitações de criação de sessão de depuração. No entanto, não é possível adicionar um filtro a uma sessão de depuração atual nem remover um filtro de uma sessão de depuração ativa.

Sintaxe do filtro

Os filtros são compatíveis com a mesma sintaxe usada pelas condições da Apigee, conforme descrito em Referência de condições. Isso inclui:

• Agrupamento
• Lógica E (&&) e OU (|")
• Expressões de caminho
• Operadores e Operandos
• Literais (null, true e false)

Além disso, os filtros podem acessar todas as variáveis de fluxo descritas na referência de variáveis de fluxo, bem como nas variáveis personalizadas. Os exemplos a seguir mostram apenas algumas das possíveis variáveis de fluxo que podem ser usadas nos filtros:

# Response codes:
  response.status.code <= 599
  response.status.code >=301 && response.status.code <=420

# Requests/responses:
  request.verb == "GET"
  request.header.A == 'B' || request.queryparam.X == 'Y'

# Query parameters:
  request.queryparam.myparam == 'fish'
  (request.queryparam.param1 == 'X' || request.queryparam.param2 == 'Y') && request.queryparam.param3 == 'Z'

# Faults:
  fault.code != 'messaging.runtime.RouteFailed'
  fault.name == 'IPDeniedAccess'

Para informações sobre como usar variáveis personalizadas, consulte Como usar atributos personalizados na Apigee na Comunidade Apigee.

Filtros de IU predefinidos

A IU da Apigee fornece um conjunto de filtros comuns para que você não precise escrever seus próprios filtros personalizados. Os filtros predefinidos são resumidos na tabela a seguir.

Nome do filtro	Descrição
Response Time Greater Than	Verifica problemas de latência em que: target.duration é a latência de destino, ou o tempo, em milissegundos, que uma solicitação leva para ser enviada e recebida do destino (calculada como a diferença entre target.received.end.timestamp e target.sent.start.timestamp) client.duration é a latência do cliente ou o tempo, em milissegundos, que uma solicitação leva para ser enviada e recebida do cliente (calculada como a diferença entre client.received.end.timestamp e client.sent.start.timestamp) Exemplo: target.duration > 420 && client.duration > 1000 Para mais informações, consulte client e target na referência das variáveis de fluxo.
Response Code	Verifica se o código de resposta HTTP corresponde ao valor especificado. Por exemplo: response.status.code <= 599 Dica: se você estiver recebendo erros, tente usar message.status.code em vez de response.status.code.
Header	Verifica se o cabeçalho da solicitação especificada é igual ao valor especificado. Por exemplo: request.header.cache-control.1 == "16544"
Path	Verifica se a solicitação corresponde ao caminho especificado. É possível usar correspondência de caracteres curinga no seu valor. Por exemplo: request.path == /myproxy/customer/4*
Query Param	Verifica se o parâmetro de consulta da solicitação especificado é igual ao valor especificado. Por exemplo: request.queryparam.lang == "language:en-us"
Custom	Permite inserir suas próprias expressões. Use os objetos na referência de variáveis de fluxo e a sintaxe na referência de condições. Além disso, é possível usar variáveis personalizadas. Para mais informações sobre como criar filtros personalizados, consulte Sintaxe de filtro.

Como ver sessões de depuração

A Apigee salva os dados da sessão de depuração por 24 horas. Não é possível configurar este valor. Depois de 24 horas, os dados não estarão mais disponíveis. Antes desse período, é possível ver as sessões de depuração.

Observação: se você quiser salvar os dados da sessão de depuração para referência futura, a Apigee recomenda que você faça o download da sessão de depuração.

Para ver os dados de uma sessão de depuração salvos, use a ferramenta de depuração off-line.

Veja as sessões de depuração recentes usando a IU ou a API da Apigee, conforme descrito nas seções a seguir.

IU da Apigee

Para ver as sessões de depuração usando o console do Google Cloud :

1. No console do Google Cloud , acesse a página Desenvolvimento de proxy > Proxies de API.

   Acessar proxies de API

2. Clique no proxy que você quer depurar.
3. Clique na guia Depurar.
4. A seção Sessões de depuração recente exibe uma lista das sessões disponíveis.

5. Clique no link da sessão que você quer visualizar.

API

Ao usar a API, você pode:

• Ver todas as sessões de depuração
• Ver todas as transações de uma sessão de depuração
• Visualizar dados da transação de uma sessão de depuração

Observação:a API Debug Session não indica se uma sessão de depuração está ativa.

Ver todas as sessões de depuração com a API

Para ver todas as sessões de depuração recentes definidas para uma revisão de proxy de API em um ambiente, emita uma solicitação GET para o seguinte recurso:

https://apigee.googleapis.com/v1/organizations/org/environments/env/apis/api/revisions/rev/debugsessions

Também é possível especificar um dos seguintes parâmetros de consulta para controlar a quantidade de dados retornados:

• pageSize: número máximo de sessões de depuração a serem listadas. O tamanho padrão da página é 25.
• pageToken: token de página, retornado de uma chamada anterior, que pode ser usado para recuperar a próxima página.

O exemplo a seguir demonstra como visualizar as sessões de depuração para a revisão 1 do proxy de API helloworld no ambiente test.

curl "https://apigee.googleapis.com/v1/organizations/myorg/environments/test/apis/helloworld/revisions/1/debugsessions" \
-X GET \
-H "Authorization: Bearer $TOKEN"

Em que $TOKEN está definido como seu token de acesso OAuth 2.0, conforme descrito em Como receber um token de acesso OAuth 2.0. Para informações sobre as opções de curl usadas neste exemplo, consulte Como usar curl. Para uma descrição das variáveis de ambiente que podem ser usadas, consulte Como definir variáveis de ambiente para solicitações de API da Apigee.

A resposta inclui um objeto sessions que contém uma lista de sessões de depuração atualmente ativas, conforme mostrado no exemplo a seguir:

{
"sessions": [
{
"id": "a423ac73-0902-4cfa-4242-87a353a84d87",
"timestamp_ms": 1566330186000
},
{
"id": "f1eccbbe-1fa6-2424-83e4-3d063b47728a",
"timestamp_ms": 1566330286000
}
]
}

Faça a depuração de sessões que contenham pelo menos uma transação incluída na resposta. Sessões de depuração que não têm transações não estão incluídas nesta lista.

Para mais informações, consulte Lista de APIs das sessões de depuração.

Ver todas as transações de uma sessão de depuração com a API

Para ver uma lista de transações de uma sessão de depuração, emita uma solicitação GET para o seguinte recurso:

https://apigee.googleapis.com/v1/organizations/org/environments/env/apis/api/revisions/rev/debugsessions/debugsession/data

Em que debugsession é o ID de uma sessão de depuração retornada ao visualizar as sessões de depuração.

O exemplo a seguir demonstra como visualizar as transações de uma sessão de depuração para a revisão 1 da API helloworld no ambiente test.

curl "https://apigee.googleapis.com/v1/organizations/myorg/environments/test/apis/helloworld/revisions/1/debugsessions/a423ac73-0902-4cfa-4242-87a353a84d87/data" \
-X GET \
-H "Authorization: Bearer $TOKEN"

Em que $TOKEN está definido como seu token de acesso OAuth 2.0, conforme descrito em Como receber um token de acesso OAuth 2.0. Para informações sobre as opções de curl usadas neste exemplo, consulte Como usar curl. Para uma descrição das variáveis de ambiente que podem ser usadas, consulte Como definir variáveis de ambiente para solicitações de API da Apigee.

A resposta inclui uma matriz de códigos de transação, conforme mostrado no exemplo a seguir:

[
"myorg-test-ver-5qxdb-64",
"myorg-test-ver-5qxdb-65",
"myorg-test-ver-5qxdb-66",
"myorg-test-ver-5qxdb-67",
"myorg-test-ver-5qxdb-68",
"myorg-test-ver-5qxdb-69",
"myorg-test-ver-5qxdb-70",
"myorg-test-ver-5qxdb-71",
"myorg-test-ver-5qxdb-72"
]

Para mais informações, consulte Lista de APIs de dados da sessão de depuração.

Como visualizar dados de transação de uma sessão de depuração usando a API

Para visualizar os dados de transação de uma sessão de depuração, emita uma solicitação GET para o seguinte recurso:

https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/apis/{api}/revisions/{rev}/debugsessions/{debugsession}/data/{transactionId}

Em que debugsession é o ID de uma sessão de depuração retornada quando você visualiza as sessões de depuração e transactionId é o ID retornado quando você visualiza uma lista de transações de um sessão de depuração.

Não é possível usar essa API para visualizar os dados de uma sessão inteira de uma só vez. Para isso, use a IU, conforme descrito em Como fazer o download de dados de depuração.

Os dados da transação salvos durante uma sessão de depuração são formatados em JSON. É possível carregar esses dados na ferramenta Debug off-line.

No exemplo a seguir, demonstramos como fazer o download dos dados de transação de uma sessão de depuração para a revisão 1 da API helloworld no ambiente test.

curl "https://apigee.googleapis.com/v1/organizations/myorg/environments/test/apis/helloworld/revisions/1/debugsessions/a423ac73-0902-4cfa-4242-87a353a84d87/data/myorg-test-ver-5qxdb-64" \
-X GET \
-H "Authorization: Bearer $TOKEN"

Em que $TOKEN está definido como seu token de acesso OAuth 2.0, conforme descrito em Como receber um token de acesso OAuth 2.0. Para informações sobre as opções de curl usadas neste exemplo, consulte Como usar curl. Para uma descrição das variáveis de ambiente que podem ser usadas, consulte Como definir variáveis de ambiente para solicitações de API da Apigee.

A resposta consiste em um payload JSON que contém os dados da transação especificada, conforme descrito em Estrutura de dados de download.

Os dados de depuração contêm todas as informações sobre a solicitação e a resposta de cada parte do fluxo em um formato JSON reservado. É possível salvar esses dados e usá-los mais tarde na ferramenta de depuração off-line.

Se nenhuma solicitação tiver sido adicionada à sessão antes do término, a resposta será semelhante a esta:

[]

Para mais informações, consulte Conseguir API de dados da sessão de depuração.

Como selecionar opções de visualização na IU

Nesta seção, descrevemos como selecionar opções de visualização para filtrar o que é mostrado na UI.

Para escolher as opções de visualização da sessão de depuração, selecione ou limpe as opções no painel Opções de visualização. Essas opções de visualização são mantidas na sessão de depuração para cada usuário.

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 a referência de configuração do proxy de API.
Mostrar políticas ignoradas	Mostre as políticas que foram ignoradas. Uma política ignorada ocorre quando ela não foi executada porque a condição de etapa foi avaliada como falsa. Consulte Condições com variáveis de fluxo para mais informações.
Mostrar todos os FlowInfos	Representa transições em um segmento de fluxo.
Mostrar todas as condições de fluxo	Representam as condições que foram avaliadas para cada fluxo.

Compartilhar uma sessão de depuração

É possível compartilhar uma sessão de depuração com outros usuários que tenham acesso à organização e as permissões necessárias. Para fazer isso, basta enviar a eles o URL exibido no navegador quando estiver visualizando a sessão de depuração. O link só é válido 24 horas após a criação da sessão de depuração.

Como fazer download de dados da sessão de depuração

É possível fazer o download de um arquivo de resultados de Debug brutos para visualização off-line. O arquivo transferido por download mostra todos os detalhes da sessão de depuração, incluindo o conteúdo de todos os cabeçalhos, variáveis e políticas.

Os dados da sessão de depuração ficam disponíveis para download ou visualização na IU por apenas 24 horas. Depois disso, a Apigee exclui os dados da sessão.

Para ver os dados de uma sessão de depuração salvos, use a ferramenta de depuração off-line.

Observação:

• Não é possível usar a API Apigee para visualizar os dados de uma sessão inteira de uma só vez. Você só pode usar a API para visualizar dados de transação individuais, conforme descrito em Como visualizar sessões de depuração.
• Os metadados NÃO são incluídos ao baixar transações pela API Apigee. É necessário adicionar metadados manualmente para fazer upload e visualizar a transação usando a depuração off-line.

IU da Apigee

Para fazer o download da sessão de depuração atual no console do Google Cloud , clique em Fazer download na visualização de depuração.

Observação:uma sessão de depuração é excluída em até 24 horas após a conclusão. Portanto, se você quiser ver a sessão de depuração após esse período, faça o download dela antes disso.

API

Para visualizar os IDs de todas as transações da sessão de depuração atual usando a API Apigee, insira o seguinte comando:

    curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/apis/PROXY/revisions/REV/debugsessions/SESSION_ID/data

em que SESSION_ID é o ID da sessão de depuração que você quer fazer o download.

Consulte Listar os IDs da transação de uma sessão de depuração.

Para ver os dados de depuração de uma transação usando a API Apigee, digite o seguinte comando:

    curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/apis/PROXY/revisions/REV/debugsessions/SESSION_ID/data/TRANSACTION_ID

Fazer o download da estrutura de dados

A estrutura de download dos dados da sessão de depuração é diferente para a IU e a API da Apigee.

IU da Apigee

Ao fazer o download de dados usando a IU da Apigee, a estrutura de dados:

• inclui todas as transações em toda a sessão;
• armazena transações em uma matriz Messages;
• inclui metadados sobre a sessão (como um objeto DebugSession).

API

Não é possível usar a API Apigee para visualizar os dados de uma sessão inteira de uma só vez. Você só pode usar a API para visualizar dados de transação individuais, conforme descrito em Como visualizar sessões de depuração.

Exemplo:

{
"completed": true,
"point": [
  ...
...
}

Fazer o download de exemplos de dados

Observação:os metadados NÃO são incluídos ao fazer o download de transações pela API Apigee. É necessário adicionar metadados manualmente para fazer upload e visualizar a transação usando a depuração off-line.

O exemplo a seguir destaca um objeto de metadados DebugSession nos dados salvos. Esse objeto é seguido pela matriz Messages que contém as transações na sessão.

{
  "DebugSession": {
    "Retrieved": "2019-06-08T13:08:13.395Z",
    "Organization": "myorg",
    "Environment": "prod",
    "API": "myproxy",
    "Revision": "1",
    "SessionId": "a2a271aa-4242-4ac6-97cb-aec8dcb115a9"
  },
  "Messages": [
    {
      "completed": true,
      "point": [
        {
          "id": "Paused"
        },
        {
          "id": "Resumed"
        },
        {
          "id": "StateChange",
          "results": [
            {
              "ActionResult": "DebugInfo",
              "properties": {
                "property": [
                  {
                    "name": "To",
                    "value": "REQ_HEADERS_PARSED"
                  },
                  {
                    "name": "From",
                    "value": "REQ_START"
                  }
                ]
              },
              "timestamp": "8-6-19 13:08:37:718"
            },
            {
              "ActionResult": "RequestMessage",
              "headers": [
                {
                  "name": "accept",
                  "value": "*/*"
                },
                {
                  "name": "accept-encoding",
                  "value": "gzip,gzip,deflate,br"
                },
                {
                  "name": "content-length",
                  "value": "0"
                },
                {
                  "name": "host",
                  "value": "myorg.example.domain.net"
                },
                {
                  "name": "user-agent",
                  "value": "Google-Apigee"
                },
                {
                  "name": "x-b3-sampled",
                  "value": "0"
                },
                {
                  "name": "x-b3-spanid",
                  "value": "d4ee579206759662"
                },
                {
                  "name": "x-b3-traceid",
                  "value": "adc1e171777c237dd4ee579206759662"
                },
                {
                  "name": "x-forwarded-for",
                  "value": "66.102.8.98"
                },
                {
                  "name": "x-forwarded-proto",
                  "value": "https"
                },
                {
                  "name": "x-request-id",
                  "value": "54e05cba-4242-4490-4242-60c45c156f90"
                }
              ],
              "uRI": "/myproxy",
              "verb": "GET"
            }
          ]
        },
        {
          "id": "FlowInfo",
          "results": [
            {
              "ActionResult": "DebugInfo",
              "properties": {
                "property": [
                  {
                    "name": "environment.name",
                    "value": "prod"
                  },
                  {
                    "name": "environment.qualifiedname",
                    "value": "myorg__prod"
                  },
                  {
                    "name": "environment.orgname",
                    "value": "myorg"
                  }
                ]
              },
              "timestamp": "8-6-19 13:08:37:718"
            }
          ]
        },
        {
          "id": "FlowInfo",
          "results": [
            {
              "ActionResult": "DebugInfo",
              "properties": {
                "property": [
                  {
                    "name": "organization.name",
                    "value": "myorg"
                  }
                ]
              },
              "timestamp": "8-6-19 13:08:37:718"
            }
          ]
        },
        {
          "id": "FlowInfo",
          "results": [
            {
              "ActionResult": "DebugInfo",
              "properties": {
                "property": [
                  {
                    "name": "apiproxy.qualifiedname",
                    "value": "myproxy__1"
                  },
                  {
                    "name": "apiproxy.basepath",
                    "value": "/"
                  },
                  {
                    "name": "apiproxy.revision",
                    "value": "1"
                  },
                  {
                    "name": "apiproxy.name",
                    "value": "myproxy"
                  }
                ]
              },
              "timestamp": "8-6-19 13:08:37:718"
            }
          ]
        },
        ...
      ...
    }
  ]
}

Se a sessão de depuração não incluir nenhuma solicitação, a matriz Message estará vazia, como no exemplo a seguir:

{
  "DebugSession": {
    "Retrieved": "2019-06-08T13:08:13.395Z",
    "Organization": "myorg",
    "Environment": "prod",
    "API": "myproxy",
    "Revision": "1",
    "SessionId": "a2a271aa-4242-4ac6-97cb-aec8dcb115a9"
  },
"Messages": []
}

Como excluir dados de uma sessão de depuração

Exclua dados de uma sessão de depuração usando a IU ou a API da Apigee, conforme descrito nas seções a seguir.

IU da Apigee

Para excluir uma sessão de depuração no console do Google Cloud :

1. Na guia Debug, clique na linha da sessão que você quer excluir.
2. No painel Sessão de depuração, clique em Excluir.

API

Cuidado:não é possível excluir transações individuais ou sessões de depuração específicas dos dados de depuração armazenados. Se você emitir uma solicitação de exclusão, excluirá todas as sessões de depuração e todos os dados associados a elas.

Para excluir todos os dados da sessão de depuração usando a API, emita uma solicitação DELETE para o seguinte recurso:

https://apigee.googleapis.com/v1/organizations/org/environments/env/apis/api/revisions/rev/debugsessions/debugsession/data

Em que debugsession é o ID de uma sessão de depuração retornada ao visualizar as sessões de depuração.

O exemplo a seguir mostra como excluir dados da sessão de depuração para a revisão 1 da API helloworld no ambiente test.

curl "https://apigee.googleapis.com/v1/organizations/myorg/environments/test/apis/helloworld/revisions/1/debugsessions/a423ac73-0902-4cfa-4242-87a353a84d87/data" \
      -X DELETE \
      -H "Authorization: Bearer $TOKEN"
    

Em que $TOKEN está definido como seu token de acesso OAuth 2.0, conforme descrito em Como receber um token de acesso OAuth 2.0. Para informações sobre as opções de curl usadas neste exemplo, consulte Como usar curl. Para uma descrição das variáveis de ambiente que podem ser usadas, consulte Como definir variáveis de ambiente para solicitações de API da Apigee.

Se bem-sucedido, o corpo da resposta ficará vazio.

Os dados da sessão de depuração são mantidos por apenas 24 horas. Se você não o excluir explicitamente antes desse período, a Apigee vai fazer isso por você.