Práticas recomendadas para casos de suporte da Apigee do Google Cloud

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

Você está vendo a documentação da Apigee X.
Veja a documentação da Apigee Edge.

O fornecimento de informações detalhadas e necessárias no caso de suporte facilita o trabalho mais rápido e eficiente da equipe de suporte da Apigee do Google Cloud . Quando seu caso de suporte não tem detalhes importantes, precisamos solicitar mais informações, o que pode envolver várias etapas. Isso leva mais tempo e pode causar atrasos na resolução dos problemas. Este guia de práticas recomendadas permite que você saiba as informações necessárias para resolver seu caso de suporte técnico mais rapidamente.

Como descrever o problema

Um problema precisa conter informações sobre o que aconteceu em comparação com o que era esperado, quando e como isso aconteceu. Um bom caso de suporte da Apigee precisa conter as seguintes informações importantes sobre cada um dos produtos da Apigee:

Informações importantes Descrição Apigee Edge para nuvem pública Apigee Edge para nuvem privada
Produto Produto específico da Apigee em que o problema está sendo observado, incluindo informações de versão, quando aplicável.
  • Versão
Detalhes do problema Descrição clara e detalhada do problema, incluindo a mensagem de erro completa, se houver
  • Mensagem de erro
  • Saída da ferramenta Trace
  • Etapas para reproduzir o problema
  • Concluir comando/solicitação da API
  • Mensagem de erro
  • Saída da ferramenta Trace
  • Etapas para reproduzir o problema
  • Concluir comando/solicitação da API
  • Registros de diagnóstico de componentes
Tempo Carimbo de data e a hora específico em que o problema começou e por quanto tempo ele durou.
  • Data, hora e fuso horário da ocorrência do problema
  • Duração do problema
  • Data, hora e fuso horário da ocorrência do problema
  • Duração do problema
Configuração Informações detalhadas em que o problema está sendo observado.
  • Nome da organização
  • Nome do ambiente
  • Nome do proxy da API
  • Revisão
  • Topologia de rede
  • Componente Edge com falha

As seções a seguir descrevem esses conceitos em mais detalhes.

Produto

Há diferentes produtos da Apigee, o Apigee Edge na nuvem pública e Apigee Edge na nuvem privada, portanto, precisamos informações sobre qual produto específico está tendo o problema.

A tabela a seguir mostra alguns exemplos que mostram informações completas na coluna O que fazer e informações incompletas na coluna O que evitar:

O que fazer O que evitar
A implantação do proxy de API OAuth2 falhou na nossa organização de nuvem pública ...

Falha na implantação do proxy da API

É necessário saber o produto da Apigee em que você está enfrentando o problema.

Falha na instalação com o seguinte erro na versão privada da nuvem privada do Edge 4.50,00...

Falha na instalação da configuração da nuvem privada.

Informações ausentes da versão

Detalhes do problema

Forneça informações precisas sobre o problema que está sendo observado, incluindo a mensagem de erro (se houver) e o comportamento esperado e real observado.

A tabela a seguir mostra alguns exemplos que mostram informações completas na coluna O que fazer e informações incompletas na coluna O que evitar:

O que fazer O que evitar

O novo proxy edgemicro edgemicro_auth falhou com o seguinte erro:

{"error":"missing_authorization","error_description":"Missing Authorization header"}

O novo proxy edgemicro criado hoje não está funcionando

O nome do proxy é desconhecido. Não está claro se o proxy está retornando um erro ou uma resposta inesperada.

Nossos clientes estão recebendo erros 500 com a seguinte mensagem de erro ao fazer solicitações ao proxy de API:

{"fault":{"faultstring":"Execution of JSReadResponse failed with error: Javascript runtime error: \"TypeError: Cannot read property \"content\" from undefined. (JSReadResponse.js:23)","detail":{"errorcode":"steps.javascript.ScriptExecutionFailed"}}}

Nossos clientes estão recebendo erros 500 ao fazer solicitações para o proxy da API.

Apenas transmitir erros 500 não fornece informações adequadas para que possamos investigar o problema. Precisamos saber a mensagem e o código do erro reais que estão sendo observados.

Tempo

O tempo é uma informação muito importante. É importante que o engenheiro de suporte saiba quando você percebeu esse problema pela primeira vez, por quanto tempo ele dura e se o problema ainda está acontecendo.

O engenheiro de suporte que resolver o problema talvez não esteja no seu fuso horário, então frases genéricas sobre o tempo dificultam o diagnóstico. Portanto, é recomendável usar o formato ISO 8601 para o carimbo de data e hora para fornecer a informação exata da hora em que o problema foi observado.

A tabela a seguir fornece alguns exemplos que mostram o horário e a duração precisos em que o problema ocorreu na coluna O que fazer e informações ambíguas ou pouco claras sobre quando o problema ocorreu na coluna O que evitar:

O que fazer O que evitar
Um enorme número de 503s foi observado ontem entre 2020-11-06 17:30 PDT e 2020-11-06 17:35 PDT...

O enorme número de 503s foi observado ontem às 17h30 por cinco minutos.

Somos forçados a usar a data implícita e não é claro em qual fuso horário esse problema foi observado.

Alta latências foram observadas nos seguintes proxies da API de 2020-11-09 15:30 IST a 2020-11-09 18:10 IST ...

As latências altas foram observadas em alguns proxies de API na semana passada.

Não está claro em qual dia e em que duração esse problema foi observado na última semana.

Configuração

Precisamos saber os detalhes de onde o problema está ocorrendo. Dependendo do produto que você está usando, precisamos das seguintes informações:

  • Se você estiver usando o Apigee Cloud, poderá ter mais de uma organização. Por isso, precisamos saber exatamente qual é a organização que está apresentando o problema, além de outros detalhes:
    • Nomes de organização e ambiente
    • Nome do proxy da API e números de revisão (para falhas de solicitação de API)
  • Se você estiver usando a nuvem privada , talvez esteja usando uma das muitas topologias de instalação compatíveis. Então, precisamos saber qual topologia você está usando, incluindo detalhes como número de data centers e nós.

A tabela a seguir mostra alguns exemplos que mostram informações completas na coluna O que fazer e informações incompletas na coluna O que evitar:

O que fazer O que evitar

401 Os erros aumentaram na nuvem pública do Edge desde 2020-11-06 09:30 CST.

Detalhes da configuração do Edge:

Os detalhes da API com falha são os seguintes:
Nomes de organizações: myorg
Nomes de Env: test
Nomes de proxy da API: myproxy
Números da revisão: 3

Erro:

{"fault":{"faultstring":"Failed to resolve API Key variable request.header.X-APP-API_KEY","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}

401 Os erros aumentaram.

Ela não fornece informações sobre o produto que está sendo usado, desde que o problema está sendo observado ou quaisquer detalhes da configuração.

Não é possível iniciar o processador de mensagens na Nuvem Privada Edge versão 4.19.06 (em inglês) após adicionar outros nós de gateway.

Registros de diagnóstico:
anexados pelos registros do Processador de mensagens.

Topologia de rede:
anexou o arquivo network-topology.png que contém os nós extras.

Não é possível iniciar o processador de mensagens na Nuvem Privada Edge versão 4.19.06 (em inglês) após adicionar outros nós de gateway.

Os registros do processador de mensagens e a topologia de rede não estão presentes.

Elementos úteis

Informar quais elementos estão relacionados ao problema agilizará a resolução, já que isso nos ajuda a entender o comportamento exato que você está observando e ver mais insights sobre ela.

Esta seção descreve alguns artefatos úteis que são úteis para todos os produtos da Apigee:

Artefatos comuns a todos os produtos da Apigee

Os artefatos a seguir são úteis para todos os produtos da Apigee: Apigee Edge on Public Cloud e Apigee Edge na nuvem privada:

Artefato Descrição
Saída da ferramenta Trace A saída da ferramenta Trace contém informações detalhadas sobre as solicitações de API que passam pelos produtos da Apigee. Isso é útil para qualquer erro de ambiente de execução, como 4XX, 5XX e problemas de latência.
Capturas de tela Capturas de tela ajudam a retransmitir o contexto do comportamento ou erro real sendo observado. Ela é útil para quaisquer erros ou problemas observados, como na interface do usuário ou no Google Analytics.
HAR (Http ARchive) HAR é um arquivo capturado por ferramentas de sessão HTTP para depurar problemas relacionados à IU. Isso pode ser capturado usando navegadores como Chrome, Firefox ou Internet Explorer.
tcpdumps A ferramenta tcpdump captura pacotes TCP/IP transferidos ou recebidos pela rede. Isso é útil para qualquer problema relacionado à rede, como falhas de handshake de TLS, erros de 502, problemas de latência etc.

Outros artefatos do Apigee Edge em nuvem privada

No caso da Apigee Edge em nuvem privada, precisamos de mais artefatos que agilizem o diagnóstico dos problemas.

Artefato Descrição
Topologia de rede O diagrama de topologia de instalação do Edge descrevendo a configuração da nuvem privada, incluindo todos os data centers, nós e componentes instalados em cada nó.
Registros de diagnóstico do componente Edge Os registros de diagnóstico relacionados ao componente específico do Apigee Edge, como o Processador de mensagens, o roteador ou o Cassandra.
Arquivo de configuração de instalação O arquivo de configuração silencioso usado ao instalar ou fazer upgrade do Apigee Edge.

Este arquivo é útil para confirmar se todas as configurações estão corretas nos casos em que problemas de instalação ou migração são encontrados.

Heap dump Os heap dump são um snapshot do processo da memória Java. Isso é útil se a alta utilização da memória ou erros OutOfMemory forem vistos em determinados componentes do Edge.
Despejos de threads Um despejo de linhas de execução é um snapshot de todas as linhas de execução de um processo Java em execução.

Isso é útil quando a CPU ou a carga alta é observada em determinados componentes do Edge.

Modelos de casos e casos de amostra

Nesta seção, são fornecidos modelos de casos e exemplos de produtos diferentes com base nas práticas recomendadas descritas neste documento:

Apigee Edge em nuvem pública

Modelo

Esta seção fornece um modelo de exemplo para Apigee Edge na nuvem pública.

Problema:

<Forneça uma descrição detalhada do problema ou o comportamento observado por você. Inclua o nome e a versão do produto quando aplicável.>

Mensagem de erro:

<Inclua a mensagem de erro completa observada (se houver)>

Horário de início do problema (formato ISO 8601):

Horário de término do problema (formato ISO 8601):

Detalhes da configuração da Apigee:
  Nomes das organizações:
  Nomes dos ambientes:
  Nomes do proxy da API:
  Números das revisões:

Etapas para reproduzir o problema:

<Forneça etapas para reproduzir o problema sempre que possível>

Informações de diagnóstico:

<Lista de arquivos anexados>

Exemplo de caso

Nesta seção, fornecemos um exemplo de caso para a Apigee Cloud (Apigee no Google Cloud/Apigee Edge em nuvem pública).

Problema:

Estamos vendo um grande número de erros 503 Service Unavailable em nossa organização de Nuvem pública. Você pode analisar o problema e resolvê-lo ou nos informar como resolvê-lo?

Mensagem de erro:

{"fault":{"faultstring":"The Service is temporarily available", "detail":{"errorcode":"messaging.adaptors.http.flow.ServiceUnavailable"}}}

Horário de início do problema (formato ISO 8601): 2020-10-04 06:30 IST

Horário de término do problema (formato ISO 8601): o problema ainda está acontecendo.

Detalhes da configuração da Apigee:
  Nomes das organizações: myorg
  Nomes dos ambientes: dev
  Nomes de proxy da API: myproxy
  Números das revisões: 3

Etapas para reproduzir o problema:

Execute o seguinte comando curl para reproduzir o problema:

curl -X GET 'https://myorg-dev.apigee.net/v1/myproxy'

Informações de diagnóstico:

Saída da ferramenta Trace (trace-503.xml)

Apigee Edge para nuvem privada

Modelo

Esta seção fornece um modelo de exemplo para Apigee Edge for Private Cloud (em inglês).

Problema:

<Forneça uma descrição detalhada do problema ou o comportamento observado por você. Inclua o nome e a versão do produto quando aplicável.>

Mensagem de erro:

<Inclua a mensagem de erro completa observada (se houver)>

Horário de início do problema (formato ISO 8601):

Horário de término do problema (formato ISO 8601):

Detalhes da configuração da nuvem privada do Edge:

<Anexe a topologia da rede descrevendo a configuração da sua nuvem privada, incluindo data centers e nós>

Etapas para reproduzir o problema:

<Forneça etapas para reproduzir o problema sempre que possível>

Informações de diagnóstico

<Lista de arquivos anexados>

Exemplo de caso

Nesta seção, apresentamos um exemplo de caso da Apigee Edge para nuvem privada.

Problema:

Enquanto instalamos a Apigee Management Server no nó #10 como parte da nuvem privada do Edge 4.19.06 no Linux RHEL 7.6, encontramos estes erros.

Mensagem de erro:

<snipped as the output is too long>
Checking for management-server uuid ................................................
Unable to get uuid for management-server.
Error: setup.sh: /opt/apigee/apigee-service/bin/apigee-service exited with unexpected status 1

Horário de início do problema (formato ISO 8601): algo acontece durante a instalação

Horário de término do problema (formato ISO 8601): não aplicável

Detalhes da configuração da nuvem privada do Edge:

Arquivo network-topology.png anexado

Etapas para reproduzir o problema:

Veja o comando que resultou no erro acima:

/opt/apigee/apigee-setup/bin/setup.sh -p ms -f /app/NonProdConfig.txt

Informações de diagnóstico:

Os seguintes arquivos foram anexados:

  • output.txt contendo uma saída completa do comando acima, incluindo a mensagem de erro.
  • Registros de servidor de gerenciamento e
  • arquivo de configuração NonProdConfig.txt