SolidApm

Rails engine to manage APM data without using a third party service.

Add to your Gemfile:

bin/bundle add solid_apm

Mount the engine in your routes file:

# config/routes.rb
Rails.application.routes.draw do
  mount SolidApm::Engine => "/solid_apm"
end

Routing constraint can be use to authorize access. See Routing constraint for more information.

Configure the database connection:

# config/initializers/solid_apm.rb
SolidApm.connects_to = { database: { writing: :solid_apm } }

Install and run the migrations:

DATABASE=solid_apm bin/rails solid_apm:install:migrations

Go to http://localhost:3000/solid_apm and start monitoring your application.

Add context

class ApplicationController
  before_action do
    SolidApm.set_context(user_id: current_user&.id)
  end
end

SolidAPM can be configured using the following options in your config/initializers/solid_apm.rb file:

Configure the database connection for SolidAPM:

SolidApm.connects_to = { database: { writing: :solid_apm } }

Control whether ActiveRecord logger is silenced during SolidAPM operations (default: true):

# Disable ActiveRecord logger silencing to see SQL queries in logs
SolidApm.silence_active_record_logger = false

Control the sampling rate for transactions using a "1 out of N" approach (default: 1):

# Sample every transaction (default behavior)
SolidApm.transaction_sampling = 1

# Sample 1 out of every 2 transactions (50% sampling)
SolidApm.transaction_sampling = 2

# Sample 1 out of every 5 transactions (20% sampling)  
SolidApm.transaction_sampling = 5

# Sample 1 out of every 10 transactions (10% sampling)
SolidApm.transaction_sampling = 10

The sampling is done per-thread using a round-robin counter, ensuring even distribution across requests. This is useful for high-traffic applications where you want to reduce the volume of APM data while still maintaining representative performance insights.

Filter specific transactions by name using exact string matches or regular expressions:

# Filter specific transactions by exact name
SolidApm.transaction_filters += ['HomeController#index', /^Rails::HealthController/]

SolidAPM provides a rake task to clean up old transaction data to manage database size over time.

Clean up transactions older than 1 month (default):

bin/rails solid_apm:cleanup

Clean up transactions with custom time periods:

# Delete transactions older than 1 week
bin/rails solid_apm:cleanup[1.week.ago]

For production applications, it's recommended to set up automated cleanup.

Example with SolidQueue. Configure recurring cleanup in your config/recurring.yml:

solid_apm_cleanup_weekly:
  class: SolidApm::CleanupJob  
  cron: "0 3 * * *"   # Every day at 3 AM
  args: ["1.week.ago"]

SolidAPM stores information in the form of transactions, representing incoming HTTP requests which listen to a variety of spans (events) from ActiveSupport::Instrument. Each span saves backtrace information to easily find the source of issues.

It is based on ActionDispatch events to start and end a transaction.

A Rack middleware uses rack.after_reply to bulk insert transactions and spans after delivering the response, so tracking your application doesn't add delay to the client.

• Request
• Rendering
• SQL requests and transactions
• Rails cache
• Net/HTTP

SolidAPM offers an optional MCP server to allow an AI agent to interact with SolidAPM and help identify issues in your application, such as
N+1 queries, slow queries and more. The AI agent can analyze and suggest fixes for these issues.

The MCP server is only mounted if the fast-mcp gem is installed by your application.

1. Add to your Gemfile:

# Work in progress, plus patch for MCP 2025-06-18 Protocol Revision
# with StreamableHTTP support
# https://github.com/yjacquin/fast-mcp/issues/109
gem 'fast-mcp', branch: 'transport', github: 'Bhacaz/fast-mcp'

2. Configure the MCP server in your config/initializers/solid_apm.rb:

SolidApm.mcp_server_config = {
  name: 'my-app-solid-apm',
  path: '/solid_apm/mcp',
  auth_token: Rails.application.credentials.solid_apm[:mcp_auth_token]
}

3. Test the MCP server by running:

curl -X POST http://localhost:3000/solid_apm/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <AUTH_TOKEN>" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}

1. Add the MCP resource impactful-transactions to the context of your prompt.
2. Prompt example: "Analyze the impactful transactions of my application and suggest improvements, base on the spans details."
3. Allow the AI agent to use the MCP tool spans-for-transaction to retrieve the longest spans for a specific transaction.

• Better handle subscribing to ActiveSupport notifications
• Custom events

• Paginate transactions list
• Allow date range transactions index

Contribution directions go here.

bin/bump major|minor|patch
# GitHub Actions will take care of the rest

The gem is available as open source under the terms of the MIT License.