Como usar o coletor de diagnósticos

Você está visualizando a versão 1.7 da documentação da Apigee híbrida. This version is end of life. You should upgrade to a newer version. Para mais informações, consulte Versões compatíveis.

Version 1.7 (unsupported)

Versões com suporte:

• v1.13 (mais recente)                        
• v1.12                         
• v1.11
• Lista de versões com suporte

Versões sem suporte:

• v1.10                                      
• v1.9
• v1.8                                         
• v1.7
• v1.6
• v1.5
• v1.4
• v1.3
• v1.2
• v1.1

O coletor de diagnóstico é uma ferramenta que captura dados de diagnóstico nos componentes do Kubernetes de uma instância da Apigee híbrida sob demanda e os armazena nos buckets de armazenamento do Google Cloud. Invoque o coletor de diagnóstico com o comando apigeectl diagnostic.

Quais dados do sistema são capturados?

O coletor de diagnóstico captura os seguintes tipos de dados:

• Como alterar os níveis de registros.
• Jstack.
• yaml de configuração do POD.
• Saída PS-ef.
• Despejo de TCP.
• Resposta de TOP.

O que acontece com os dados?

Quando o coletor de diagnóstico captura os dados, eles são enviados para um bucket de armazenamento no seu projeto do Google Cloud. É possível ver os dados armazenados no navegador do Google Cloud Platform: Cloud Storage.

É possível compartilhar esses dados com o suporte da Google Apigee ao criar um tíquete de suporte.

Observação: nenhum dado de tempo de execução do usuário ou informações confidenciais são capturados nos dados coletados pelo coletor de diagnósticos.

Pré-requisitos para executar o coletor de diagnósticos

Antes de usar o coletor de diagnósticos, é preciso cumprir os seguintes pré-requisitos:

Bucket do Google Cloud Storage

Crie um bucket do Google Cloud Storage com um nome exclusivo no projeto do Google Cloud. É possível criar e gerenciar buckets com comandos gcloud storage ou no Google Cloud Platform: navegador do Cloud Storage.

Exemplo:

gcloud storage buckets create gs://apigee_diagnostic_data

Creating gs://apigee_diagnostic_data/...

Os nomes dos buckets precisam ser globalmente exclusivos em todos os projetos do Google Cloud, incluindo aqueles de fora da organização.

Consulte as instruções em Como criar buckets de armazenamento.

Conta de serviço

Crie uma conta de serviço com o papel Administrador do Storage (roles/storage.admin) no seu projeto e faça o download do arquivo de chave .json da conta de serviço.

A conta de serviço pode ter qualquer nome exclusivo. Este guia usa "apigee-diagnostic" para o nome da conta de serviço.

Exemplo:

gcloud config set project ${PROJECT_ID}

gcloud iam service-accounts create apigee-diagnostic

gcloud projects add-iam-policy-binding ${PROJECT_ID} \
    --member="serviceAccount:apigee-diagnostic@${PROJECT_ID}.iam.gserviceaccount.com" \
    --role="roles/storage.admin"

gcloud iam service-accounts keys create ${PROJECT_ID}-apigee-diagnostic.json \
    --iam-account=apigee-diagnostic@${PROJECT_ID}.iam.gserviceaccount.com

Veja estes tópicos:

• Como criar e gerenciar contas de serviço.
• Como criar e gerenciar chaves de contas de serviço.
• Noções básicas sobre papéis: papéis do Cloud Storage.

Como usar o coletor de diagnósticos

A sequência para usar o coletor de diagnósticos é:

1. Configure a estrofe de diagnóstico no seu arquivo overrides.yaml para selecionar o tipo de informação, o contêiner da Apigee e os pods individuais dos quais você quer dados de diagnóstico. Consulte Como configurar overrides.yaml para o coletor de diagnóstico.
2. Execute o coletor de diagnósticos com o seguinte comando apigeectl.

   apigeectl diagnostic -f OVERRIDES_FILE

   Em que OVERRIDES_FILE é o caminho para o arquivo overrides.yaml.

3. Verifique os registros:
   1. Receba os pods no namespace apigee-diagnostic.

      kubectl get pods -n apigee-diagnostic

   2. Anote o pod com o nome que contém diagnostic-collector.
   3. Verifique os registros com o seguinte comando:

      kubectl -n apigee-diagnostic logs -f POD_NAME

      Em que POD_NAME é o nome do pod do coletor de diagnósticos.

      Também é possível ver os registros coletados no navegador do Google Cloud Platform: Cloud Storage.

4. Depois de coletar os dados, exclua o coletor de diagnóstico. Não é possível executá-lo novamente até excluí-lo.

   apigeectl diagnostic delete -f OVERRIDES_FILE

Como configurar o overrides.yaml para o coletor de diagnósticos

Antes de executar o coletor de diagnóstico, é preciso configurá-lo no arquivo overrides.yaml.

Para uma referência completa das propriedades de configuração do diagnostic, consulte a Referência da propriedade de configuração: diagnostic.

Propriedades obrigatórias

As seguintes propriedades são obrigatórias para que o coletor de diagnóstico seja executado.

• diagnostic.serviceAccountPath: o caminho para um arquivo de chave da conta de serviço para a conta de serviço com o papel Administrador de armazenamento em Pré-requisitos.
• diagnostic.operation: especifica se é necessário coletar todas as estatísticas ou apenas registros.

  Os valores são "ALL" ou "LOGGING".

  Se você definir diagnostic.operation como "LOGGING", as seguintes propriedades serão obrigatórias:

  • diagnostic.loggingDetails.logDuration
  • diagnostic.loggingDetails.loggerNames
  • diagnostic.loggingDetails.logLevel
• diagnostic.bucket: o nome do bucket de armazenamento do Google Cloud em que os dados de diagnóstico serão depositados. Este é o bucket que você criou em Pré-requisitos.
• diagnostic.container: especifica o tipo de pod de onde você está capturando dados. Os valores podem ser um dos seguintes:

  Valor de container	Componente da Apigee	Namespace do Kubernetes	Exemplo de nome do pod neste contêiner
  apigee-cassandra	Cassandra	apigee	apigee-cassandra-default-0
  istio-proxy	Entrada do Istio	istio-system	istio-ingressgateway-696879cdf8-9zzzf
  apigee-mart-server	MART	apigee	apigee-mart-hybrid-example-d89fed1-151-jj2ux-l7nlb
  apigee-runtime	processador de mensagens	apigee	apigee-runtime-hybrid-example-3b2ebf3-151-s64bh-g9qmv
  apigee-synchronizer	Sincronizador	apigee	apigee-synchronizer-hybrid-example-3b2ebf3-151-xx4z6cg78
  apigee-udca	UDCA	apigee	apigee-udca-hybrid-example-3b2ebf3-151-q4g2c-vnzg9
  apigee-watcher	Watcher	apigee	apigee-watcher-hybrid-example-d89fed1-151-cpu3s-sxxdf

• diagnostic.namespace: o namespace do Kubernetes em que os pods são coletados de dados residem; O namespace precisa ser o correto para o contêiner que você especificou com diagnostic.container.
• diagnostic.podNames: os nomes dos pods individuais em que você quer coletar dados de diagnóstico. Por exemplo:

  diagnostic:
   …
   podNames:
   - apigee-runtime-hybrid-example-3b2ebf3-150-8vfoj-2wcjn
   - apigee-runtime-hybrid-example-3b2ebf3-150-8vfoj-6xzn2

Propriedades obrigatórias somente quando a operação está definida como LOGGING

As seguintes propriedades são obrigatórias somente quando o coletor de diagnóstico com diagnostic.operation é LOGGING.

• diagnostic.loggerNames: especifica pelo nome de que os registradores coletam dados. Para a Apigee híbrida versão 1.6.0, o único valor compatível é ALL, o que significa todos os registradores. Por exemplo:

  diagnostic:
   …
   loggingDetails:
     loggerNames:
     - ALL

• diagnostic.logLevel: especifica a granularidade dos dados de geração de registros a serem coletados. No Apigee híbrido 1.6, somente FINE é compatível.
• diagnostic.logDuration: a duração em milissegundos dos dados de registro coletados. Um valor típico é 30000.

Propriedades opcionais

As seguintes propriedades são opcionais.

• diagnostic.tcpDumpDetails.maxMsgs: define o número máximo de mensagens tcpDump a serem coletadas. A Apigee recomenda um valor máximo de 1000.
• diagnostic.tcpDumpDetails.timeoutInSeconds: define o tempo em segundos para aguardar que tcpDump retorne mensagens.
• diagnostic.threadDumpDetails.delayInSeconds: o atraso em segundos entre a coleta de cada despejo de linhas de execução. Precisa ser usado com diagnostic.threadDumpDetails.iterations.
• diagnostic.threadDumpDetails.iterations: o número de iterações de despejo de linhas de execução do jstack a serem coletadas. Precisa ser usado com diagnostic.threadDumpDetails.delayInSeconds.

Exemplo geral

Veja a seguir um exemplo de estrofe diagnostic que mostra todas as entradas possíveis:

diagnostic:
  # required properties:
  serviceAccountPath: "service-accounts/apigee-diagnostics.json"
  operation: "ALL"
  bucket: "diagnostics_data"
  container: "apigee-runtime"
  namespace: "apigee"
  podNames:
  - apigee-runtime-hybrid-example-3b2ebf3-150-8vfoj-2wcjn
  - apigee-runtime-hybrid-example-3b2ebf3-150-8vfoj-6xzn2

  # required if operation is Logging
  loggingDetails:
    loggerNames:
    - ALL
    logLevel: FINE
    logDuration: 30000

  # optional properties:
  tcpDumpDetails:
    maxMsgs: 10
    timeoutInSeconds: 100

  threadDumpDetails:
    iterations: 5
    delayInSeconds: 2

Casos de uso comuns

Os exemplos a seguir mostram como configurar e usar o coletor de diagnósticos em algumas situações comuns.

Alta latência de proxy

Nesse caso, o tempo de execução da Apigee está demorando muito para processar as solicitações, fazendo com que os clientes vejam altas latências de proxy. É necessário coletar a saída do Jstack e TOP.

1. Selecione qualquer um dos dois pods do ambiente de execução.
2. Crie sua estrofe diagnostic com a seguinte estrutura:

   diagnostic:
     serviceAccountPath: "service-accounts/apigee-diagnostics.json"
     operation: "ALL"
     bucket: "diagnostics_data"
     container: "apigee-runtime"
     namespace: "apigee"
     podNames:
     - apigee-runtime-hybrid-example-3b2ebf3-150-8vfoj-2wcjn
     - apigee-runtime-hybrid-example-3b2ebf3-150-8vfoj-6xzn2
   
     tcpDumpDetails:
       maxMsgs: 10
   
     threadDumpDetails:
       iterations: 15
       delayInSeconds: 1

3. Depois de configurar a estrofe diagnostic, execute o coletor de diagnóstico.

   apigeectl diagnostic -f OVERRIDES_FILE

4. Colete os registros e exclua o coletor de diagnóstico.

   apigeectl diagnostic delete -f OVERRIDES_FILE

Problemas de conectividade/rede

É preciso executar diagnósticos no ambiente de execução da Apigee, bem como nos pods de gateway de entrada.

1. Selecione qualquer um dos dois pods do ambiente de execução.
2. Crie sua estrofe diagnostic com a seguinte estrutura:

   diagnostic:
     serviceAccountPath: "service-accounts/apigee-diagnostics.json"
     operation: "ALL"
     bucket: "diagnostics_data"
     container: "apigee-runtime"
     namespace: "apigee"
     podNames:
     - apigee-runtime-hybrid-example-3b2ebf3-150-8vfoj-2wcjn
     - apigee-runtime-hybrid-example-3b2ebf3-150-8vfoj-6xzn2
   
     tcpDumpDetails:
       maxMsgs: 1000

3. Depois de configurar a estrofe diagnostic, execute o coletor de diagnóstico.

   apigeectl diagnostic -f OVERRIDES_FILE

4. Colete os registros e exclua o coletor de diagnóstico.

   apigeectl diagnostic delete -f OVERRIDES_FILE

5. Selecione dois pods no gateway de entrada do Istio.
6. Reconfigure a estrofe diagnostic com os pods de entrada do Istio:

   diagnostic:
     serviceAccountPath: "service-accounts/apigee-diagnostics.json"
     operation: "ALL"
     bucket: "diagnostics_data"
     container: "istio-proxy"
     namespace: "istio-system"
     podNames:
     - istio-ingressgateway-696879cdf8-9zzzf
     - istio-ingressgateway-696879cdf8-6abc7
   
     tcpDumpDetails:
       maxMsgs: 1000

7. Depois de configurar a estrofe diagnostic, execute o coletor de diagnóstico.

   apigeectl diagnostic -f OVERRIDES_FILE

8. Colete os registros e exclua o coletor de diagnóstico.

   apigeectl diagnostic delete -f OVERRIDES_FILE

Os proxies estão gerando erros inesperados ou novos contratos não estão sendo aplicados

Nesse caso, você precisa alterar os níveis de registro para depurar por pelo menos cinco minutos ou até 10 minutos, como no exemplo a seguir. Isso aumenta a quantidade de registros, mas informações úteis são registradas. Você executará o coletor de diagnóstico duas vezes: uma no ambiente de execução da Apigee e depois no sincronizador da Apigee.

1. Selecione qualquer um dos dois pods do ambiente de execução.
2. Crie sua estrofe diagnostic com a seguinte estrutura:

   diagnostic:
     serviceAccountPath: "service-accounts/apigee-diagnostics.json"
     operation: "LOGGING"
     bucket: "diagnostics_data"
     namespace: "apigee"
     container: "apigee-runtime"
     podNames:
     - apigee-runtime-hybrid-example-3b2ebf3-150-8vfoj-2wcjn
     - apigee-runtime-hybrid-example-3b2ebf3-150-8vfoj-6xzn2
   
     loggingDetails:
       loggerNames:
       - ALL
       logLevel: FINE
       logDuration: 60000

3. Depois de configurar a estrofe diagnostic, execute o coletor de diagnóstico.

   apigeectl diagnostic -f OVERRIDES_FILE

4. Colete os registros e exclua o coletor de diagnóstico.

   apigeectl diagnostic delete -f OVERRIDES_FILE

5. Selecione qualquer dois pods de sincronização.
6. Crie sua estrofe diagnostic com a seguinte estrutura:

   diagnostic:
     serviceAccountPath: "service-accounts/apigee-diagnostics.json"
     operation: "LOGGING"
     bucket: "diagnostics_data"
     namespace: "apigee"
     container: "apigee-synchronizer"
     podNames:
     - apigee-synchronizer-hybrid-example-3b2ebf3-150-xx4z-6cg78
     - apigee-synchronizer-hybrid-example-3b2ebf3-150-xx4z-1a2b3
   
     loggingDetails:
       loggerNames:
       - ALL
       logLevel: FINE
       logDuration: 60000

7. Depois de configurar a estrofe diagnostic, execute o coletor de diagnóstico.

   apigeectl diagnostic -f OVERRIDES_FILE

8. Colete os registros e exclua o coletor de diagnóstico.

   apigeectl diagnostic delete -f OVERRIDES_FILE