Puma

Puma was built for speed and parallelism. Puma is a small library that provides a very fast and concurrent HTTP 1.1 server for Ruby web applications.

Usage

The AppSignal Ruby gem automatically inserts a listener into the Puma server. No further action is required.

Minutely probe

Since AppSignal Ruby gem 2.9.0 and up a minutely probe is activated by default. Once we detect these metrics we'll add a magic dashboard to your apps.

To enable the minutely probe, add the AppSignal plugin to your Puma configuration. This plugin will ensure AppSignal is started in Puma's main process. Which allows us to track Puma metrics in its single and clustered mode.

# puma.rb
plugin :appsignal # Available Ruby gem 2.9.17 and higher

Your app may require additional configuration for AppSignal to start in the Puma main process to collect metrics.

Metrics

This probe will report the following metrics grouped by hostname tag:

• puma_workers - gauge
  • Tag type:
    • count: number of currently running threads for this server.
    • booted: the total number of currently booted workers for this server.
    • old: the number of workers running the previous configuration/code of the server at the moment in time. These will be phased out by Puma as new workers start.
• puma_threads - gauge
  • Tag type:
    • running: number of currently running threads for this server.
    • max: maximum number of configured threads for this server.
• puma_connection_backlog - gauge
  • The number of established but unaccepted connections that are in the server backlog queue and still need to be processed.
• puma_pool_capacity - gauge
  • The total thread pool capacity of the Puma server, including the number of threads that are waiting to be booted.

Configuration

By default the Puma main process doesn't start your app. This means AppSignal isn't loaded by default either. To remedy this, add the AppSignal Puma plugin to your Puma config.

# puma.rb
plugin :appsignal

Additional configuration may be required to load your app config and/or secrets as well in order to load the AppSignal config.

In combination with prune_bundler you will need to add AppSignal as a runtime dependency.

# puma.rb
plugin :appsignal
extra_runtime_dependencies ["appsignal"]

Secrets

If you use a library such as Rails or dotenv to manage your app's secrets and configure AppSignal, you will need to load these in your Puma configuration.

Using the Puma plugin AppSignal loads a minutely probe in Puma's main process. The rest of your app is not loaded by default in Puma's main process (unless you use preload_app!, which may not be suitable for your app). Without additional configuration the AppSignal config will fail to load and AppSignal will not start.

There are no hooks "on boot"-hook available in Puma to load your extra config in the main process. To load your additional config add it to the root of your puma.rb configuration file like in the example below.

# puma.rb / config/puma.rb
plugin :appsignal # Add this plugin
 
# Rails secrets
# Add this line when using Rails secrets in your `config/appsignal.yml` file.
require "rails"
 
# Dotenv
# Add this section when using dotenv for secrets management
require "dotenv"
Dotenv.load
# or for Rails apps
require "dotenv/rails-now"
 
# Rest of your Puma config...

Hostname

This probe listens to the hostname config option for the hostname tag added to all its metrics. If none is set it will try to detect it automatically. Use the hostname config option to set the hostname if you want to change the detected hostname.

Phased restart

Puma phased restarts don't restart the main Puma process. This means that the AppSignal minutely probe does not get restarted either on a phased restart. If you have made changes to the AppSignal config, you will need to do a full restart of your Puma app afterward to have the configuration change take effect.

# Change AppSignal config, restart once using:
pumactl restart
# instead of
pumactl phased-restart