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

# Puma

export const VersionRequirements = ({versions = []}) => {
  if (!Array.isArray(versions) || versions.length === 0) {
    return null;
  }
  const boundaries = {
    upper: " or lower",
    exact: "",
    lower: " or higher"
  };
  const containerStyle = {
    marginTop: "0.5rem",
    marginBottom: "1.5rem"
  };
  const lineStyle = {
    display: "block",
    margin: "0 0 0.35rem 0",
    fontSize: "0.875rem",
    lineHeight: "1.4"
  };
  const pillBaseStyle = {
    display: "inline-block",
    padding: "0.1em 0.4em",
    borderRadius: "0.25rem",
    border: "1px solid",
    fontFamily: "ui-monospace, SFMono-Regular, Menlo, monospace",
    fontSize: "0.85em",
    fontWeight: 500
  };
  const pillColors = {
    "AppSignal for Elixir": {
      background: "#f3e8ff",
      borderColor: "#e9d5ff",
      color: "#9333ea"
    },
    "AppSignal for Front-end": {
      background: "#fef9c3",
      borderColor: "#fde68a",
      color: "#ca8a04"
    },
    "AppSignal for Go": {
      background: "#ccfbf1",
      borderColor: "#99f6e4",
      color: "#0d9488"
    },
    "AppSignal for JavaScript": {
      background: "#fef9c3",
      borderColor: "#fde68a",
      color: "#ca8a04"
    },
    "AppSignal for Node.js": {
      background: "#dcfce7",
      borderColor: "#bbf7d0",
      color: "#16a34a"
    },
    "AppSignal for Python": {
      background: "#dbeafe",
      borderColor: "#bfdbfe",
      color: "#2563eb"
    },
    "AppSignal for Ruby": {
      background: "#fee2e2",
      borderColor: "#fecaca",
      color: "#dc2626"
    },
    "AppSignal for Rust": {
      background: "#ffedd5",
      borderColor: "#fed7aa",
      color: "#ea580c"
    }
  };
  const defaultPillColor = {
    background: "#f4f4f5",
    borderColor: "#e4e4e7",
    color: "#52525b"
  };
  const getPillStyle = name => ({
    ...pillBaseStyle,
    ...pillColors[name] || defaultPillColor
  });
  const getBoundText = bound => {
    return boundaries[bound] || boundaries.lower;
  };
  return <div style={containerStyle}>
      {versions.map((v, i) => <p key={`${v.name}-${v.version}-${v.bound || "lower"}-${i}`} style={lineStyle}>
          This feature requires{" "}
          <code style={getPillStyle(v.name)}>{v.name}</code> version {v.version}
          {getBoundText(v.bound)}.
        </p>)}
    </div>;
};

<VersionRequirements
  versions={[
{ name: "AppSignal for Ruby", version: "3.0.7" },
{ name: "Puma", version: "3.11.4" }
]}
/>

O [Puma](http://puma.io/) foi construído para velocidade e paralelismo. O Puma é uma pequena biblioteca que fornece um servidor HTTP 1.1 rápido e concorrente para aplicações web Ruby.

A gem AppSignal Ruby insere automaticamente um listener no servidor Puma; nenhuma configuração manual é necessária.

## Plugin de métricas do Puma

O plugin do AppSignal para o Puma irá [coletar métricas sobre como o Puma está operando](#metrics). Quando o AppSignal detecta métricas do Puma, ele criará um [Magic Dashboard](#magic-dashboard), permitindo que você monitore métricas principais visualmente.

Para habilitar a coleta de métricas, adicione o plugin AppSignal à sua configuração do Puma:

<CodeGroup>
  ```ruby Ruby theme={null}
  # puma.rb (ou config/puma.rb)
  plugin :appsignal
  ```
</CodeGroup>

<Tip>
  O servidor StatsD incluído no AppSignal Agent deve estar ativo para que o
  plugin de métricas do Puma funcione. Certifique-se de que [a opção de
  configuração `enable_statsd`](/ruby/configuration/options#option-enable_statsd)
  não esteja definida como `false`.
</Tip>

O Puma pode exigir configuração adicional para carregar os [secrets](#configuration-secrets) da sua aplicação, que podem ser necessários para o AppSignal iniciar.

## Uso com `prune_bundler`

Se o seu arquivo `puma.rb` inclui `prune_bundler`, você deve adicionar o AppSignal como uma dependência de runtime.

<Tip>
  Para usar o Puma com `prune_bundler`, é necessária a versão 4.2.0 ou superior do Puma.
</Tip>

<CodeGroup>
  ```ruby Ruby theme={null}
  # puma.rb (ou config/puma.rb)
  prune_bundler

  plugin :appsignal
  extra_runtime_dependencies ["appsignal"]
  ```
</CodeGroup>

## Uso com `preload_app!`

Se o seu arquivo `puma.rb` inclui `preload_app!`, alguma configuração é necessária para reportar corretamente as métricas dos [minutely probes](/ruby/instrumentation/minutely-probes). Quando `preload_app!` é true, os minutely probes são executados no processo primary do Puma. No processo primary, os probes não conseguem acessar os mesmos dados que o app rodando nos workers do Puma pode, reportando dados imprecisos ou nenhum dado.

No arquivo de configuração `puma.rb` do Puma, pare os minutely probes do AppSignal no callback `before_fork` para parar os minutely probes no processo principal do Puma. Em seguida, inicie os minutely probes no processo worker a partir do callback `on_worker_boot`.

<CodeGroup>
  ```ruby Ruby theme={null}
  # puma.rb ou config/puma.rb

  # Quando preload_app! está definido
  preload_app!


  # Adicione este callback before_fork para parar os minutely probes no processo principal do Puma
  before_fork do
    Appsignal::Probes.stop
  end

  # Adicione este callback on_worker_boot para iniciar os minutely probes nos processos worker do Puma
  on_worker_boot do
    Appsignal::Probes.start
  end
  ```
</CodeGroup>

## Secrets

Se você usa uma biblioteca como [Rails](https://guides.rubyonrails.org/security.html#custom-credentials) ou [dotenv](https://github.com/bkeepers/dotenv) para gerenciar os secrets do seu app e configurar o AppSignal, você precisará carregá-los na sua configuração do Puma.

O AppSignal executa um processo em background no processo principal do Puma quando se usa o plugin do Puma. O resto do seu app não é carregado por padrão no processo principal do Puma (a menos que você use `preload_app!`, que pode não ser adequado para o seu app). Sem configuração adicional, a config do AppSignal falhará ao carregar, e o AppSignal não iniciará.

Nenhum hook "on boot" está disponível no Puma para carregar sua configuração extra no processo principal. Para carregar sua configuração, adicione-a à raiz do seu arquivo de configuração `puma.rb`, como no exemplo abaixo.

<CodeGroup>
  ```ruby Ruby theme={null}
  # puma.rb (ou config/puma.rb)
  plugin :appsignal # Adicione este plugin

  # Secrets do Rails
  # Adicione esta linha ao usar secrets do Rails no seu arquivo `config/appsignal.rb` ou `config/appsignal.yml`.
  require "rails"

  # Adicione esta seção ao usar dotenv para gerenciamento de secrets
  require "dotenv"
  Dotenv.load
  # ou para apps Rails:
  require "dotenv/load"
  Dotenv.load


  # Resto da sua configuração do Puma...
  ```
</CodeGroup>

### Hostname {/* id: minutely-probe-configuration-hostname */}

Este probe escuta a [opção de configuração `APPSIGNAL_HOSTNAME` da variável de
ambiente](/ruby/configuration/options#option-hostname) para a tag hostname
adicionada a todas as suas métricas. Se nenhuma for definida, ele tentará detectá-la automaticamente.
Use a variável de ambiente do sistema `APPSIGNAL_HOSTNAME` para definir o hostname caso
queira alterar o hostname detectado.

### Porta do StatsD

Este probe escuta a [opção de configuração `APPSIGNAL_STATSD_PORT` da variável de ambiente](/ruby/configuration/options#option-statsd_port) para a configuração de portas StatsD não padrão. Se a variável de ambiente não estiver definida, o padrão é 8125. Para o processo principal do Puma, é necessário usar a variável de ambiente; ele não lerá a configuração de arquivo do AppSignal.

## Phased restart {/* id: minutely-probe-phased-restart */}

[Phased restarts](https://github.com/puma/puma/blob/master/docs/restart.md) do Puma
não reiniciam o processo principal do Puma, o que significa que o processo em background do AppSignal
também não é reiniciado em um phased restart. Se você fez alterações na
config do AppSignal, será necessário reiniciar completamente seu app Puma depois para
que a mudança de configuração tenha efeito.

<CodeGroup>
  ```sh Shell theme={null}
  # Após alterar a config do AppSignal, reinicie usando:
  pumactl restart
  # em vez de: pumactl phased-restart
  ```
</CodeGroup>

## Magic dashboard

Quando o AppSignal recebe métricas do Puma, ele criará um magic dashboard do Puma, disponível na seção de dashboard do app AppSignal.

O magic dashboard do Puma terá os seguintes gráficos:

| Gráfico                                         | Métricas                  | Tags                                            |
| ----------------------------------------------- | ------------------------- | ----------------------------------------------- |
| [Connection backlog](#connection-backlog-graph) | `puma_connection_backlog` | `hostname`                                      |
| [Pool capacity](#pool-capacity-graph)           | `puma_pool_capacity`      | `hostname`                                      |
| [Threads](#threads-graph)                       | `puma_threads`            | <li>`max`</li><li>`running`</li>                |
| [Worker info](#worker-info-graph)               | `puma_workers`            | <li>`booted`</li><li>`count`</li><li>`old`</li> |

As tags fornecem um detalhamento contextual das informações de performance do Active job. O AppSignal reporta as seguintes tags para jobs do Active Job:

| Nome       | Descrição                                                                                                                                                |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `booted`   | Número total de workers atualmente inicializados para este servidor.                                                                                     |
| `count`    | Número de threads atualmente em execução para este servidor.                                                                                             |
| `hostname` | Nome do host do qual a métrica foi reportada.                                                                                                            |
| `max`      | Número máximo de threads configuradas para este servidor.                                                                                                |
| `old`      | Número de workers executando a configuração/código anterior do servidor no momento. O Puma irá desativá-los gradualmente conforme novos workers iniciam. |
| `running`  | Número de threads atualmente em execução para este servidor                                                                                              |

Os gráficos permitem que você monitore as métricas da sua aplicação visualmente. Você pode adicionar marcadores aos gráficos e clicar em qualquer ponto de dados para obter insights sobre o estado da sua aplicação naquele momento.

<img src="https://mintcdn.com/appsignal-715f5a51/4TRZP0Sq9Zq7PAPW/assets/images/screenshots/ruby/integrations/puma/dashboard-graphs.png?fit=max&auto=format&n=4TRZP0Sq9Zq7PAPW&q=85&s=b9c868a34aedc2a6ee3f1e870c0e97c8" alt="Exemplo de magic dashboard do Puma" width="1432" height="672" data-path="assets/images/screenshots/ruby/integrations/puma/dashboard-graphs.png" />

### Gráfico Connection backlog

O gráfico Connection backlog mostra a quantidade de conexões de entrada para o servidor que estão aguardando para serem atendidas na fila de backlog do servidor.

Você pode usar o gráfico Connection backlog para monitorar quantas requisições estão aguardando para serem tratadas e identificar gargalos do Puma.

### Gráfico Pool capacity

O gráfico Pool capacity mostra a quantidade de threads do Puma disponíveis para receber requisições, incluindo threads do Puma que ainda não foram criadas.

Você pode usar o gráfico Pool capacity para monitorar a disponibilidade das threads do Puma e otimizar os workers.

### Gráfico Threads

O gráfico Threads mostra informações sobre as threads criadas pelo Puma para atender requisições web, agregadas em todos os workers do Puma. Para atender requisições web, o Puma criará mais threads quando necessário. O gráfico mostrará a quantidade de threads em execução em comparação ao número máximo disponível de threads.

Você pode usar o gráfico Threads para monitorar a demanda e a oferta de threads do Puma e otimizar os workers.

### Gráfico Worker info

O gráfico Worker info mostra quantos workers do Puma estão funcionando e qual versão do seu site eles estão usando. A linha count mostra quantos workers estão funcionando no total, enquanto as linhas booted e old mostram quantos workers estão usando a nova versão e quantos workers estão usando a versão antiga da sua aplicação.

Você pode usar o gráfico worker info para monitorar o status e a performance dos seus workers do Puma e ver quantos workers estão rodando em uma configuração desatualizada da sua aplicação.

[thread pool]: https://github.com/puma/puma/#thread-pool

[clustered mode]: https://github.com/puma/puma/#clustered-mode