> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appsignal.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Depurando o AppSignal
> Um procedimento de depuração usado para depurar problemas com o AppSignal ou a configuração em uma aplicação monitorada pelo AppSignal.
Quando uma solicitação de suporte chega em [support@appsignal.com](mailto: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](/support/known-issues) para uma lista de problemas que podem afetar sua aplicação.
## Diagnóstico
Nosso [gem Ruby](/ruby), [pacote Elixir](/elixir), [pacote Node.js](/nodejs/3.x) e [pacote Python](/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.
```bash Bash theme={null}
# 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.
```bash Bash theme={null}
# 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](/appsignal/terminology#agent)
* 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
* Ambiente
* O gem Ruby emite um aviso se nenhum for encontrado.
* Lista de opções de configuração
* Veja todas as opções de configuração disponíveis:
* [Opções do gem Ruby](/ruby/configuration/options)
* [Opções do pacote Elixir](/elixir/configuration/options)
* [Opções do pacote Node.js](/nodejs/3.x/configuration/options)
* [Opções do pacote Python](/python/configuration/options)
* 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](#diagnose), 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.
* Visão geral da configuração:
[Ruby](/ruby/configuration) /
[Elixir](/elixir/configuration) /
[Node.js](/nodejs/3.x/configuration) /
[Python](/python/configuration)
* Configuração mínima necessária:
[Ruby](/ruby/configuration/#minimal-required-configuration) /
[Elixir](/elixir/configuration/#minimal-required-configuration) /
[Node.js](/nodejs/3.x/configuration/#minimal-required-configuration) /
[Python](/python/configuration/#minimal-required-configuration)
* Ordem de carregamento da configuração:
[Ruby](/ruby/configuration/load-order) /
[Elixir](/elixir/configuration/load-order) /
[Node.js](/nodejs/3.x/configuration/load-order) /
[Python](/python/configuration/load-order)
* Opções de configuração:
[Ruby](/ruby/configuration/options) /
[Elixir](/elixir/configuration/options) /
[Node.js](/nodejs/3.x/configuration/options) /
[Python](/python/configuration/options)
## 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".
```bash Bash theme={null}
# 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](/ruby/configuration/options#option-log_level) / [Elixir](/elixir/configuration/options#option-log_level) / [Python](/python/configuration/options#option-log_level)) / `logLevel` ([Node.js](/nodejs/3.x/configuration/options#option-logLevel)) 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 Text theme={null}
[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 Text theme={null}
[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`](/ruby/configuration/options#option-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](#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 Bash theme={null}
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](http://heroku.com/), 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](https://devcenter.heroku.com/articles/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.
```bash Bash theme={null}
# 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`.
```bash Bash theme={null}
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](/support/operating-systems) é suportado?
* A "extensão" foi instalada e carregada corretamente?
As respostas devem estar na [saída do "diagnose"](#diagnose).
* A aplicação está rodando dentro de um sistema containerizado?
* Os servidores da aplicação estão sincronizados usando [NTP](/support/about-time) para evitar desvio de relógio?
* Seu problema está mencionado em nossa lista de [problemas conhecidos](/support/known-issues)?
## 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](mailto:support@appsignal.com) se você se deparar com
algum problema ao depurar os agentes do AppSignal. Estamos aqui para ajudar.