SolidApm
Rails engine to manage APM data without using a third party service.
Installation
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
Usage
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
Configuration
SolidAPM can be configured using the following options in your config/initializers/solid_apm.rb
file:
Database Connection
Configure the database connection for SolidAPM:
SolidApm.connects_to = { database: { writing: :solid_apm } }
ActiveRecord Logger Silencing
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
Transaction Sampling
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.
Transaction Name Filtering
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/]
MCP Server
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.
MCP Server Configuration
The MCP server is only mounted if the fast-mcp gem is installed by your application.
- 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'
- 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]
}
- 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}
MCP usage
- Add the MCP resource
impactful-transactions
to the context of your prompt. - Prompt example: "Analyze the impactful transactions of my application and suggest improvements, base on the spans details."
- Allow the AI agent to use the MCP tool
spans-for-transaction
to retrieve the longest spans for a specific transaction.
TODOs
Features
- Better handle subscribing to ActiveSupport notifications
- Custom events
Interface
- Paginate transactions list
- Allow date range transactions index
Contributing
Contribution directions go here.
Release
bin/bump major|minor|patch
# GitHub Actions will take care of the rest
License
The gem is available as open source under the terms of the MIT License.