Usar o coletor de diagnósticos

O coletor de diagnósticos é uma ferramenta que capta dados de diagnóstico nos componentes do Kubernetes de uma instância híbrida do Apigee a pedido e armazena-os em contentores do Google Cloud Storage. Invoca o coletor de diagnósticos com o comando apigeectl diagnostic.

Que dados do sistema são capturados?

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

  • Alterar níveis de registo.
  • Jstack.
  • YAML de configuração do POD.
  • Resultado de PS -ef.
  • Captura TCP.
  • Resultado TOP.

O que acontece aos dados?

Quando o coletor de diagnósticos captura os dados, estes são carregados para um contentor de armazenamento no seu projeto do Google Cloud. Pode ver os dados armazenados no Google Cloud Platform: Navegador do Cloud Storage.

Opcionalmente, pode optar por partilhar estes dados com o apoio técnico do Google Apigee quando cria um pedido de apoio técnico.

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

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

Contentor do Google Cloud Storage

Crie um contentor do Google Cloud Storage com um nome único no seu projeto do Google Cloud. Pode criar e gerir contentores com comandos gcloud storage ou no Google Cloud Platform: navegador do Cloud Storage.

Por exemplo: 

gcloud storage buckets create gs://apigee_diagnostic_data
 
Creating gs://apigee_diagnostic_data/...

Consulte o artigo Criar contentores de armazenamento para ver instruções.

Conta de serviço

Crie uma conta de serviço com a função Administrador de armazenamento (roles/storage.admin) no seu projeto e transfira o ficheiro 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.

Por 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

Consulte:

Usar o coletor de diagnósticos

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

  1. Configure a stanza Diagnostic no seu ficheiro overrides.yaml para selecionar o tipo de informações, o contentor do Apigee e os pods individuais dos quais quer obter dados de diagnóstico. Consulte o artigo Configurar o overrides.yaml para o coletor de diagnósticos.
  2. Execute o Diagnostic collector com o seguinte comando apigeectl. 
    apigeectl diagnostic -f OVERRIDES_FILE

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

  3. Verifique os registos:
    1. Obtenha os pods no espaço de nomes apigee-diagnostic. 
      kubectl get pods -n apigee-diagnostic
    2. Tome nota do pod com o nome que contém diagnostic-collector
    3. Verifique os registos 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 pode ver os registos recolhidos no Google Cloud Platform: navegador do Cloud Storage.

  4. Depois de recolher os dados, elimine o coletor de diagnósticos. Não pode executá-lo novamente até o eliminar. 
    apigeectl diagnostic delete -f OVERRIDES_FILE

Configurar o overrides.yaml para o coletor de diagnósticos

Antes de poder executar o coletor de diagnósticos, tem de o configurar no ficheiro overrides.yaml.

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

Propriedades obrigatórias

As seguintes propriedades são necessárias para a execução do coletor de diagnósticos.

  • diagnostic.serviceAccountPath: O caminho para um ficheiro de chave de conta de serviço para a conta de serviço com a função de administrador de armazenamento em Pré-requisitos.
  • diagnostic.operation: especifica se devem ser recolhidas todas as estatísticas ou apenas registos.

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

    Se definir diagnostic.operation como "LOGGING", são necessárias as seguintes propriedades:

  • diagnostic.bucket: o nome do contentor do Google Cloud Storage onde os seus dados de diagnóstico vão ser depositados. Este é o contentor que criou nos Pré-requisitos.
  • diagnostic.container: isto especifica o tipo de agrupamento a partir do qual está a captar dados. Os valores podem ser um dos seguintes:
    Valor: containerComponente do ApigeeNamespace do KubernetesNome do pod de exemplo neste contentor
    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 Observador apigee apigee-watcher-hybrid-example-d89fed1-151-cpu3s-sxxdf
  • diagnostic.namespace: o namespace do Kubernetes no qual residem os pods nos quais está a recolher dados. O espaço de nomes tem de ser o correto para o contentor que especificar com diagnostic.container.
  • diagnostic.podNames: os nomes dos pods individuais nos quais quer recolher 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 necessárias apenas quando a operação está definida como LOGGING

As seguintes propriedades só são necessárias quando executar o coletor de diagnósticos com diagnostic.operation é LOGGING.

  • diagnostic.loggerNames: especifica por nome os registadores dos quais recolher dados. Para a versão 1.6.0 do Apigee Hybrid, o único valor suportado é ALL, o que significa todos os registadores. Por exemplo: 
    diagnostic:
 …
 loggingDetails:
   loggerNames:
   - ALL
  • diagnostic.logLevel: especifica o nível de detalhe dos dados de registo a recolher. No Apigee hybrid 1.6, apenas FINE é suportado.
  • diagnostic.logDuration: a duração em milissegundos dos dados de registo recolhidos. Um valor típico é 30000.

Propriedades opcionais

As seguintes propriedades são opcionais.

  • diagnostic.tcpDumpDetails.maxMsgs: define o número máximo de tcpDump mensagens a recolher. A Apigee recomenda um valor máximo não superior a 1000.
  • diagnostic.tcpDumpDetails.timeoutInSeconds: define o período em segundos que o sistema deve esperar para que tcpDump devolva mensagens.
  • diagnostic.threadDumpDetails.delayInSeconds: O atraso em segundos entre a recolha de cada despejo de memória. Tem de ser usado com o diagnostic.threadDumpDetails.iterations.
  • diagnostic.threadDumpDetails.iterations: o número de iterações de despejo de threads jstack a recolher. Tem de ser usado com o diagnostic.threadDumpDetails.delayInSeconds.

Exemplo geral

Segue-se um exemplo de uma secção 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

Exemplos de utilização comuns

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

Latência elevada do proxy

Neste caso, o Apigee-runtime está a demorar muito tempo a processar pedidos, o que faz com que os clientes vejam latências de proxy elevadas. Tem de recolher a saída Jstack e TOP.

  1. Selecione 2 pods de tempo de execução quaisquer.
  2. Crie a secção 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 secção diagnostic, execute o coletor de diagnósticos. 
    apigeectl diagnostic -f OVERRIDES_FILE
  4. Recolha os registos e elimine o coletor de diagnósticos. 
    apigeectl diagnostic delete -f OVERRIDES_FILE

Problemas de rede / conetividade

Tem de executar diagnósticos no apigee-runtime, bem como nos pods do gateway de entrada.

  1. Selecione 2 pods de tempo de execução quaisquer.
  2. Crie a secção 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 secção diagnostic, execute o coletor de diagnósticos. 
    apigeectl diagnostic -f OVERRIDES_FILE
  4. Recolha os registos e elimine o coletor de diagnósticos. 
    apigeectl diagnostic delete -f OVERRIDES_FILE
  5. Selecione dois pods da gateway de entrada do Istio.
  6. Reconfigure a secção 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 secção diagnostic, execute o coletor de diagnósticos. 
    apigeectl diagnostic -f OVERRIDES_FILE
  8. Recolha os registos e elimine o coletor de diagnósticos. 
    apigeectl diagnostic delete -f OVERRIDES_FILE

Os proxies estão a gerar erros inesperados ou os novos contratos não estão a ser aplicados

Neste caso, tem de alterar os níveis de registo para depurar durante, pelo menos, 5 minutos ou até 10 minutos, como neste exemplo. Isto aumenta a quantidade de registos, mas as informações úteis são registadas. Executa o Diagnostic Collector duas vezes, uma no tempo de execução do Apigee e outra no sincronizador do Apigee.

  1. Selecione 2 pods de tempo de execução quaisquer.
  2. Crie a secção 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 secção diagnostic, execute o coletor de diagnósticos. 
    apigeectl diagnostic -f OVERRIDES_FILE
  4. Recolha os registos e elimine o coletor de diagnósticos. 
    apigeectl diagnostic delete -f OVERRIDES_FILE
  5. Selecione 2 pods de sincronização.
  6. Crie a secção 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 secção diagnostic, execute o coletor de diagnósticos. 
    apigeectl diagnostic -f OVERRIDES_FILE
  8. Recolha os registos e elimine o coletor de diagnósticos. 
    apigeectl diagnostic delete -f OVERRIDES_FILE