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

Esta é 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 Cloud (Apigee no Google Cloud/Apigee Edge em nuvem pública) Apigee Edge para nuvem privada Apigee híbrido
Produto Produto específico da Apigee em que o problema está sendo observado, incluindo informações de versão, quando aplicável.
  • Versão
  • Versão híbrida
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 de depuração
  • Etapas para reproduzir o problema
  • Concluir comando/solicitação da API
  • Mensagem de erro
  • Saída da ferramenta de depuração
  • Etapas para reproduzir o problema
  • Concluir comando/solicitação da API
  • Registros de diagnóstico de componentes
  • Mensagem de erro
  • Saída da ferramenta de depuração
  • Etapas para reproduzir o problema
  • Concluir comando/solicitação da API
  • Registros de diagnóstico de componentes
  • Métricas do Cloud Monitoring
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
  • 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 Apigee, Apigee Cloud (Apigee no Google Cloud/Apigee Edge em nuvem pública), Apigee Edge em nuvem privada e Apigee híbrida. Por isso, precisamos saber exatamente qual produto está apresentando 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

Estamos recebendo o seguinte erro ao acessar o Cassandra usando cqlsh na versão híbrida 1.3 da Apigee ...

Não foi possível acessar o Cassandra usando cqlsh.

Faltam informações de versão híbridas

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.
  • Se você estiver usando a híbrida, talvez esteja usando uma das muitas plataformas híbridas e topologias de instalação compatíveis. Então, precisamos saber qual plataforma híbrida e 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.

A depuração está apresentando falha com o seguinte erro na versão híbrida 1.3 da Apigee

Erro:

Error while Creating trace session for corp-apigwy-discovery, revision 3, environment dev.

Failed to create DebugSession {apigee-hybrid-123456 dev corp-apigwy-discovery 3 ca37384e-d3f4-4971-9adb-dcc36c392bb1}

Detalhes da configuração híbrida da Apigee:

  • Plataforma híbrida da Apigee:
    Anthos GKE On-Prem versão 1.4.0
  • Projeto do Google Cloud, organização híbrida e ambiente
    ID do projeto do Google Cloud: apigee-hybrid-123456
    Organização híbrida da Apigee: apigee-hybrid-123456
    Ambiente híbrido da Apigee: dev
  • Detalhes do nome do cluster do Kubernetes
    k8sCluster:
    nome: user-cluster-1
    região: us-east1
  • Topologia de rede
    Anexou o arquivo network-topology.png.
Falha de depuração no Apigee híbrido.

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 Cloud (Apigee no Google Cloud/Apigee Edge em nuvem pública), Apigee Edge em nuvem privada, eApigee híbrida:

Artefato Descrição
Saída da ferramenta de depuração A saída da ferramenta de depuração 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.

Outros artefatos para ambientes híbridos

Para a híbrida, talvez sejam necessários artefatos adicionais que facilitem o diagnóstico de problemas.

Artefato Descrição
Plataforma híbrida da Apigee Especifique uma das plataformas híbridas compatíveis que são usadas:
  • GKE
  • GKE On-Prem
  • AKS (Serviço do Kubernetes do Azure)
  • Amazon EKS
  • GKE na AWS
Versões de componentes híbridos e dependentes da Apigee
  • Versão híbrida da CLI da Apigee: versão
    apigeectl
  • Versão do agente da Apigee Connect:
    kubectl -n=apigee get pods -l app=apigee-connect-agent -o=json | jq '.items[].spec.containers[].image'
  • Versão da MART da Apigee:
    kubectl -n=apigee get pods -l app=apigee-mart -o=json | jq '.items[].spec.containers[].image'
  • Versão do sincronizador da Apigee:
    kubectl -n=apigee get pods -l app=apigee-synchronizer -o=json | jq '.items[].spec.containers[].image'
  • Versão da Apigee Cassandra:
    kubectl -n=apigee get pods -l app=apigee-cassandra -o=json | jq '.items[].spec.containers[].image'
  • Versão do ambiente de execução da Apigee:
    kubectl -n=apigee get pods -l app=apigee-runtime -o=json | jq '.items[].spec.containers[].image'
  • CLI do Kubernetes e versões de servidor:
    versão kubectl
  • CLI do Istio e versões de servidor:
    versão istioctl
Topologia de rede O diagrama de topologia de instalação da Apigee que descreve a configuração híbrida, incluindo todos os data centers, clusters do Kubernetes, namespaces e pods.
Modifica o arquivo YAML O arquivo overrides.yaml usado em cada data center para instalar o plano de ambiente de execução híbrido da Apigee.
Status da implantação híbrida da Apigee

A saída dos seguintes comandos em cada cluster de data center/Kubernetes:

kubectl get pods -A
kubectl get services -A

Registros de componentes híbridos da Apigee

Fornecer links para os registros do StackDriver para os componentes híbridos OU

É possível buscar os registros do componente híbrido da Apigee usando os seguintes comandos em cada cluster de data center/cluster do Kubernetes e compartilhá-los conosco:

kubectl -n {namespace} get pods
kubectl -n {namespace} logs {pod-name}

  • Registros do agente do Apigee Connect:
    kubectl -n {namespace} get pods
    kubectl -n {namespace} logs {apigee-connect-agent-pod-name}
  • Registros MART:
    kubectl -n {namespace} get pods
    kubectl -n {namespace} logs {apigee-mart-pod-name}
  • Registros do sincronizador:
    kubectl -n {namespace} get pods
    kubectl -n {namespace} logs {synchronizer-pod-name}
  • Registros do Apigee Cassandra:
    kubectl -n {namespace} get pods
    kubectl -n {namespace} logs {apigee-cassandra-pod-name}
  • Registros do ambiente de execução da MP/Apigee (de todos os pods do ambiente de execução da Apigee):
    kubectl -n {namespace} get pods
    kubectl -n {namespace} logs {apigee-runtime-pod-name}
Descrever registros

Informações detalhadas sobre o pod.

Isso é útil especialmente se você estiver observando problemas como os pods ficarem presos no estado CrashLoopBackoff.

kubectl -n apigee describe pod {pod-name}

Cloud Monitoring
  • Link para seu painel de métricas
  • Snapshots de qualquer painel relacionado às métricas do Cloud Monitoring.

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 Cloud

Modelo

Nesta seção, fornecemos um modelo de amostra da Apigee Cloud (Apigee no Google Cloud/Apigee Edge em 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 de depuração (trace-503.xml)

Apigee Edge para nuvem privada

Modelo

Nesta seção, fornecemos um modelo de amostra da Apigee Edge para nuvem privada.

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

Nuvem híbrida

Modelo

Nesta seção, apresentamos um modelo de amostra do Apigee híbrido.

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 híbrida da Apigee:

  • Plataforma híbrida da Apigee:

    <Forneça as informações sobre a Plataforma em que você instalou o híbrido e a respectiva versão.>

  • Projeto do Google Cloud, organização híbrida e ambiente:
    ID do projeto do Google Cloud:
      <Se você estiver usando o Google Kubernetes Engine (GKE), forneça o ID do projeto em que os clusters estão localizados. Se você estiver usando o GKE On-Prem, o Azure Kubernetes Service ou o Amazon EKS, forneça o ID do projeto para onde enviar os registros.>
    Organização híbrida da Apigee:
    Ambiente híbrido da Apigee:
  • Apigee híbrida e outras versões da CLI:
    CLI da Apigee híbrida (apigeectl): versão
    do Kubectl:
  • Detalhes do nome do cluster do Kubernetes:
    k8sCluster:
    nome:
    região:
  • Topologia de rede:
    <Anexe a topologia de rede, que descreve a configuração da Apigee híbrida, incluindo data centers, clusters, namespaces e pods do Apigee.>
  • Substitui o arquivo YAML:
    <Anexa o arquivo YAML substituto.>

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 híbrida.

Problema:

Estamos recebendo erros ao executar APIs de gerenciamento na Apigee híbrida versão 1.3.

Mensagem de erro:

[ERROR] 400 Bad Request
{
"error": {
"code": 400,
"message": "Error processing MART request: INTERNAL_ERROR",
"errors": [
{
"message": "Error processing MART request: INTERNAL_ERROR",
"domain": "global",
"reason": "failedPrecondition"
}
],
"status": "FAILED_PRECONDITION"
}
}

Horário de início do problema (formato ISO 8601): desde 2020-10-24 10:30 PDT

Horário de término do problema (formato ISO 8601): continuando observando o problema.

Detalhes da configuração híbrida da Apigee:

  • Plataforma híbrida da Apigee
    GKE versão 1.15.1
  • Projeto do Google Cloud, organização híbrida e ambiente
    ID do projeto do Google Cloud: apigee-hybrid-123456
      Observação: este é o ID do projeto em que os clusters estão localizados.
    Organização híbrida da Apigee: apigee-hybrid-123456
    Ambiente híbrido da Apigee: dev
  • Apigee híbrida e outras versões da CLI:
    CLI híbrida da Apigee (apigeectl):
    Versão: 1.2.0
    Compromisso: ac09109
    Código da versão: 214
    Horário da versão: 2020-03-30T20:23:36Z
    Versão do Go: go1.12

    Versão do Kubectl:
    versão do cliente:
    version.Info{Major:"1", Minor:"15", GitVersion:"v1.15.0", GitCommit:"e8462b5b5dc2584fdcd18e6bcfe9f1e4d970a529", GitTreeState:"clean", BuildDate:"2019-06-19T16:40:16Z", GoVersion:"go1.12.5", Compiler:"gc", Platform:"darwin/amd64"}

        Versão do servidor:
    version.Info{Major:"1", Minor:"14+", GitVersion:"v1.14.10-gke.36", GitCommit:"34a615f32e9a0c9e97cdb9f749adb392758349a6", GitTreeState:"clean",
  • Detalhes do nome do cluster do Kubernetes
    k8sCluster:
    nome: user-cluster-1
    região: us-east1
  • Topologia de rede
    Anexou o arquivo network-topology.png
  • Substitui o arquivo YAML
    O arquivo overrides.yaml foi anexado

Etapas para reproduzir o problema:

Execute a seguinte API de gerenciamento para observar o erro:

curl -X GET --header "Authorization: Bearer <TOKEN>" "https://apigee.googleapis.com/v1/organizations/apigee-hybrid-123456/environments/dev/keyvaluemaps"

Informações de diagnóstico:

Os seguintes arquivos foram anexados:

  • network-topology.png
  • overrides.yaml file
  • Registros MART
  • Registros do sincronizador