solid_apm

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/]

Data Cleanup

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

Manual Cleanup

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]

Automated Cleanup with ActiveJob

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"]

How it works

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.

Request transaction

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.

Spans saved

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

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.