Skip to main content

Ruby SDK Integration Best Practices

Last updated 3 min read

coolhand-ruby patches Net::HTTP via Module#prepend and requires an explicit Coolhand.configure call — it does not auto-initialize on require. Require order, initializer placement, and duplicate provider gems all affect whether monitoring actually captures your AI calls. This guide covers the Ruby-specific ordering pitfalls to check first.

Coolhand's Ruby SDK (coolhand-ruby) monitors LLM calls by prepending a module onto Net::HTTP when you call Coolhand.configure. Two things make this different from Coolhand's Node and Python SDKs: it does not auto-initialize just by being required, and the require order that avoids problems is the opposite of what you'd naturally guess.

Require the provider gem before coolhand

Why it matters: Coolhand patches Net::HTTP (and, by extension, most provider gems that ultimately delegate to it) using Module#prepend. prepend inserts a module ahead of an existing class in the method-resolution order — which only works on a class that's already loaded. If you require 'coolhand' before the provider gem, there's nothing yet to prepend onto for that gem's specific patches, and calls silently go unmonitored.

# ❌ Wrong order — coolhand has nothing to patch yet
require 'coolhand'
require 'anthropic'

# ✅ Correct order — provider gem loads first, so coolhand has a class to prepend onto
require 'anthropic'  # must come before coolhand
require 'coolhand'

Call Coolhand.configure explicitly during boot

Why it matters: Unlike coolhand-python (which auto-initializes on import coolhand), coolhand-ruby does nothing until you explicitly call Coolhand.configure. Requiring the gem alone patches nothing. In a plain Ruby app, call it once at the start of your application; in Rails, put it in an initializer so it runs during boot, before any request or job can fire:

# ✅ config/initializers/coolhand.rb
Coolhand.configure do |c|
  c.api_key = Rails.application.credentials.coolhand_api_key
  c.silent = true
end

Don't install both a provider gem and its fork/alias

Why it matters: Some providers have more than one gem on RubyGems for the same API (for example, anthropic and the older ruby-anthropic). If both are installed, Coolhand can end up intercepting through more than one path for the same underlying HTTP call, producing duplicate captured requests. If you see duplicates in your logs, check for and remove the redundant gem rather than assuming it's a Coolhand bug:

# ✅ Keep one provider gem per provider
gem uninstall ruby-anthropic

Verify interception in CI, not just a 200 response

An app that returns correct responses from your AI provider proves the provider integration works — it does not prove Coolhand captured it. Require order and missing Coolhand.configure calls both produce a fully working app with silently missing logs. If you have an integration test or example around your Coolhand setup, assert that a request was actually intercepted rather than just checking for a successful HTTP response.

Related articles