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.

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}

MCP usage

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.

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.