---
title: "Ruby SDK Integration Best Practices"
answer: "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."
category: "Logs \u0026 API"
tags: []
published: 2026-09-22T14:26:47Z
updated: 2026-09-13T16:14:45Z
canonical_url: https://coolhandlabs.com/help/ruby-sdk-integration-best-practices
index_url: https://coolhandlabs.com/help.md
---

# Ruby SDK Integration Best Practices

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.

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

```ruby
# ✅ 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:

```ruby
# ✅ 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:

```bash
# ✅ 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

- [Node.js/JavaScript SDK Integration Best Practices](https://coolhandlabs.com/help/nodejs-sdk-integration-best-practices.md)
- [Python SDK Integration Best Practices](https://coolhandlabs.com/help/python-sdk-integration-best-practices.md)


---

Related:
- [Node.js/JavaScript SDK Integration Best Practices](https://coolhandlabs.com/help/nodejs-sdk-integration-best-practices.md)
- [Python SDK Integration Best Practices](https://coolhandlabs.com/help/python-sdk-integration-best-practices.md)
- [When should I use batch requests?](https://coolhandlabs.com/help/how-to-use-batch-requests.md)
- [What every field on an LLM request log means](https://coolhandlabs.com/help/llm-request-log-fields.md)

[← All help articles](https://coolhandlabs.com/help.md) · [Logs & API](https://coolhandlabs.com/help/category/logs-and-api.md)