ActiveStatsD

ActiveStatsD is a lightweight Ruby gem providing a built-in StatsD-compatible UDP server and client integration directly within your Rails applications. It simplifies local metrics aggregation during development and seamlessly integrates with external aggregation services like Datadog in production.

Add this line to your Rails application's Gemfile:

gem 'active_statsd'

Then execute:

bundle install
rails generate active_stats_d:active_stats_d

Create an initializer manually at config/initializers/active_statsd.rb:

# config/initializers/active_statsd.rb
ActiveStatsD.configure do |config|
  config.host = '127.0.0.1'
  config.port = 8125
  config.namespace = 'my_rails_app'
  config.aggregation = true        # local aggregation (default: true)
  config.forward_host = nil        # set if forwarding metrics externally
  config.forward_port = nil
end

Use the convenient Rails.stats interface:

# Increment a counter
Rails.stats.increment('user.signup.success')

# Record a gauge metric
Rails.stats.gauge('user.current.active_sessions', 123)

# Measure execution time
Rails.stats.timing('db.query.time') do
  User.where(active: true).load
end

Measured on a MacBook Pro M2 Max:

Warming up --------------------------------------
   increment counter    17.167k i/100ms
        gauge metric    17.009k i/100ms
       timing metric    79.000 i/100ms
Calculating -------------------------------------
   increment counter    176.564k (± 9.9%) i/s    (5.66 μs/i) -      1.751M in  10.038152s
        gauge metric    169.860k (± 9.2%) i/s    (5.89 μs/i) -      1.684M in  10.013536s
       timing metric    824.802 (± 5.2%) i/s    (1.21 ms/i) -      8.295k in  10.089701s

Comparison:
   increment counter:   176564.0 i/s
        gauge metric:   169859.9 i/s - same-ish: difference falls within error
       timing metric:      824.8 i/s - 214.07x  slower

Benchmarked with benchmark-ips over 10s runs, reusing a single UDP socket.

In development mode, ActiveStatsD automatically runs an embedded UDP StatsD server to locally aggregate metrics. Aggregated metrics are flushed to your Rails logs every 10 seconds:

[ActiveStatsD] Aggregated metric - my_rails_app.user.signup.success: 42

If aggregation is disabled (aggregation: false), each metric is logged immediately:

[ActiveStatsD] Metric received (no aggregation) - my_rails_app.user.signup.success:1|c

To automatically track Sidekiq metrics, add this middleware explicitly:

# config/initializers/sidekiq.rb
Sidekiq.configure_server do |config|
  config.server_middleware do |chain|
    chain.add ActiveStatsD::SidekiqMiddleware
  end
end

---

## Production Usage & Datadog Integration

For multi-server setups, disable the local aggregation and forward metrics directly to a centralized aggregator like Datadog:

```ruby
# config/environments/production.rb
ActiveStatsD.configure do |config|
  config.aggregation = false
  config.forward_host = ENV['DATADOG_AGENT_HOST'] || 'datadog-agent.internal'
  config.forward_port = 8125
  config.namespace = 'my_rails_app'
end

1. Install Datadog agent: Official Datadog Installation Docs
2. Configure Rails app: Ensure metrics forward to Datadog agent as shown above.
3. View metrics: Datadog will aggregate and provide centralized dashboards automatically.

No additional code is needed; ActiveStatsD metrics are fully compatible with Datadog.

After cloning the repository, run:

bin/setup

To run tests:

bundle exec rake spec

To experiment with the gem interactively:

bin/console

Update the version in lib/active_statsd/version.rb, then run:

bundle exec rake release

This tags the release, pushes commits and tags, and publishes to RubyGems.

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

This project is intended to be a welcoming space for collaboration. Contributors must adhere to the Code of Conduct.

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

All interactions in ActiveStatsD's codebase, issue tracker, chat rooms, and mailing lists are governed by the Code of Conduct.