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

Esta é a documentação da Apigee e da Apigee híbrida.
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 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. Neste guia de práticas recomendadas, você conhecerá 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 precisa conter as seguintes informações importantes sobre cada um dos produtos da Apigee:

Key information Descrição Apigee no Google Cloud 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 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
  • Métricas do Cloud Monitoring
Tempo Carimbo de data/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

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

Produto

Há diferentes produtos da Apigee, Apigee no Google Cloud e Apigee híbrida. Portanto, precisamos de informações específicas sobre qual produto específico está com 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
Falha na implantação do proxy de API OAuth2 na nossa organização da Apigee no Google Cloud...

Falha na implantação do proxy da API

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

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 ao proxy de 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 real 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 durou 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 precisa 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 06/11/2020 17h30 PDT e 06/11/2020 17h35 PDT...

Um 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.
Latências altas foram observadas nos proxies de API a seguir entre 09/11/2020 15h30 IST e 09/11/2020 18h10 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.

Instalaçã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 a Apigee no Google 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 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

Os erros 401 aumentaram na Apigee no Google Cloud desde 06/11/2020 09h30 CST.

Detalhes de configuração da Apigee:

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.

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 artefatos 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 isso.

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

Artefatos comuns a todos os produtos da Apigee

Os seguintes artefatos são úteis para todos os produtos da Apigee: Apigee no Google Cloud e Apigee 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 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, apresentamos um modelo de exemplo da Apigee no Google Cloud.

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, apresentamos um caso de exemplo da Apigee no Google Cloud.

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)

Híbrido

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