foam-ruby 0.1.0.alpha1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6fd659f190b92247bff589dafeed2d7ac4c8cb5897b6dc20e779914b65911f63
+  data.tar.gz: f1861ab90f5a331225bb0ee36eefe5bf32ede8a373bd668cfeeed493542633a2
+SHA512:
+  metadata.gz: 596c7ec442d2cfc7e50bb9ef265c346e671910e237868ae73560751e1df867cb7363632a0b0486b108b7bfb776ea6a2c93f1d18a686f318405c293f71bc80a10
+  data.tar.gz: adc51e59deeb2f121d2f5e39892931b58e410b8c50726189b8cf4b09242e0725d085c06802ff1c609fcc3119440e31032bbafe55d72c4af9f8fe1388435a692e

data/README.md

@@ -0,0 +1,121 @@
+# foam-ruby
+
+Foam observability for Ruby on Rails — logs, traces, and errors via OpenTelemetry.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "foam-ruby"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Quick Start
+
+Create an initializer at `config/initializers/foam.rb`:
+
+```ruby
+Foam::Ruby.init(
+  api_key: ENV["FOAM_API_KEY"],
+  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
+
+### Block syntax
+
+```ruby
+Foam::Ruby.configure do |c|
+  c.api_key = ENV["FOAM_API_KEY"]
+  c.service_name = "my-rails-app"
+  c.traces_enabled = true
+  c.logs_enabled = true
+end
+```
+
+### Environment variables
+
+| Variable | Description | Default |
+|---|---|---|
+| `FOAM_API_KEY` | Your Foam API key | — |
+| `OTEL_SERVICE_NAME` | Service name for telemetry | `rails-app` |
+| `FOAM_OTEL_ENDPOINT` | OTLP collector endpoint | `https://otel.api.foam.ai` |
+
+### Disabling signals
+
+```ruby
+Foam::Ruby.init(
+  api_key: ENV["FOAM_API_KEY"],
+  service_name: "my-rails-app",
+  traces: false,  # disable trace collection
+  logs: true
+)
+```
+
+## 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:
+
+```ruby
+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:
+
+```ruby
+begin
+  risky_operation
+rescue => e
+  Foam::Ruby.capture_exception(e)
+  # handle error...
+end
+```
+
+### Additional Instrumentations
+
+Pass extra OpenTelemetry instrumentations:
+
+```ruby
+Foam::Ruby.init(
+  api_key: ENV["FOAM_API_KEY"],
+  service_name: "my-rails-app",
+  instrumentations: [
+    "OpenTelemetry::Instrumentation::Sidekiq",
+    "OpenTelemetry::Instrumentation::Redis",
+  ]
+)
+```
+
+## 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
+
+## License
+
+MIT

data/lib/foam/ruby/configuration.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Foam
+  module Ruby
+    class Configuration
+      FOAM_OTEL_ENDPOINT = "https://otel.api.foam.ai"
+
+      attr_accessor :api_key, :service_name, :endpoint,
+                    :traces_enabled, :logs_enabled,
+                    :additional_instrumentations
+
+      def initialize
+        @api_key = ENV["FOAM_API_KEY"]
+        @service_name = ENV.fetch("OTEL_SERVICE_NAME", "rails-app")
+        @endpoint = ENV.fetch("FOAM_OTEL_ENDPOINT", FOAM_OTEL_ENDPOINT)
+        @traces_enabled = true
+        @logs_enabled = true
+        @additional_instrumentations = []
+      end
+
+      def otel_headers
+        { "Authorization" => "Bearer #{api_key}" }
+      end
+
+      def traces_endpoint
+        "#{endpoint}/v1/traces"
+      end
+
+      def logs_endpoint
+        "#{endpoint}/v1/logs"
+      end
+
+      def valid?
+        !api_key.nil? && !api_key.empty?
+      end
+    end
+  end
+end

data/lib/foam/ruby/log_subscriber.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module Foam
+  module Ruby
+    # Emits OTel log records. Attached to Rails.logger as a broadcast
+    # destination so existing log output (stdout, file, etc.) is preserved.
+    class OtelLogDevice
+      SEVERITY_MAP = {
+        Logger::DEBUG => OpenTelemetry::Logs::SeverityNumber::SEVERITY_NUMBER_DEBUG,
+        Logger::INFO => OpenTelemetry::Logs::SeverityNumber::SEVERITY_NUMBER_INFO,
+        Logger::WARN => OpenTelemetry::Logs::SeverityNumber::SEVERITY_NUMBER_WARN,
+        Logger::ERROR => OpenTelemetry::Logs::SeverityNumber::SEVERITY_NUMBER_ERROR,
+        Logger::FATAL => OpenTelemetry::Logs::SeverityNumber::SEVERITY_NUMBER_FATAL,
+      }.freeze
+
+      SEVERITY_TEXT = {
+        Logger::DEBUG => "DEBUG",
+        Logger::INFO => "INFO",
+        Logger::WARN => "WARN",
+        Logger::ERROR => "ERROR",
+        Logger::FATAL => "FATAL",
+      }.freeze
+
+      def initialize
+        @otel_logger = OpenTelemetry.logger_provider.logger(name: "foam-ruby")
+      end
+
+      def emit(severity, message)
+        return if message.nil? || (message.respond_to?(:empty?) && message.empty?)
+
+        span_context = OpenTelemetry::Trace.current_span.context
+
+        @otel_logger.on_emit(
+          body: message.to_s,
+          severity_number: SEVERITY_MAP.fetch(severity, OpenTelemetry::Logs::SeverityNumber::SEVERITY_NUMBER_INFO),
+          severity_text: SEVERITY_TEXT.fetch(severity, "INFO"),
+          span_context: span_context.valid? ? span_context : nil,
+          timestamp: Time.now
+        )
+      rescue StandardError => e
+        warn "[foam-ruby] Failed to emit OTel log record: #{e.message}"
+      end
+    end
+
+    # No-op IO stand-in so ::Logger internals never hit nil.
+    class NullLogDevice
+      def write(_msg) = nil
+      def close = nil
+      def reopen(_log = nil) = nil
+    end
+
+    # Logger subclass that forwards every #add call to OtelLogDevice.
+    # Designed to be broadcast-attached to Rails.logger, not used standalone.
+    # Does no level filtering — the parent BroadcastLogger already decided
+    # this message should be delivered.
+    class OtelLogger < ::Logger
+      def initialize
+        super(NullLogDevice.new)
+        @otel_device = OtelLogDevice.new
+      end
+
+      def add(severity, message = nil, progname = nil, &block)
+        msg = message || (block ? block.call : progname)
+        @otel_device.emit(severity || ::Logger::INFO, msg)
+        true
+      end
+    end
+  end
+end

data/lib/foam/ruby/otel_setup.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "opentelemetry/sdk"
+require "opentelemetry-exporter-otlp"
+require "opentelemetry-logs-api"
+require "opentelemetry-logs-sdk"
+
+module Foam
+  module Ruby
+    module OtelSetup
+      module_function
+
+      def configure!(config)
+        configure_traces(config) if config.traces_enabled
+        configure_logs(config) if config.logs_enabled
+      end
+
+      def configure_traces(config)
+        OpenTelemetry::SDK.configure do |c|
+          c.service_name = config.service_name
+
+          c.add_span_processor(
+            OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
+              OpenTelemetry::Exporter::OTLP::Exporter.new(
+                endpoint: config.traces_endpoint,
+                headers: config.otel_headers
+              )
+            )
+          )
+
+          c.use "OpenTelemetry::Instrumentation::Rack"
+          c.use "OpenTelemetry::Instrumentation::ActionPack"
+          c.use "OpenTelemetry::Instrumentation::ActiveRecord"
+          c.use "OpenTelemetry::Instrumentation::ActiveSupport"
+          c.use "OpenTelemetry::Instrumentation::Rails"
+
+          config.additional_instrumentations.each do |instrumentation|
+            c.use instrumentation
+          end
+        end
+      end
+
+      def configure_logs(config)
+        exporter = OpenTelemetry::Exporter::OTLP::LogRecordExporter.new(
+          endpoint: config.logs_endpoint,
+          headers: config.otel_headers
+        )
+
+        processor = OpenTelemetry::SDK::Logs::Export::BatchLogRecordProcessor.new(exporter)
+        logger_provider = OpenTelemetry::SDK::Logs::LoggerProvider.new
+        logger_provider.add_log_record_processor(processor)
+        OpenTelemetry.logger_provider = logger_provider
+      end
+    end
+  end
+end

data/lib/foam/ruby/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Foam
+  module Ruby
+    VERSION = "0.1.0.alpha1"
+  end
+end

data/lib/foam/ruby.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "opentelemetry/sdk"
+require "opentelemetry-logs-api"
+
+require_relative "ruby/version"
+require_relative "ruby/configuration"
+require_relative "ruby/otel_setup"
+require_relative "ruby/log_subscriber"
+
+module Foam
+  module Ruby
+    class << self
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def configure
+        yield(configuration) if block_given?
+        configuration
+      end
+
+      def init(api_key: nil, service_name: nil, endpoint: nil, **options)
+        configure do |c|
+          c.api_key = api_key if api_key
+          c.service_name = service_name if service_name
+          c.endpoint = endpoint if endpoint
+          c.traces_enabled = options.fetch(:traces, true)
+          c.logs_enabled = options.fetch(:logs, true)
+          c.additional_instrumentations = options[:instrumentations] || []
+        end
+
+        unless configuration.valid?
+          warn "[foam-ruby] Missing api_key — set FOAM_API_KEY or pass api_key: to Foam::Ruby.init"
+          return
+        end
+
+        OtelSetup.configure!(configuration)
+        schedule_logger_attach! if configuration.logs_enabled
+      end
+
+      def capture_exception(error, attributes: {})
+        span = OpenTelemetry::Trace.current_span
+        return unless span && span.context.valid?
+
+        raw_parent = span.instance_variable_get(:@parent_span_id)
+        parent_id = raw_parent&.unpack1("H*")
+        parent_id = nil if parent_id.nil? || parent_id == ("0" * 16)
+
+        attrs = attributes.merge(
+          "trace_id" => span.context.hex_trace_id,
+          "span_id" => span.context.hex_span_id
+        )
+        attrs["parent_span_id"] = parent_id if parent_id
+
+        span.record_exception(error, attributes: attrs)
+        span.status = OpenTelemetry::Trace::Status.error(error.message)
+      rescue StandardError => e
+        warn "[foam-ruby] capture_exception failed: #{e.message}"
+      end
+
+      private
+
+      def schedule_logger_attach!
+        return unless defined?(::Rails)
+
+        if ::Rails.respond_to?(:application) && ::Rails.application
+          ::Rails.application.config.after_initialize { do_attach_otel_logger! }
+        else
+          do_attach_otel_logger!
+        end
+      rescue StandardError => e
+        warn "[foam-ruby] Failed to schedule OTel logger attach: #{e.message}"
+      end
+
+      def do_attach_otel_logger!
+        return unless ::Rails.respond_to?(:logger) && ::Rails.logger
+
+        unless OpenTelemetry.logger_provider.is_a?(OpenTelemetry::SDK::Logs::LoggerProvider)
+          warn "[foam-ruby] OTel logger provider not configured — call Foam::Ruby.init before attaching logger"
+          return
+        end
+
+        otel_logger = OtelLogger.new
+
+        if ::Rails.logger.respond_to?(:broadcast_to)
+          ::Rails.logger.broadcast_to(otel_logger)
+        elsif defined?(::ActiveSupport::Logger) && ::ActiveSupport::Logger.respond_to?(:broadcast)
+          ::Rails.logger.extend(::ActiveSupport::Logger.broadcast(otel_logger))
+        end
+      rescue StandardError => e
+        warn "[foam-ruby] Failed to attach OTel logger to Rails.logger: #{e.message}"
+      end
+    end
+  end
+end

data/lib/foam-ruby.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "foam/ruby"

metadata

@@ -0,0 +1,232 @@
+--- !ruby/object:Gem::Specification
+name: foam-ruby
+version: !ruby/object:Gem::Version
+  version: 0.1.0.alpha1
+platform: ruby
+authors:
+- Foam
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-04-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-api
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-sdk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-exporter-otlp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.29'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.29'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-logs-api
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-logs-sdk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-instrumentation-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.31'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.31'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-instrumentation-rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.24'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.24'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-instrumentation-active_record
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-instrumentation-action_pack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-instrumentation-active_support
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: 
+email:
+- support@foam.ai
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/foam-ruby.rb
+- lib/foam/ruby.rb
+- lib/foam/ruby/configuration.rb
+- lib/foam/ruby/log_subscriber.rb
+- lib/foam/ruby/otel_setup.rb
+- lib/foam/ruby/version.rb
+homepage: https://github.com/nicktesh/packages
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">"
+    - !ruby/object:Gem::Version
+      version: 1.3.1
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: Foam observability for Ruby on Rails (logs, traces, errors) via OpenTelemetry
+test_files: []