MiniTelemetry

A lightweight Application Performance Monitoring (APM) and error tracking solution for Ruby on Rails applications. It's built on top of ActiveSupport::Notifications and ActiveSupport::ErrorReporter.

Installation

Add this line to your application's Gemfile:

gem "mini_telemetry"

And then execute:

$ bundle

To copy and migrate MiniTelemetry's migrations, run:

$ rails mini_telemetry:install:migrations db:migrate

And then mount the engine in your config/routes.rb:

Rails.application.routes.draw do
  # ...

  mount MiniTelemetry::Engine, at: "/telemetry"
end

Now you should be able to browse to /telemetry and see all your application events, errors, and performance insights.

Authentication and authorization

MiniTelemetry leaves authentication and authorization to the user. If no authentication is enforced, /telemetry will be available to everyone.

To enforce authentication, you can use route constraints, or set up a HTTP Basic auth middleware.

For example, if you're using devise, you can do this:

# config/routes.rb
authenticate :user do
  mount MiniTelemetry::Engine, at: "/telemetry"
end

See more examples here.

However, if you're using Rails' default authentication generator, or an authentication solution that doesn't provide constraints, you need to roll out your own solution:

# config/routes.rb
constraints ->(request) { Constraints::Auth.authenticated?(request) } do
  mount MiniTelemetry::Engine, at: "/telemetry"
end

# lib/constraints/auth.rb
class Constraints::Auth
  def self.authenticated?(request)
    cookies = ActionDispatch::Cookies::CookieJar.build(request, request.cookies)

    Session.find_by id: cookies.signed[:session_id]
  end
end

You can also set up a HTTP Basic auth middleware in the engine:

# config/initializers/mini_telemetry.rb
MiniTelemetry::Engine.middleware.use(Rack::Auth::Basic) do |username, password|
  ActiveSupport::SecurityUtils.secure_compare(Rails.application.credentials.mini_telemetry_username, username) &
    ActiveSupport::SecurityUtils.secure_compare(Rails.application.credentials.mini_telemetry_password, password)
end

Slow events detection

MiniTelemetry automatically identifies slow events in your application by comparing event durations against configurable thresholds. This helps you quickly identify performance bottlenecks.

When events are recorded, MiniTelemetry checks their duration against defined thresholds:

• Events: Each event is marked as slow if its duration exceeds the threshold for its event type
• Aggregated metrics: For identifiers (grouped events), the MiniTelemetry calculates the P95 duration and marks the identifier as slow if this percentile exceeds the threshold

Default thresholds

By default, MiniTelemetry uses the following thresholds (in milliseconds):

{
  "process_action.action_controller" => 500.0,  # HTTP requests
  "sql.active_record" => 100.0                  # Database queries
}

This means:

• HTTP requests taking longer than 500ms are considered slow
• Database queries taking longer than 100ms are considered slow

Configuring thresholds

You can customize these thresholds in an initializer:

# config/initializers/mini_telemetry.rb
MiniTelemetry.slow_thresholds = {
  "process_action.action_controller" => 1000.0,  # 1 second for HTTP requests
  "sql.active_record" => 50.0,                   # 50ms for database queries
  "perform.active_job" => 5000.0                 # 5 seconds for background jobs
}

You can add thresholds for any event type that MiniTelemetry tracks. Events without a defined threshold won't be marked as slow.

LLM-Friendly JSON Responses

MiniTelemetry provides a dedicated API documentation endpoint designed for LLMs and automated systems to understand and interact with your telemetry data. This enables LLM-driven analysis for identifying performance bottlenecks, suggesting fixes for recurring errors, and generating actionable insights.

LLM API Documentation

Visit /telemetry/llms to access comprehensive API documentation in markdown format, including:

• Complete API endpoint reference with request/response examples
• Authentication guidance for programmatic access
• Step-by-step analysis workflows for common tasks
• Response format schemas and best practices

# Access the LLM guide
curl -u username:password http://localhost:3000/telemetry/llms

This endpoint returns machine-readable markdown that LLMs can use to understand how to query your telemetry data, interpret results, and perform automated analysis.

Accessing JSON Data

All MiniTelemetry endpoints support JSON responses. Append .json to any URL or set the Accept: application/json header:

curl http://localhost:3000/telemetry/performance.json
curl http://localhost:3000/telemetry/errors.json

All routes follow standard Rails conventions. Use bin/rails routes to see available endpoints. Each endpoint returns structured JSON with the resource data and pagination metadata.

Authentication considerations

If you've configured authentication as described in the previous section, keep in mind that cookie-based approaches (like route constraints) won't work for programmatic access. For LLM integration:

• HTTP Basic Auth works out of the box with curl -u username:password
• Token-based auth requires implementing a custom concern that authenticates JSON requests via bearer tokens while preserving cookie-based auth for the web UI

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/sinaptia/mini_telemetry.

License

The gem is available as open source under the terms of the MIT License.