Pular para o conteúdo principal
Quando uma solicitação de suporte chega em support@appsignal.com, temos alguns procedimentos para depurar de onde um problema pode vir. Como é bom compartilhar, aqui estão alguns dos nossos procedimentos. Veja também nossa lista de problemas conhecidos para uma lista de problemas que podem afetar sua aplicação.

​
Diagnóstico

Nosso gem Ruby, pacote Elixir, pacote Node.js e pacote Python vêm com uma ferramenta de linha de comando de diagnóstico integrada que produz informações sobre a configuração da biblioteca do AppSignal e o ambiente em que está rodando. Todas essas informações podem ajudar a encontrar uma possível causa para um problema. Se você abrir uma solicitação de suporte, geralmente pediremos que você execute isso primeiro. 
# Ruby
appsignal diagnose

# Elixir
mix appsignal.diagnose

# Com um binário de release Elixir (`mix release`):
bin/your_app eval ":appsignal_tasks.diagnose()"

# Com um binário de release Distillery:
bin/your_app command appsignal_tasks diagnose

# Node.js
npx @appsignal/cli diagnose

# Python
python -m appsignal diagnose
O comando diagnose deve ser executado no diretório de uma aplicação que tenha a biblioteca do AppSignal instalada. A menos que a aplicação seja configurada com variáveis de ambiente, é necessário fornecer ao comando diagnose um ambiente. O ambiente ajudará o AppSignal a carregar a configuração correta que precisa ser diagnosticada. 
# Ruby
APPSIGNAL_APP_ENV=production appsignal diagnose
# Suporte à opção --environment desde o gem Ruby versão 2.0.4
appsignal diagnose --environment=production

# Elixir
MIX_ENV=production mix appsignal.diagnose
# Ou com o binário de release
bin/your_app command appsignal_tasks diagnose

# Node.js
NODE_ENV=production npx @appsignal/cli diagnose

# Python
APPSIGNAL_APP_ENV=production python -m appsignal diagnose

​
Informações do diagnóstico

O comando diagnose produzirá os seguintes dados.
  • Informações do agente
    • Versão do gem Ruby / pacote Elixir / Node.js / pacote Python
    • Versão do agente
    • Caminho de instalação do gem Ruby
    • Extensão C / Nif carregada: yes/no
  • Informações do host
    • Arquitetura de hardware
    • Sistema operacional
    • Versão do Ruby / Elixir & OTP / Node.js / Python
    • Detecção de Heroku - visível apenas no Heroku
    • Detecção de container
    • Usuário atual é o usuário root: yes/no
  • Diagnóstico do Agente
    • Inicia o agente no modo de diagnóstico
    • Validação da configuração do agente
    • Inicialização do logger do agente
    • Verificação se o caminho do arquivo de lock do agente é gravável
  • Configuração
  • Validação da chave Push API
    • Testa se a chave Push API que está sendo usada é uma chave válida no AppSignal.com.
  • Informações de caminho
    • Testa todos os caminhos necessários para verificar se são graváveis. Também exibe a propriedade do usuário atual.
    • current_path - caminho em que o comando diagnose é executado. Deve ser um caminho para a aplicação que você está tentando depurar. Geralmente o mesmo que root_path. (Somente Ruby)
    • root_path - caminho da aplicação. O AppSignal tentará encontrar um arquivo config/appsignal.rb/config/appsignal.yml aqui. (Somente Ruby)
    • log_dir_path - caminho em que o arquivo de log é criado.
    • log_file_path - caminho em que o arquivo de log é criado. Fica vazio se nenhum caminho viável puder ser encontrado.
  • Informações de instalação (Somente Ruby)
    • Algo pode ter dado errado durante a instalação do agente do AppSignal. Esta seção exibe os arquivos install.log e mkmf.log (log do Makefile).
As seguintes opções precisam estar configuradas corretamente para o AppSignal iniciar. É o mínimo absoluto, outras configurações também podem afetar a instrumentação.
  • A configuração Environment / env está definida.
  • A configuração name está definida.
  • A configuração push_api_key está definida.
  • A configuração active está definida como true.
  • A chave Push API é validada. Uma conexão com a internet é necessária para isso.

​
Configuração

A configuração é fundamental. É importante, porque sem ela o agente do AppSignal não saberá qual aplicação está instrumentando e em qual ambiente. Usando as informações do diagnóstico, vemos se podemos encontrar um problema com a configuração do agente. Os agentes do AppSignal têm vários métodos de configuração. Recomendamos que você leia o tópico de configuração para começar, especificamente a configuração mínima necessária, a ordem de carregamento da configuração e as páginas de opções de configuração se você estiver enfrentando problemas.

​
Nenhum dado aparecendo

Pode haver muitas razões pelas quais uma aplicação não está sendo detectada pelo AppSignal. Somente quando os servidores do AppSignal começam a receber dados de uma aplicação ela é criada na UI no AppSignal.com; se nenhum dado for recebido, nenhuma aplicação é criada. Quando uma integração está quebrada ou não configurada corretamente, pode demorar muito para rastrear o problema. Para descartar o agente do AppSignal e seu processamento, podemos enviar “amostras de demonstração”. 
# Ruby
appsignal demo --environment=development

# Elixir
MIX_ENV=prod mix appsignal.demo
# Ou com o binário de release
bin/your_app command appsignal_tasks demo

# Node.js
npx @appsignal/cli demo

# Python
python -m appsignal demo --environment=production
Este comando envia uma amostra falsa de requisição web e erro para os servidores do AppSignal para a aplicação. Uma vez que os dados são recebidos, os servidores do AppSignal começam a processar os dados e criam uma aplicação no AppSignal.com. Em cada integração, esse processo também é usado na ferramenta de linha de comando de instalação para ajudar no processo de instalação. Observe que o comando “demo” deve ser executado no diretório de uma aplicação que tenha o agente AppSignal instalado.

​
Logs

Quando nenhum problema é encontrado nas informações de diagnóstico, os logs do agente são a próxima coisa que você pode investigar. Os agentes do AppSignal criam arquivos de log para exibir informações úteis e problemas encontrados no próprio agente. Por padrão, os agentes registram logs de nível “info” e superiores (warning & error). Para registrar mais dados relevantes para depuração, defina a opção log_level (Ruby / Elixir / Python) / logLevel (Node.js) como debug.

​
Conteúdo dos logs

O arquivo de log do AppSignal contém informações de três componentes diferentes do AppSignal. Ele prefixará cada entrada de log com um carimbo de data/hora, nome do componente, PID do processo, indicador de nível de log e a própria mensagem de log. Os componentes do agente disponíveis são:
  • process Implementação específica da linguagem (Ruby / Elixir).
  • extension Extensão em C para a implementação da linguagem. Roda no mesmo processo que process.
  • agent Agente do sistema AppSignal em Rust. Um processo separado.

​
Análise da mensagem de log

​
Análise da mensagem de log do logger de arquivo

Text
[2016-10-19T11:06:18 (process) #11329][DEBUG] Starting appsignal
 ^                    ^         ^      ^      ^
 |                    |         |      |      Mensagem
 |                    |         |      Nível de log
 |                    |         PID do processo
 |                    Componente do agente
 Carimbo de data/hora no fuso horário do host

​
Análise da mensagem de log no STDOUT

Para loggers no STDOUT, o gem Ruby do AppSignal prefixa um identificador “appsignal” reconhecível à mensagem para que mensagens específicas do AppSignal possam ser filtradas com grep na saída de log do processo pai.
Text
[2016-10-19T11:06:18 (process) #11329][DEBUG] appsignal: Starting appsignal
 ^                    ^         ^      ^      ^          ^
 |                    |         |      |      |          Mensagem
 |                    |         |      |      Prefixo do AppSignal
 |                    |         |      Nível de log
 |                    |         PID do processo
 |                    Componente do agente
 Carimbo de data/hora no fuso horário do host

​
Localização dos logs

Existem dois métodos para salvar logs da biblioteca AppSignal. Gravando os logs em um arquivo de log e imprimindo os logs no STDOUT do processo. Veja a configuração log para mais informações. Os logs gravados em um arquivo de log não são gravados nos arquivos de log da sua aplicação, mas têm seu próprio arquivo appsignal.log. Dependendo das permissões de um host, o agente gravará os logs em uma localização diferente. O gem Ruby tentará primeiro criar um arquivo de log no diretório da aplicação. Para aplicações Ruby on Rails, ele criará um arquivo de log no diretório log/ em vez disso. Se não conseguir criar um arquivo de log, recorrerá ao diretório /tmp do sistema. É também onde outros arquivos do agente AppSignal são salvos. O pacote Elixir gravará os arquivos de log no arquivo de log /tmp/appsignal.log. Se ele falhar completamente em encontrar uma localização gravável para salvar seus logs, ele os exibirá no STDOUT do processo da aplicação pai. Isso também pode ser configurado com a opção :log. Atualmente, o agente do sistema não pode registrar no STDOUT, então sempre registrará no arquivo appsignal.log mesmo quando o log estiver configurado para STDOUT. Para deixar que o AppSignal informe onde gravará seus logs, veja a saída do comando diagnose.

​
Rotação de logs

O AppSignal não realiza rotação de logs para seus arquivos de log. Recomendamos configurar uma ferramenta do sistema como logrotate para gerenciar o tamanho e a retenção de arquivos.

​
Logs do agente standalone

Se você está usando o agente standalone do AppSignal, você pode acessar os logs com o seguinte comando:
Bash
sudo journalctl -u appsignal-agent
(O comando sudo pode ser opcional em certos ambientes, como containers.)

​
Arquivos de log no Heroku

Na plataforma de hospedagem Heroku, a biblioteca de integração registrará automaticamente no STDOUT. Como o agente não pode registrar no STDOUT, ele continuará gravando no arquivo appsignal.log. No Heroku, não é possível ver o conteúdo do arquivo de log com heroku run bash e depois ler o arquivo de log, devido à forma como os Dynos do Heroku são containerizados. O Heroku fornece um complemento chamado “Heroku Exec” para permitir a execução de comandos no mesmo container de dyno que sua aplicação. Usando este complemento, podemos ler o arquivo de log nos dynos da sua aplicação. 
# Instale o complemento Exec conforme descrito no site do Heroku:
# https://devcenter.heroku.com/articles/heroku-exec
$ heroku ps:exec
$ cat /path/to/appsignal.log

​
O agente está rodando?

Quando uma aplicação com integração AppSignal inicia, ela inicializa o agente do sistema AppSignal. Este agente roda como um processo separado e se comunica com a aplicação. Após processar dados de instrumentação, é esse agente que envia os dados aos servidores do AppSignal, não o agente específico da linguagem. Quando o agente do sistema não está rodando, nenhum dado pode ser processado ou enviado ao AppSignal. É importante saber se o agente do sistema está rodando. Você pode encontrá-lo na lista de processos com o nome appsignal-agent. 
ps aux | grep appsignal
Execute o comando ps na linha de comando do seu host para ver se o agente está rodando enquanto sua aplicação está rodando o AppSignal.

​
Outras perguntas

Pode haver muitos fatores em jogo quando um problema ocorre. Coisas a verificar quando o AppSignal parece não estar funcionando ou quando não há logs disponíveis.
  • Desde quando o problema ocorre?
    • O agente foi atualizado?
    • Outras bibliotecas foram atualizadas?
  • O que dizem os logs do agente AppSignal com a opção log_level definida como debug?
  • O Sistema Operacional é suportado?
  • A “extensão” foi instalada e carregada corretamente? As respostas devem estar na saída do “diagnose”.
  • A aplicação está rodando dentro de um sistema containerizado?
  • Os servidores da aplicação estão sincronizados usando NTP para evitar desvio de relógio?
  • Seu problema está mencionado em nossa lista de problemas conhecidos?

​
Criando um estado reproduzível

Se os passos descritos acima não mostraram uma causa para o problema, um bom próximo passo é tentar replicar a situação na configuração mais mínima possível. Crie uma aplicação de teste com o mínimo de configuração possível, carregando apenas as bibliotecas e dependências mínimas necessárias. Com este exemplo de aplicação reproduzível, podemos começar a rastrear a causa do problema.

​
Entre em contato

Não hesite em entrar em contato se você se deparar com algum problema ao depurar os agentes do AppSignal. Estamos aqui para ajudar.