Ruby Gem Installation

Installation

Add the gem to your Gemfile:

gem 'miniapm'

Install with Bundler:

bundle install

Rails Setup (Recommended)

Generate the configuration file:

rails generate miniapm:install

This creates config/initializers/miniapm.rb:

MiniAPM.configure do |config|
  # MiniAPM server URL
  config.endpoint = ENV.fetch('MINI_APM_URL', 'http://localhost:3000')

  # Your API key from MiniAPM
  config.api_key = ENV['MINI_APM_API_KEY']

  # Service name shown in traces
  config.service_name = 'my-rails-app'

  # Current environment
  config.environment = Rails.env
end

Configuration Options

Option	Default	Description
endpoint	http://localhost:3000	MiniAPM server URL
api_key	nil	API key for authentication
service_name	rails-app	Service identifier in traces
environment	Rails.env	Environment name
service_version	nil	Version string for deploy tracking
sample_rate	1.0	Sampling rate (0.0 to 1.0)
batch_size	100	Max spans per batch
flush_interval	5.0	Seconds between flushes
max_queue_size	10000	Max queued items before dropping
enabled	true	Enable/disable tracing
auto_start	true	Start on Rails boot

Full Configuration Example

MiniAPM.configure do |config|
  # Required
  config.endpoint = ENV.fetch('MINI_APM_URL', 'http://localhost:3000')
  config.api_key = ENV['MINI_APM_API_KEY']
  config.service_name = 'my-app'

  # Optional: Service metadata
  config.environment = Rails.env
  config.service_version = ENV['GIT_SHA']
  config.git_sha = ENV['GIT_SHA']

  # Optional: Sampling (for high-traffic apps)
  config.sample_rate = Rails.env.production? ? 0.1 : 1.0

  # Optional: Batching
  config.batch_size = 100
  config.flush_interval = 5.0
  config.max_queue_size = 10000

  # Optional: Enable/disable
  config.enabled = !Rails.env.test?

  # Optional: Instrumentation control
  config.instrument :activerecord, log_sql: true
  config.instrument :redis, enabled: false

  # Optional: Filter sensitive parameters
  config.filter_parameters = [:password, :token, :api_key, :secret]

  # Optional: Ignore specific exceptions
  config.ignored_exceptions = [
    'ActionController::RoutingError',
    'ActionController::InvalidAuthenticityToken'
  ]

  # Optional: Custom span processing
  config.before_send = ->(span) {
    # Modify or filter spans before sending
    span
  }
end

Environment Variables

You can also configure MiniAPM entirely through environment variables:

export MINI_APM_URL=http://localhost:3000
export MINI_APM_API_KEY=proj_abc123...
export MINI_APM_SERVICE_NAME=my-app
export MINI_APM_ENVIRONMENT=production

Disabling in Tests

By default, MiniAPM is disabled when Rails.env.test? returns true. You can also explicitly disable it:

MiniAPM.configure do |config|
  config.enabled = !Rails.env.test?
end

Manual Initialization

If you’re not using Rails, initialize MiniAPM manually:

require 'miniapm'

MiniAPM.configure do |config|
  config.endpoint = 'http://localhost:3000'
  config.api_key = 'proj_abc123...'
  config.service_name = 'my-ruby-app'
  config.auto_start = false
end

# Start manually when ready
MiniAPM.start!

Verifying Installation

Check if MiniAPM is connected:

if MiniAPM.healthy?
  puts "Connected to MiniAPM server"
else
  puts "Cannot reach MiniAPM server"
end

Check current configuration:

puts MiniAPM.configuration.inspect