Auto-instrumentation

The MiniAPM gem automatically instruments popular Ruby libraries using ActiveSupport::Notifications and targeted monkey-patching.

How It Works

When Rails boots, MiniAPM’s Railtie:

1. Inserts middleware into the request stack
2. Subscribes to ActiveSupport::Notifications events
3. Applies instrumentation to detected libraries
4. Creates spans automatically with contextual attributes

Rails Instrumentation

ActionController

Automatically traced:

• Request method and path
• Controller and action names
• Response status
• Total request duration

Captured attributes:

• http.method - GET, POST, etc.
• http.route - Controller#action
• http.status_code - Response status
• http.request_id - Rails request ID

ActionView

Automatically traced:

• Template rendering
• Partial rendering
• Layout rendering

Captured attributes:

• view.template - Template path
• view.layout - Layout name

ActiveRecord

Automatically traced:

• All SQL queries
• Query execution time
• Database operations

Captured attributes:

• db.system - Database type (postgresql, mysql, sqlite)
• db.statement - SQL query (sanitized)
• db.operation - SELECT, INSERT, UPDATE, DELETE

Enable full SQL logging:

config.instrument :activerecord, log_sql: true

Background Jobs

ActiveJob

Automatically traced:

• Job execution
• Queue time
• Job failures

Captured attributes:

• job.class - Job class name
• job.queue - Queue name
• job.id - Job ID

Sidekiq

Automatically traced via middleware:

• Job processing
• Retry attempts
• Failures

Captured attributes:

• sidekiq.class - Worker class
• sidekiq.queue - Queue name
• sidekiq.jid - Job ID
• sidekiq.retry_count - Retry attempt

SolidQueue

Automatically traced:

• Job claiming
• Job execution
• Concurrency controls

HTTP Clients

Net::HTTP

Automatically traced:

• All HTTP requests
• Request/response details
• Timing

Captured attributes:

• http.method - Request method
• http.url - Request URL
• http.status_code - Response status

W3C Trace Context headers are automatically injected.

Faraday

Instrumented via middleware:

# Automatically added when Faraday is detected
conn = Faraday.new do |f|
  # MiniAPM middleware is auto-inserted
end

HTTParty

Automatically traced for all requests.

Redis

redis-client (modern)

Instrumented via middleware:

Captured attributes:

• db.system - “redis”
• db.operation - Command name
• net.peer.name - Redis host

redis gem (legacy)

Instrumented via monkey-patching.

Search Engines

Elasticsearch / OpenSearch

Automatically traced:

• Search queries
• Index operations
• Bulk operations

Searchkick

Traced via ActiveSupport::Notifications.

Cache Operations

Rails cache operations are traced:

• cache.read
• cache.write
• cache.delete
• cache.fetch

Manual Span Creation

Create custom spans for operations not automatically instrumented:

MiniAPM.span("process_order", category: :internal) do |span|
  span.add_attribute("order.id", order.id)
  span.add_attribute("order.total", order.total)

  process_order(order)
end

Span categories:

• :http_server - Incoming HTTP requests
• :http_client - Outgoing HTTP requests
• :db - Database operations
• :cache - Cache operations
• :job - Background jobs
• :internal - Custom internal operations

Accessing Current Context

# Get current trace ID (useful for logging)
MiniAPM.current_trace_id

# Get current span
MiniAPM.current_span

# Get current span ID
MiniAPM.current_span_id

Disabling Specific Instrumentation

MiniAPM.configure do |config|
  # Disable Redis instrumentation
  config.instrument :redis, enabled: false

  # Disable SQL logging
  config.instrument :activerecord, log_sql: false
end

Parameter Filtering

Sensitive parameters are automatically filtered:

MiniAPM.configure do |config|
  config.filter_parameters = [
    :password,
    :token,
    :api_key,
    :secret,
    :credit_card
  ]
end

Error Capture

Exceptions are automatically captured with:

• Full stack trace
• Request context
• User ID (if available)
• Custom parameters

Ignore specific exceptions:

MiniAPM.configure do |config|
  config.ignored_exceptions = [
    'ActionController::RoutingError',
    'ActionController::InvalidAuthenticityToken',
    'ActionController::UnknownFormat',
    'ActiveRecord::RecordNotFound'
  ]
end