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

# Como as integrações do AppSignal operam

O AppSignal consiste em muitos sistemas diferentes trabalhando juntos. Esta página explicará quais sistemas fazem parte das integrações que disponibilizamos para [Ruby](/ruby) e [Elixir](/elixir), e como eles trabalham juntos.

* [Bibliotecas de linguagem](#language-libraries)
* [Extensão](#extension)
* [Agente](#agent)
  * [Diretório de trabalho](#working-directory)
    * [Localização](#location)
    * [Permissões](#permissions)

## Bibliotecas de linguagem

A [gem Ruby](https://rubygems.org/gems/appsignal) e o [pacote Elixir](https://hex.pm/packages/appsignal) do AppSignal fornecem integração para suas respectivas linguagens de programação e bibliotecas populares (para [Ruby](/ruby/integrations) e [Elixir](/elixir/integrations)) do seu ecossistema, para fornecer relatórios de erros e insights de desempenho. Atualmente, é necessário usar uma dessas bibliotecas para integrar o AppSignal ao seu app e coletar [métricas de host](/metrics/host-metrics) do seu host.

Quando você instala a gem Ruby ou o pacote Elixir do AppSignal no seu app, uma [extensão](#extension) nativa para a linguagem de programação é compilada junto com ela. Essa extensão se comunica com o [agente](#agent) para processar seus dados de forma eficiente e enviá-los à [Push API](/appsignal/terminology#push-api) do AppSignal.

Quando você inicia sua aplicação com o AppSignal instalado, o agente do AppSignal será iniciado em segundo plano. Ele só iniciará um agente por configuração; se uma nova configuração for encontrada, um novo agente iniciará e os agentes de outras versões serão encerrados.

## Extensão

A extensão do AppSignal comunica entre a linguagem de programação e o agente do AppSignal. Uma parte é escrita em Rust e a outra na linguagem de programação C. A máquina host na qual o AppSignal está instalado, portanto, precisa de um [compilador C](https://en.wikipedia.org/wiki/C_%28programming_language%29) funcional presente. Geralmente isso já está instalado na máquina host, mas para muitas imagens Docker frequentemente não é o caso, a fim de manter as imagens pequenas. Os pacotes necessários para o seu sistema operacional estão listados em nossa página de [sistemas operacionais suportados](/support/operating-systems).

Há duas partes na extensão do AppSignal: a extensão C e a biblioteca estática/dinâmica escrita em [Rust](https://www.rust-lang.org/en-US/). A extensão C para [Ruby](https://github.com/appsignal/appsignal-ruby/blob/main/ext/appsignal_extension.c) e o [Nif](/elixir/why-nif) para [Elixir](https://github.com/appsignal/appsignal-elixir/blob/develop/c_src/appsignal_extension.c) implementarão a interface da biblioteca do AppSignal para que a biblioteca de linguagem do AppSignal possa se comunicar com ela. Uma biblioteca separada é usada para que a implementação possa ser compartilhada entre as [bibliotecas](#language-libraries) do AppSignal.

A extensão se comunica com o agente por meio de um socket, para o qual o ponteiro é armazenado no [diretório de trabalho](#working-directory) do agente. Essa comunicação é unidirecional: a extensão envia os dados gravados para o agente, e o agente envia isso para os servidores do AppSignal.

## Agente

Uma vez iniciado pela [extensão](#extension), o agente do AppSignal continuará em execução em segundo plano da sua aplicação como um processo daemonizado. Ele lidará com conexões de vários clientes (processos do app por meio da [extensão](#extension)) quando necessário. Por exemplo, se você executar tanto o Unicorn (servidor web) quanto o Sidekiq (biblioteca de jobs em background) ao mesmo tempo, haverá apenas um agente do AppSignal em execução para ambos os processos. Se a conexão com o agente for perdida, os clientes se reconectarão automaticamente e/ou iniciarão um novo agente. (Comportamento de reinicialização adicionado na versão `2.4.0` da gem Ruby, versão `1.4.0` do pacote Elixir e Node.js `1.0.0`).

Na inicialização, o agente tentará localizar um [diretório de trabalho](#working-directory) adequado no qual possa armazenar alguns de seus arquivos operacionais temporários. Ele precisa criar e gravar arquivos no diretório de trabalho e criar o arquivo `appsignal.log` antes de poder iniciar adequadamente. Se falhar em fazê-lo, não iniciará corretamente e sairá. O agente requer um local para armazenar o arquivo `appsignal.log`, pois o valor `stdout` para a opção de configuração `log` (para [Ruby](/ruby/configuration/options#option-log) e [Elixir](/elixir/configuration/options#option-log)) não se aplicará ao agente. O agente não pode comunicar seus logs de volta pelo socket com a extensão.

O agente em si é um processo leve escrito em [Rust](https://www.rust-lang.org/en-US/), que usa muito pouco recursos. Ele só mantém seus dados em memória por um tempo muito curto até enviá-los à Push API do AppSignal, após o que descarrega os dados. Se não puder se conectar à Push API do AppSignal, armazenará temporariamente os dados em disco, veja [diretório de trabalho](#working-directory).

Ao longo do tempo, o agente receberá dados de monitoramento dos seus apps e começará a agregá-los. Após um intervalo de transmissão de 30 segundos, ele enviará os dados agregados à Push API do AppSignal. Aqui serão processados, incidentes e alertas de Detecção de anomalias são criados e, eventualmente, notificações são enviadas para você, o usuário.

Periodicamente, o agente também lerá as estatísticas do sistema da máquina em que está sendo executado para coletar [métricas de host](/metrics/host-metrics). Isso é feito com a ajuda da biblioteca [probes-rs](https://github.com/appsignal/probes-rs) escrita pelo AppSignal. Os dados de métricas de host são usados para o recurso de métricas de host para fornecer gráficos e para mostrar dados de métricas de host para [amostras](/appsignal/terminology#samples) naquele momento.

Se uma requisição à nossa [Push API](/appsignal/terminology#push-api) falhar, o payload dessa requisição é gravado em disco no [diretório de trabalho](#working-directory) e tentará reenviar o payload no próximo intervalo de transmissão.

### Diretório de trabalho

O diretório de trabalho é usado para várias coisas que o agente do AppSignal precisa para continuar operando. É uma parte necessária para poder executar o agente do AppSignal. Se nenhum lugar adequado para o diretório de trabalho puder ser encontrado, o agente será encerrado e a extensão no seu app se desabilitará. Não reportará mais nenhum dado aos servidores do AppSignal.

As responsabilidades do diretório de trabalho:

* Localização de fallback do `appsignal.log`
  * O diretório de trabalho funciona como o local de fallback para o arquivo `appsignal.log` quando nenhum caminho válido pode ser detectado e o local `log_path` fornecido não é utilizável (opção de configuração para [Ruby](/ruby/configuration/options#option-log_path) e [Elixir](/elixir/configuration/options#option-log_path)). Se nenhum local adequado for encontrado, como no diretório `log/` do seu projeto, ele será armazenado em `{working_directory}/appsignal.log`. Leia mais sobre os [logs do AppSignal](/support/debugging#logs).
* Armazenamento do arquivo `agent.socket`
  * O agente do AppSignal armazena um arquivo de socket em `{working_directory}/agent.socket`, que é usado pela extensão do AppSignal na sua aplicação para se comunicar com o agente. Sempre que uma transação do AppSignal termina ou você envia uma métrica personalizada, esses dados são gravados no socket e recebidos pelo agente. Ele então agrega esses dados e os transmite à Push API do AppSignal.
* Armazenamento do arquivo `agent.lock`
  * O agente do AppSignal armazena um arquivo de lock (`agent.lock`) para garantir que haja apenas uma instância do agente em execução com a configuração do seu app. Se uma nova versão do agente for iniciada, versões mais antigas serão encerradas quando detectarem que uma versão mais nova está em execução, permitindo que o agente recém-iniciado lide com todos os dados recebidos a partir desse ponto.
  * Usar um único diretório de trabalho, e arquivo de lock, para vários apps em execução na mesma máquina pode criar algum comportamento estranho. Por esse motivo, recomendamos usar um diretório de trabalho por app. Leia mais sobre [como executar várias aplicações em um único host](/application/#running-multiple-applications-on-one-host).
  * Se você excluir esse arquivo, ou o diretório de trabalho inteiro, o agente será encerrado imediatamente.
* Armazenamento de `payloads`
  * O diretório payloads contém payloads em cache gravados em disco para quando o agente está tendo problemas para se conectar à nossa Push API. Para evitar que o consumo de memória do agente aumente ao longo do tempo, esses dados são armazenados temporariamente em disco. Isso nos permite garantir que não perderemos nenhum dos seus preciosos dados se sua conexão de rede estiver fora por um tempo limitado ou se nossa Push API tiver um pequeno soluço. A quantidade de payloads armazenada em disco é automaticamente limitada aos últimos payloads, então isso sempre usará um pequeno espaço em disco.

#### Localização

A localização padrão do diretório de trabalho é `/tmp/appsignal`. Se você usa uma estrutura de diretório no estilo [Capistrano](http://capistranorb.com/), ele criará um diretório chamado `appsignal` em `app/shared`. Em deploys no estilo [Heroku](https://heroku.com), ele criará o diretório em `/app/tmp`. Se nenhum desses caminhos for detectado, o diretório do AppSignal será criado no local padrão.

A localização do diretório de trabalho pode ser personalizada com a opção de configuração `working_directory_path` ([Ruby](/ruby/configuration/options#option-working_directory_path) / [Elixir](/elixir/configuration/options#option-working_directory_path)). Qualquer caminho configurado dessa forma terá precedência sobre qualquer caminho que ele possa detectar.

#### Permissões

Por padrão, o diretório de trabalho é gravável para todos (permissões Unix `0666`). Esse é o padrão, porque ao longo do tempo vimos muitas solicitações de suporte que se originaram do diretório de trabalho existir, mas não ser gravável pelo agente do AppSignal. Por exemplo: quando o app é iniciado pelo usuário de deploy no deploy do app, mas por outro usuário durante uma reinicialização do host. Isso dá a propriedade do diretório a uma das contas de usuário, tornando-o não gravável para o outro usuário.

É possível desabilitar as permissões globais de leitura e escrita (e dar ao diretório de trabalho permissões Unix `0644`) definindo a opção de configuração `files_world_accessible` ([Ruby](/ruby/configuration/options#option-files_world_accessible) / [Elixir](/elixir/configuration/options#option-files_world_accessible)) como `false` para seus apps.