railswatch_gem 0.1.5 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 31cef41294d874fdcf6b8e23b0f34d7f954359b27e60bcea834d178405dd9dc5
-  data.tar.gz: 24f4ccf4c3d9617aad4340dd2b41cf31d8028dfd3b443361f9aa90b97afe9781
+  metadata.gz: 540f88538c4fa2d5a156e22d680839b8768ea224eff4719729c3548731fadc67
+  data.tar.gz: 40e65222f075c543739f096dd197e9e1aef3fa8d66568d8af9447cb44ff928a9
 SHA512:
-  metadata.gz: 22fadd59c98cda3262e290dd2cbbed57d133469be81cb6f68951062b4dd25f51a92b4f972822d98681f9b9d5298ac23d21168a87f2907ddc0fb3a267a950f441
-  data.tar.gz: 1aceb6e85b61bea68bb581c6590d6cee2847fbab7e5dfa95883e4a2371ffd617e462ff2f8d92a0766ca827d5c9e6dbf66ff3769c052ef6f7df618ecac14c9876
+  metadata.gz: c3cda587349e79a8908db25a6d6599bc6b08d0d57d5ac398cf4d8e108cc62290f4e281ee374d883076a50a13ae306c6088327b8efca9567a921b0a62d8980398
+  data.tar.gz: 718a3a2eff1bd4c83913ccdbdee9106ac0d372e2937d426ddca35c6805d0db90047c84f7eaa8e1225db4fc632c80f483326d1a113e0758f825d17bbb0b6cb509

data/README.md

@@ -1,130 +1,98 @@
 # RailsWatch Gem
 
-RailsWatch is a lightweight, high-performance observability probe for Ruby on Rails applications. It captures requests, SQL queries, background jobs, logs, and exceptions in real-time and forwards them to your RailsWatch dashboard.
+**Instant, zero-config observability for Ruby on Rails.**
 
-Designed to be the Rails equivalent of Laravel Nightwatch/Telescope, it provides deep insight into your application's lifecycle without the overhead of heavy APM tools.
+The \`railswatch_gem\` automatically instruments your Rails application using **OpenTelemetry**. It captures request traces, database queries, background jobs, and—most importantly—provides deep visibility into your AI integration costs and latency (OpenAI & Anthropic).
 
-## 🚀 Features
+## Features
 
-- **Zero-Config**: Automatically hooks into Rails via ActiveSupport::Notifications.
+* **Auto-Instrumentation:** Zero code required to track Rails requests, Sidekiq jobs, Postgres queries, Redis commands, and Net::HTTP calls.
+* **AI Monitoring:** Automatically tracks token usage, costs, model names, and latency for \`ruby-openai\` and \`anthropic\` gems.
+* **Debug Dump:** A global \`rw()\` helper to instantly dump variables into your trace timeline without clogging your stdout logs.
+* **Standard OTLP:** Uses the industry-standard OpenTelemetry Protocol.
 
-- **Full Lifecycle Tracking**:
-  - HTTP Requests (Headers, Session, Params)
-  - Database Queries (SQL, Duration)
-  - Background Jobs (Sidekiq, ActiveJob)
-  - Mail Deliveries
-  - Cache Hits/Misses (Redis, Memcached)
-  - Outgoing HTTP Requests (Net::HTTP)
-  - Rake Tasks & CLI Commands
+## Installation
 
-- **Active Debugging**: Includes a global `rw()` helper to dump variables to your dashboard instantly.
+Add this line to your application'\''s Gemfile:
 
-- **Performance First**: Uses a background thread and buffered queue to ensure your application performance is never impacted by monitoring.
-
-- **Safe**: Handles thread-safety and swallows internal errors to prevent bringing down your app.
-
-## 📦 Installation
-
-Add this line to your application's Gemfile:
-
-```ruby
-gem 'railswatch_gem'
-```
+    gem '\''railswatch_gem'\''
 
 And then execute:
 
-```bash
-bundle install
-```
+    bundle install
 
-## ⚙️ Configuration
+## Configuration
 
-Create an initializer file at `config/initializers/railswatch.rb`. You will need your Project Token from your RailsWatch dashboard settings.
+The gem is configured entirely via environment variables. You do not need an initializer file.
 
-```ruby
-# config/initializers/railswatch.rb
+Add these to your \`.env\` file or production environment:
 
-RailswatchGem.configure do |config|
-  # The URL of your Railswatch SaaS instance (or self-hosted)
-  config.ingest_url = "https://api.railswatch.com/api/v1/ingest"
+    # Required
+    RAILSWATCH_API_KEY=rw_live_...
+    RAILSWATCH_SERVICE_NAME=my-rails-app
 
-  # Your unique Project Token
-  config.env_token  = ENV.fetch("RAILSWATCH_TOKEN", "your-project-token")
+    # Optional (Defaults to standard RailsWatch ingest)
+    # RAILSWATCH_INGEST_URL=https://ingest.railswatch.com/v1/traces
 
-  # Optional: Fine-tune performance
-  # config.batch_size = 100       # Max events to send in one HTTP request
-  # config.flush_interval = 2.0   # Send data every 2 seconds
-end
-```
+Once these variables are present, \`railswatch_gem\` will automatically start when Rails boots.
 
-That's it! Restart your application, and data will start flowing to your dashboard.
+## Usage
 
-## 🛠 Usage
+### 1. Standard Observability
+Just run your app!
+* **Controllers:** Every request is traced.
+* **Database:** SQL queries are captured as spans.
+* **Jobs:** Sidekiq jobs are linked to the web requests that enqueued them.
 
-### The rw() Helper
+### 2. AI Monitoring
+If you use the \`ruby-openai\` or \`anthropic\` gems, we automatically patch them to record rich telemetry.
 
-Stop using `puts` or `binding.pry` in production. Use the global `rw()` helper (aliased as `railswatch_dump`) to send any variable directly to your "Dumps" dashboard tab.
+**Supported Libraries:**
+* \`ruby-openai\`
+* \`anthropic\`
 
-```ruby
-class UsersController < ApplicationController
-  def create
-    @user = User.new(user_params)
+**What we capture:**
+* Model Name (e.g., \`gpt-4\`, \`claude-3-sonnet\`)
+* Token Usage (Prompt, Completion, and Total)
+* Latency
+* System Fingerprints
 
-    # Inspect the user object in your dashboard without stopping the request
-    rw(@user)
+**Example:**
 
-    if @user.save
-      # ...
-    end
-  end
-end
-```
-
-It returns the original object, so you can wrap expressions transparently:
+    # This API call will automatically appear in your RailsWatch dashboard
+    client = OpenAI::Client.new
+    client.chat(parameters: { model: "gpt-4", messages: [...] })
 
-```ruby
-# The result is assigned to 'result' AND sent to the dashboard
-result = rw(ComplexCalculation.perform(x, y))
-```
+### 3. The \`rw()\` Debug Helper
+Stop using \`puts\` or \`Rails.logger.info\` for debugging complex objects. Use the global \`rw()\` helper.
 
-### Manual Logging
+It dumps the object into the **current trace timeline**, allowing you to see exactly *when* a variable had a specific value relative to your DB queries and API calls.
 
-RailsWatch automatically captures standard Rails.logger output. However, you can also manually record specific events if needed:
+    def index
+      @users = User.all
 
-```ruby
-RailswatchGem.record({
-  event_type: "custom_alert",
-  message: "Something interesting happened",
-  metadata: { user_id: 123 }
-})
-```
+      # Dumps the array to RailsWatch without stopping execution
+      rw(@users)
 
-## 🔒 Security
-
-- **Parameter Filtering**: RailsWatch respects your `Rails.application.config.filter_parameters`. Passwords and secrets defined there are scrubbed before leaving your server.
+      # You can also pass through values (returns the argument)
+      @user = rw(User.first)
+    end
 
-- **Async Processing**: Data is buffered in memory and sent asynchronously. If the ingestion API is down, your app continues running smoothly.
+## Troubleshooting
 
-## 🧩 Supported Instrumenters
+If you don'\''t see data in your dashboard:
 
-RailsWatch automatically instruments the following libraries if they are loaded:
+1.  **Check the Logs:**
+    On boot, you should see: \`[Railswatch] Observability started for my-rails-app\`.
 
-| Instrumenter | Description |
-|-------------|-------------|
-| Requests | Controller actions, status codes, paths, IP addresses. |
-| Queries | ActiveRecord SQL queries (filters out SCHEMA/EXPLAIN). |
-| Jobs | ActiveJob & Sidekiq execution, latency, and retries. |
-| Mail | ActionMailer deliveries, recipients, and subjects. |
-| Cache | ActiveSupport::Cache reads, writes, and hit rates. |
-| Outbound | Net::HTTP requests to external APIs. |
-| Models | ActiveRecord Create/Update/Destroy events with changesets. |
-| Exceptions | Unhandled exceptions and Rails.error.report calls. |
-| Commands | Rake tasks and Thor CLI commands. |
+2.  **Verify Environment Variables:**
+    Ensure \`RAILSWATCH_API_KEY\` is available in your shell/environment.
 
-## 🤝 Contributing
+3.  **OpenTelemetry Debugging:**
+    To see exactly what OTel is doing, enable the internal logger:
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/yourusername/railswatch_gem. This project is intended to be a safe, welcoming space for collaboration.
+        OTEL_LOG_LEVEL=debug rails s
 
-## 📄 License
+## License
 
-The gem is available as open source under the terms of the MIT License.
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/railswatch_gem/configuration.rb

@@ -2,52 +2,14 @@
 
 module RailswatchGem
   class Configuration
-    attr_accessor :env_token, :batch_size, :flush_interval, :ingest_url, :auto_boot
-    attr_reader :enabled_events, :custom_event_blocks
-
-    DEFAULT_EVENTS = %i[
-      requests
-      queries
-      outgoing_requests
-      jobs
-      scheduled_tasks
-      commands
-      cache
-      mail
-      notifications
-      logs
-      errors
-      models
-    ].freeze
-
-    DEFAULT_INGEST_URL = "https://api.railswatch.com/ingest".freeze
+    attr_accessor :api_key, :service_name, :ingest_url, :enabled
 
     def initialize
-      @env_token = nil
-      @batch_size = 200
-      @flush_interval = 2.0
-      @ingest_url = DEFAULT_INGEST_URL
-      @auto_boot = true # Defaults to true for ease of use
-
-      # all default event families enabled
-      @enabled_events = DEFAULT_EVENTS.dup
-
-      # user-supplied instrumentation hooks
-      @custom_event_blocks = []
-    end
-
-    def enable_event(name)
-      name = name.to_sym
-      @enabled_events << name unless @enabled_events.include?(name)
-    end
-
-    def disable_event(name)
-      @enabled_events.delete(name.to_sym)
-    end
-
-    # for custom subscriptions using the client
-    def on_custom_event(&block)
-      @custom_event_blocks << block if block
+      @api_key = ENV["RAILSWATCH_API_KEY"]
+      default_name = defined?(::Rails) ? ::Rails.application.class.module_parent_name.underscore.dasherize : "rails-app"
+      @service_name = ENV["RAILSWATCH_SERVICE_NAME"] || default_name
+      @ingest_url = ENV["RAILSWATCH_INGEST_URL"] || "https://ingest.railswatch.com/v1/traces"
+      @enabled = true
     end
   end
 end

data/lib/railswatch_gem/helpers.rb

@@ -1,71 +1,62 @@
 # frozen_string_literal: true
 
+require "json"
+
 module RailswatchGem
   module Helpers
-    # Usage: rw(user, params) or railswatch_dump(variable)
+    # Types that can be safely serialized to JSON without inspection
+    SAFE_JSON_TYPES = [Hash, Array, String, Integer, Float, TrueClass, FalseClass, NilClass].freeze
+    MAX_PAYLOAD_SIZE = 4096
+
     def railswatch_dump(*args)
-      # 1. Capture the location where this was called (file:line)
-      call_site = caller(1, 1).first
-
-      # 2. Correlate with request if inside one
-      request_id = Thread.current[:railswatch_request_id]
-
-      # 3. Format the arguments for display
-      formatted_args = args.map do |arg|
-        format_dump_arg(arg)
-      end
-
-      payload = {
-        event_type: "dump",
-        timestamp: Time.now.utc.iso8601,
-        values: formatted_args,
-        location: call_site,
-        request_id: request_id
-      }
-
-      # Send to client
-      RailswatchGem.record(payload)
-
-      # 4. Return original args to allow debugging without breaking chains:
-      #    return rw(result)
-      if args.size == 1
-        args.first
-      else
-        args
-      end
+      span = OpenTelemetry::Trace.current_span
+      return return_value(args) unless span.recording?
+
+      file, line = parse_caller_location
+
+      json_content = serialize_args(args)
+
+      span.add_event("railswatch.dump", attributes: {
+        "code.filepath" => file,
+        "code.lineno" => line,
+        "railswatch.dump.content" => truncate_payload(json_content)
+      })
+
+      return_value(args)
     rescue => e
-      warn "RailswatchGem: Dump failed: #{e.message}"
-      # Always return args so we don't break the app flow on error
-      args.size == 1 ? args.first : args
+      # Fail silently, return original args
+      return_value(args)
     end
 
-    # Short alias for ease of use
     alias_method :rw, :railswatch_dump
 
     private
 
-    def format_dump_arg(arg)
-      case arg
-      when Hash
-        # Attempt to keep hashes as structures for the JSON viewer in the dashboard
-        begin
-          arg.transform_keys(&:to_s)
-        rescue
-          arg.inspect
-        end
-      when Array
-        arg.map { |item| format_dump_arg(item) }
-      when String, Numeric, TrueClass, FalseClass, NilClass
-        arg
-      else
-        # For Active Record models or complex objects, .inspect gives the string representation
-        # which is usually what developers want to see.
-        arg.inspect
-      end
+    def return_value(args)
+      args.size == 1 ? args.first : args
+    end
+
+    def parse_caller_location
+      # Returns ["/path/to/file.rb", "45"]
+      caller(2, 1).first.to_s.split(":")[0..1]
+    end
+
+    def serialize_args(args)
+      args.map { |arg| sanitize_arg(arg) }.to_json
+    end
+
+    def sanitize_arg(arg)
+      return arg if SAFE_JSON_TYPES.any? { |t| arg.is_a?(t) }
+
+      # Fallback for complex objects (ActiveRecord, Custom Classes)
+      arg.inspect
+    end
+
+    def truncate_payload(json)
+      return json if json.bytesize <= MAX_PAYLOAD_SIZE
+      json.byteslice(0, MAX_PAYLOAD_SIZE - 3) + "..."
     end
   end
 end
 
-# Automatically mix into the top-level Object so it's available everywhere
-# (Models, Controllers, Views, Console, Irb)
 Object.include(RailswatchGem::Helpers) if defined?(Object)

data/lib/railswatch_gem/instrumentation/ai_helper.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module RailswatchGem
+  module Instrumentation
+    module AiHelper
+      MAX_CONTENT_SIZE = 4096
+
+      def trace_ai_request(tracer, span_name, attributes = {})
+        span = tracer.start_span(span_name, kind: :client)
+
+        OpenTelemetry::Trace.with_span(span) do
+          # 1. Set Standard Request Attributes
+          span.set_attribute("gen_ai.system", attributes[:system])
+          span.set_attribute("gen_ai.request.model", attributes[:model].to_s)
+
+          if attributes[:prompt_role]
+            span.set_attribute("gen_ai.prompt.role", attributes[:prompt_role].to_s)
+          end
+
+          if attributes[:prompt_content]
+            span.set_attribute("gen_ai.prompt.content", truncate(attributes[:prompt_content].to_s))
+          end
+
+          # 2. Yield span to the block so the provider can set its own stats
+          response = yield(span)
+
+          response
+        rescue => e
+          span.record_exception(e)
+          span.status = OpenTelemetry::Trace::Status.error("#{attributes[:system]} Request Failed: #{e.message}")
+          raise e
+        ensure
+          span.finish
+        end
+      end
+
+      private
+
+      def truncate(str)
+        return str if str.bytesize <= MAX_CONTENT_SIZE
+        str.byteslice(0, MAX_CONTENT_SIZE - 3) + "..."
+      end
+    end
+  end
+end

data/lib/railswatch_gem/instrumentation/anthropic.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "railswatch_gem/instrumentation/ai_helper"
+
+module RailswatchGem
+  module Instrumentation
+    module Anthropic
+      extend AiHelper
+
+      def self.install
+        return unless defined?(::Anthropic::Client)
+        ::Anthropic::Client.prepend(Patches)
+      end
+
+      module Patches
+        def messages(parameters = {})
+          model = parameters[:model] || parameters["model"]
+          messages = parameters[:messages] || parameters["messages"]
+          last_msg = messages&.last
+
+          prompt_role = last_msg.is_a?(Hash) ? (last_msg[:role] || last_msg["role"]) : nil
+          prompt_content = last_msg.is_a?(Hash) ? (last_msg[:content] || last_msg["content"]) : nil
+
+          RailswatchGem::Instrumentation::Anthropic.trace_ai_request(
+            tracer,
+            "gen_ai.anthropic.messages",
+            system: "anthropic",
+            model: model,
+            prompt_role: prompt_role,
+            prompt_content: prompt_content
+          ) do |span|
+            response = super
+
+            # 2. Extract Stats (Anthropic Format)
+            if response.is_a?(Hash)
+              if (usage = response["usage"])
+                input = usage["input_tokens"].to_i
+                output = usage["output_tokens"].to_i
+                span.set_attribute("gen_ai.usage.input_tokens", input)
+                span.set_attribute("gen_ai.usage.output_tokens", output)
+                span.set_attribute("gen_ai.usage.total_tokens", input + output)
+              end
+
+              if response["stop_reason"]
+                span.set_attribute("gen_ai.response.finish_reason", response["stop_reason"].to_s)
+              end
+            end
+
+            response
+          end
+        end
+
+        private
+
+        def tracer
+          OpenTelemetry.tracer_provider.tracer("railswatch_gem-ai")
+        end
+      end
+    end
+  end
+end

data/lib/railswatch_gem/instrumentation/openai.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "railswatch_gem/instrumentation/ai_helper"
+
+module RailswatchGem
+  module Instrumentation
+    module OpenAI
+      extend AiHelper
+
+      def self.install
+        return unless defined?(::OpenAI::Client)
+        ::OpenAI::Client.prepend(Patches)
+      end
+
+      module Patches
+        def chat(parameters = {})
+          model = parameters[:model] || parameters["model"]
+          messages = parameters[:messages] || parameters["messages"]
+          last_msg = messages&.last
+
+          # Extract prompt safely
+          prompt_role = last_msg.is_a?(Hash) ? (last_msg[:role] || last_msg["role"]) : nil
+          prompt_content = last_msg.is_a?(Hash) ? (last_msg[:content] || last_msg["content"]) : nil
+
+          RailswatchGem::Instrumentation::OpenAI.trace_ai_request(
+            tracer,
+            "gen_ai.chat",
+            system: "openai",
+            model: model,
+            prompt_role: prompt_role,
+            prompt_content: prompt_content
+          ) do |span|
+            # 1. Call original method
+            response = super
+
+            # 2. Extract Stats (OpenAI Format)
+            if response.is_a?(Hash)
+              if (usage = response["usage"])
+                span.set_attribute("gen_ai.usage.input_tokens", usage["prompt_tokens"].to_i)
+                span.set_attribute("gen_ai.usage.output_tokens", usage["completion_tokens"].to_i)
+                span.set_attribute("gen_ai.usage.total_tokens", usage["total_tokens"].to_i)
+              end
+
+              if (choice = response.dig("choices", 0))
+                span.set_attribute("gen_ai.response.finish_reason", choice["finish_reason"].to_s)
+              end
+            end
+
+            response
+          end
+        end
+
+        private
+
+        def tracer
+          OpenTelemetry.tracer_provider.tracer("railswatch_gem-ai")
+        end
+      end
+    end
+  end
+end

data/lib/railswatch_gem/railtie.rb

@@ -1,21 +1,14 @@
 # frozen_string_literal: true
 
-require "rails/railtie"
-require_relative "middleware/request_context"
-
 module RailswatchGem
   class Railtie < ::Rails::Railtie
-    # Insert our middleware at the very top (index 0) to ensure we catch everything,
-    # including potential errors in other middlewares.
-    initializer "railswatch.middleware" do |app|
-      app.middleware.insert_before 0, RailswatchGem::Middleware::RequestContext
-    end
-
     # Automatically boot the instrumentation when Rails finishes initializing.
     config.after_initialize do
-      # Only boot if the user hasn't disabled auto_boot in their config
-      if RailswatchGem.configuration.auto_boot
-        RailswatchGem.boot!
+      # Check if properly configured (e.g. via ENV vars or initializer)
+      if RailswatchGem.config.api_key.present?
+        RailswatchGem.start!
+      else
+        puts "[Railswatch] API Key not found. Observability disabled."
       end
     end
   end

data/lib/railswatch_gem/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RailswatchGem
-  VERSION = "0.1.5"
+  VERSION = "0.2.0"
 end