Como usar o coletor de diagnósticos

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.

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/...

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 usar o coletor de diagnósticos

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

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

Selecione qualquer um dos dois pods do ambiente de execução.

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

Depois de configurar a estrofe diagnostic, execute o coletor de diagnóstico.
```
apigeectl diagnostic -f OVERRIDES_FILE
```
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.

Selecione qualquer um dos dois pods do ambiente de execução.

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

Depois de configurar a estrofe diagnostic, execute o coletor de diagnóstico.
```
apigeectl diagnostic -f OVERRIDES_FILE
```
Colete os registros e exclua o coletor de diagnóstico.
```
apigeectl diagnostic delete -f OVERRIDES_FILE
```
Selecione dois pods no gateway de entrada do Istio.

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

Depois de configurar a estrofe diagnostic, execute o coletor de diagnóstico.
```
apigeectl diagnostic -f OVERRIDES_FILE
```
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.

Selecione qualquer um dos dois pods do ambiente de execução.

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

Depois de configurar a estrofe diagnostic, execute o coletor de diagnóstico.
```
apigeectl diagnostic -f OVERRIDES_FILE
```
Colete os registros e exclua o coletor de diagnóstico.
```
apigeectl diagnostic delete -f OVERRIDES_FILE
```
Selecione qualquer dois pods de sincronização.

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

Depois de configurar a estrofe diagnostic, execute o coletor de diagnóstico.
```
apigeectl diagnostic -f OVERRIDES_FILE
```
Colete os registros e exclua o coletor de diagnóstico.
```
apigeectl diagnostic delete -f OVERRIDES_FILE
```

Como usar o coletor de diagnósticos

Quais dados do sistema são capturados?

O que acontece com os dados?

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

Bucket do Google Cloud Storage

Conta de serviço

Como usar o coletor de diagnósticos

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

Propriedades obrigatórias

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

Propriedades opcionais

Exemplo geral

Casos de uso comuns

Alta latência de proxy

Problemas de conectividade/rede

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

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

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