foam-ruby

Foam observability for Ruby on Rails — logs, traces, and errors via OpenTelemetry.

Installation

Add to your Gemfile:

gem "foam-ruby"

Then run:

bundle install

Quick Start

Create an initializer at config/initializers/foam.rb:

Foam::Ruby.init(
  token: ENV["FOAM_API_TOKEN"],
  service_name: "my-rails-app"
)

That's it. The gem will:

  1. Traces — Auto-instrument Rails controllers, ActiveRecord queries, and Rack requests via OpenTelemetry
  2. Logs — Bridge Rails.logger calls to OTel log records (your existing Rails.logger.info "..." calls automatically emit telemetry)
  3. Errors — Foam::Ruby.capture_exception(e) to record exceptions on the active trace span with full trace context

Configuration

Environment variables

Variable Description Default
FOAM_API_TOKEN Your Foam bearer token —
OTEL_SERVICE_NAME Service name for telemetry rails-app
FOAM_OTEL_ENDPOINT OTLP collector endpoint https://otel.api.foam.ai

How It Works

Rails.logger → OTel Logs

The gem attaches an OTel-emitting logger to Rails.logger using Rails 7.1+ BroadcastLogger. Your existing logging code works unchanged:

Rails.logger.info "User signed up"
Rails.logger.warn "Rate limit approaching"
Rails.logger.error "Payment failed"

Each call emits an OpenTelemetry log record with:

  • The log message body
  • Severity level (DEBUG/INFO/WARN/ERROR/FATAL)
  • Trace context (span ID / trace ID) when inside an active span

Error Capture

Use capture_exception to record errors on the active span with trace context:

begin
  risky_operation
rescue => e
  Foam::Ruby.capture_exception(e)
  # handle error...
end

Sentry Integration

If Sentry is in your Gemfile, the gem automatically bridges Sentry.capture_exception to forward errors to Foam. No configuration needed.

Production Only

The gem only initializes in production (RAILS_ENV=production or RACK_ENV=production). In development and test, all calls are silent no-ops — zero overhead, zero side effects.

Rails Compatibility

  • Rails 7.1+: Full support with BroadcastLogger for log bridging
  • Rails 7.0 and below: Falls back to ActiveSupport::Logger.broadcast
  • Ruby: >= 3.0

Acknowledgements

This package is built on top of the following open source projects:

Project License Link
OpenTelemetry Ruby SDK (opentelemetry-sdk) Apache-2.0 https://github.com/open-telemetry/opentelemetry-ruby
OpenTelemetry Ruby Logs SDK (opentelemetry-logs-sdk) Apache-2.0 https://github.com/open-telemetry/opentelemetry-ruby
OpenTelemetry OTLP Exporter (opentelemetry-exporter-otlp) Apache-2.0 https://github.com/open-telemetry/opentelemetry-ruby
OpenTelemetry OTLP Logs Exporter (opentelemetry-exporter-otlp-logs) Apache-2.0 https://github.com/open-telemetry/opentelemetry-ruby
OpenTelemetry Rails Instrumentation (opentelemetry-instrumentation-rails) Apache-2.0 https://github.com/open-telemetry/opentelemetry-ruby-contrib

License

MIT