brainzlab 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dea1ca28ddfd1614e67dd24d5a8cb36663e4cf3b75d00dabfa9ff9e01d95e2cc
+  data.tar.gz: 753cf41c654d57476fdcd915e1bc088c0fe9a2242cf4464431b520c375012884
+SHA512:
+  metadata.gz: 91382c001767b6f0ca913cb5e12956d7a3664d0a098c94540948796d89db44e6b08c12a5fa9bdf8666c5909822d97bfda68638aaf20de945614a0ee329ed20e5
+  data.tar.gz: ec17f7bf47291eb1cb00f0173972e866f61634d21d4608e432f7412c866273abb975cd6e9e32a50022377129c489f6819edd21fcbed3d6de6e753113fb79cd0d

data/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.0] - 2025-01-01
+
+### Added
+
+- **Recall** - Structured logging
+  - Log levels (debug, info, warn, error, fatal)
+  - Buffered batch sending
+  - Auto-provisioning support
+  - Rails integration
+
+- **Reflex** - Error tracking
+  - Exception capturing with context
+  - Breadcrumbs support
+  - User context tracking
+  - Sample rate and before_send hooks
+  - Custom fingerprinting
+  - Auto-provisioning support
+
+- **Pulse** - APM & Distributed Tracing
+  - Request tracing with breakdown
+  - Distributed tracing (W3C Trace Context + B3)
+  - Auto-provisioning support
+
+- **Instrumentation** (13 libraries)
+  - Rails/Rack middleware
+  - Active Record (SQL queries)
+  - Net::HTTP
+  - Faraday
+  - HTTParty
+  - Redis (v4 and v5+)
+  - Sidekiq (server and client middleware)
+  - Delayed::Job
+  - GraphQL (query and field tracing)
+  - Grape API
+  - MongoDB/Mongoid
+  - Elasticsearch/OpenSearch
+  - ActionMailer
+
+- **Configuration**
+  - Environment variable support
+  - Per-product enable/disable
+  - Sensitive field scrubbing
+  - Debug mode
+
+- **Rails Integration**
+  - Automatic setup via Railtie
+  - Request context propagation
+  - User context from current_user

data/LICENSE

@@ -0,0 +1,26 @@
+Ossassy License
+
+Copyright (c) 2025, Brainz Lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+No licensee or downstream recipient may use the Software (including any modified
+or derivative versions) to directly compete with the original Licensor by
+offering it to third parties as a hosted, managed, or Software-as-a-Service
+(SaaS) product or cloud service where the primary value of the service is the
+functionality of the Software itself.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,311 @@
+# BrainzLab Ruby SDK
+
+Official Ruby SDK for [BrainzLab](https://brainzlab.ai) - the complete observability platform.
+
+- **Recall** - Structured logging
+- **Reflex** - Error tracking
+- **Pulse** - APM & distributed tracing
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'brainzlab'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Quick Start
+
+### Configuration
+
+```ruby
+# config/initializers/brainzlab.rb
+BrainzLab.configure do |config|
+  # Authentication (required)
+  config.secret_key = ENV['BRAINZLAB_SECRET_KEY']
+
+  # Environment
+  config.environment = Rails.env
+  config.service = 'my-app'
+
+  # Enable/disable products
+  config.recall_enabled = true   # Logging
+  config.reflex_enabled = true   # Error tracking
+  config.pulse_enabled = true    # APM
+
+  # Auto-provisioning (creates projects automatically)
+  config.recall_auto_provision = true
+  config.reflex_auto_provision = true
+  config.pulse_auto_provision = true
+end
+```
+
+## Recall - Structured Logging
+
+```ruby
+# Log levels
+BrainzLab::Recall.debug("Debug message", details: "...")
+BrainzLab::Recall.info("User signed up", user_id: user.id)
+BrainzLab::Recall.warn("Rate limit approaching", current: 95, limit: 100)
+BrainzLab::Recall.error("Payment failed", error: e.message, amount: 99.99)
+BrainzLab::Recall.fatal("Database connection lost")
+
+# With context
+BrainzLab::Recall.info("Order created",
+  order_id: order.id,
+  user_id: user.id,
+  total: order.total,
+  items: order.items.count
+)
+```
+
+### Configuration Options
+
+```ruby
+config.recall_min_level = :info        # Minimum log level (:debug, :info, :warn, :error, :fatal)
+config.recall_buffer_size = 50         # Batch size before flush
+config.recall_flush_interval = 5       # Seconds between flushes
+```
+
+## Reflex - Error Tracking
+
+```ruby
+# Capture exceptions
+begin
+  risky_operation
+rescue => e
+  BrainzLab::Reflex.capture(e,
+    user_id: current_user.id,
+    order_id: order.id
+  )
+end
+
+# Add breadcrumbs for context
+BrainzLab::Reflex.add_breadcrumb("User clicked checkout",
+  category: "ui.click",
+  data: { button: "checkout" }
+)
+
+# Set user context
+BrainzLab::Reflex.set_user(
+  id: user.id,
+  email: user.email,
+  plan: user.plan
+)
+
+# Add tags
+BrainzLab::Reflex.set_tags(
+  environment: "production",
+  region: "us-east-1"
+)
+```
+
+### Configuration Options
+
+```ruby
+config.reflex_excluded_exceptions = ['ActiveRecord::RecordNotFound']
+config.reflex_sample_rate = 1.0        # 1.0 = 100%, 0.5 = 50%
+config.reflex_before_send = ->(event) {
+  # Modify or filter events
+  event[:tags][:custom] = 'value'
+  event  # Return nil to drop the event
+}
+```
+
+## Pulse - APM & Distributed Tracing
+
+Pulse automatically instruments your application to track performance.
+
+### Automatic Instrumentation
+
+The SDK automatically instruments:
+
+| Library | Description |
+|---------|-------------|
+| Rails/Rack | Request tracing with breakdown |
+| Active Record | SQL queries with timing |
+| Net::HTTP | Outbound HTTP calls |
+| Faraday | HTTP client requests |
+| HTTParty | HTTP client requests |
+| Redis | Redis commands |
+| Sidekiq | Background job processing |
+| Delayed::Job | Background job processing |
+| GraphQL | Query and field resolution |
+| Grape | API endpoint tracing |
+| MongoDB | Database operations |
+| Elasticsearch | Search operations |
+| ActionMailer | Email delivery |
+
+### Configuration Options
+
+```ruby
+# Enable/disable specific instrumentations
+config.instrument_http = true           # Net::HTTP, Faraday, HTTParty
+config.instrument_active_record = true  # SQL queries
+config.instrument_redis = true          # Redis commands
+config.instrument_sidekiq = true        # Sidekiq jobs
+config.instrument_graphql = true        # GraphQL queries
+config.instrument_mongodb = true        # MongoDB operations
+config.instrument_elasticsearch = true  # Elasticsearch queries
+config.instrument_action_mailer = true  # Email delivery
+config.instrument_delayed_job = true    # Delayed::Job
+config.instrument_grape = true          # Grape API
+
+# Filtering
+config.http_ignore_hosts = ['localhost', '127.0.0.1']
+config.redis_ignore_commands = ['ping', 'info']
+config.pulse_excluded_paths = ['/health', '/ping', '/up', '/assets']
+config.pulse_sample_rate = 1.0          # 1.0 = 100%
+```
+
+### Distributed Tracing
+
+Pulse supports distributed tracing across services using W3C Trace Context and B3 propagation.
+
+```ruby
+# Extracting trace context from incoming requests (automatic in Rails)
+context = BrainzLab::Pulse.extract!(request.headers)
+
+# Injecting trace context into outgoing requests (automatic with instrumentation)
+BrainzLab::Pulse.inject!(headers)
+```
+
+### Custom Spans
+
+```ruby
+BrainzLab::Pulse.trace("process_payment", kind: "payment") do |span|
+  span[:data] = { amount: 99.99, currency: "USD" }
+  process_payment(order)
+end
+```
+
+## Rails Integration
+
+The SDK automatically integrates with Rails when loaded:
+
+- Request context (request_id, path, method, params)
+- Exception reporting to Reflex
+- Performance tracing with Pulse
+- User context from `current_user`
+
+### Setting User Context
+
+```ruby
+class ApplicationController < ActionController::Base
+  before_action :set_brainzlab_context
+
+  private
+
+  def set_brainzlab_context
+    if current_user
+      BrainzLab.set_user(
+        id: current_user.id,
+        email: current_user.email,
+        name: current_user.name
+      )
+    end
+  end
+end
+```
+
+## Sidekiq Integration
+
+For Sidekiq, the SDK automatically:
+
+- Traces job execution with queue wait time
+- Propagates trace context between web and worker
+- Captures job failures to Reflex
+
+```ruby
+# config/initializers/sidekiq.rb
+# Instrumentation is automatic, but you can configure:
+
+BrainzLab.configure do |config|
+  config.instrument_sidekiq = true
+end
+```
+
+## Grape API Integration
+
+For Grape APIs, you can use the middleware:
+
+```ruby
+class API < Grape::API
+  use BrainzLab::Instrumentation::GrapeInstrumentation::Middleware
+
+  # Your API endpoints...
+end
+```
+
+## GraphQL Integration
+
+For GraphQL-Ruby 2.0+, add the tracer:
+
+```ruby
+class MySchema < GraphQL::Schema
+  trace_with BrainzLab::Instrumentation::GraphQLInstrumentation::Tracer
+
+  # Your schema...
+end
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `BRAINZLAB_SECRET_KEY` | API key for authentication |
+| `BRAINZLAB_ENVIRONMENT` | Environment name (default: auto-detect) |
+| `BRAINZLAB_SERVICE` | Service name |
+| `BRAINZLAB_APP_NAME` | App name for auto-provisioning |
+| `BRAINZLAB_DEBUG` | Enable debug logging (`true`/`false`) |
+| `RECALL_URL` | Custom Recall endpoint |
+| `REFLEX_URL` | Custom Reflex endpoint |
+| `PULSE_URL` | Custom Pulse endpoint |
+
+## Scrubbing Sensitive Data
+
+The SDK automatically scrubs sensitive fields:
+
+```ruby
+config.scrub_fields = [:password, :password_confirmation, :token, :api_key, :secret]
+```
+
+## Debug Mode
+
+Enable debug mode to see SDK activity:
+
+```ruby
+config.debug = true
+# Or set BRAINZLAB_DEBUG=true
+```
+
+## Self-Hosted
+
+For self-hosted BrainzLab installations:
+
+```ruby
+BrainzLab.configure do |config|
+  config.recall_url = 'https://recall.your-domain.com'
+  config.reflex_url = 'https://reflex.your-domain.com'
+  config.pulse_url = 'https://pulse.your-domain.com'
+end
+```
+
+## Documentation
+
+Full documentation: [docs.brainzlab.ai](https://docs.brainzlab.ai)
+
+- [Installation Guide](https://docs.brainzlab.ai/sdk/ruby/installation)
+- [Recall (Logging)](https://docs.brainzlab.ai/sdk/ruby/recall)
+- [Reflex (Errors)](https://docs.brainzlab.ai/sdk/ruby/reflex)
+- [Pulse (APM)](https://docs.brainzlab.ai/sdk/ruby/pulse)
+
+## License
+
+Ossassy License - see [LICENSE](LICENSE) for details.

data/lib/brainzlab/configuration.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+module BrainzLab
+  class Configuration
+    LEVELS = %i[debug info warn error fatal].freeze
+
+    attr_accessor :secret_key,
+                  :environment,
+                  :service,
+                  :host,
+                  :commit,
+                  :branch,
+                  :app_name,
+                  :debug,
+                  :recall_enabled,
+                  :recall_url,
+                  :recall_min_level,
+                  :recall_buffer_size,
+                  :recall_flush_interval,
+                  :recall_master_key,
+                  :recall_auto_provision,
+                  :reflex_enabled,
+                  :reflex_url,
+                  :reflex_api_key,
+                  :reflex_master_key,
+                  :reflex_auto_provision,
+                  :reflex_excluded_exceptions,
+                  :reflex_before_send,
+                  :reflex_sample_rate,
+                  :reflex_fingerprint,
+                  :pulse_enabled,
+                  :pulse_url,
+                  :pulse_api_key,
+                  :pulse_master_key,
+                  :pulse_auto_provision,
+                  :pulse_buffer_size,
+                  :pulse_flush_interval,
+                  :pulse_sample_rate,
+                  :pulse_excluded_paths,
+                  :scrub_fields,
+                  :logger,
+                  :instrument_http,
+                  :instrument_active_record,
+                  :instrument_redis,
+                  :instrument_sidekiq,
+                  :instrument_graphql,
+                  :instrument_mongodb,
+                  :instrument_elasticsearch,
+                  :instrument_action_mailer,
+                  :instrument_delayed_job,
+                  :instrument_grape,
+                  :http_ignore_hosts,
+                  :redis_ignore_commands,
+                  :log_formatter_enabled,
+                  :log_formatter_colors,
+                  :log_formatter_hide_assets,
+                  :log_formatter_compact_assets,
+                  :log_formatter_show_params
+
+    def initialize
+      # Authentication
+      @secret_key = ENV["BRAINZLAB_SECRET_KEY"]
+
+      # Environment
+      @environment = ENV["BRAINZLAB_ENVIRONMENT"] || detect_environment
+      @service = ENV["BRAINZLAB_SERVICE"]
+      @host = ENV["BRAINZLAB_HOST"] || detect_host
+
+      # App name for auto-provisioning
+      @app_name = ENV["BRAINZLAB_APP_NAME"]
+
+      # Git context
+      @commit = ENV["GIT_COMMIT"] || ENV["COMMIT_SHA"] || detect_git_commit
+      @branch = ENV["GIT_BRANCH"] || ENV["BRANCH_NAME"] || detect_git_branch
+
+      # Debug mode - enables verbose logging
+      @debug = ENV["BRAINZLAB_DEBUG"] == "true"
+
+      # Recall settings
+      @recall_enabled = true
+      @recall_url = ENV["RECALL_URL"] || "https://recall.brainzlab.ai"
+      @recall_min_level = :debug
+      @recall_buffer_size = 50
+      @recall_flush_interval = 5
+      @recall_master_key = ENV["RECALL_MASTER_KEY"]
+      @recall_auto_provision = true
+
+      # Reflex settings
+      @reflex_enabled = true
+      @reflex_url = ENV["REFLEX_URL"] || "https://reflex.brainzlab.ai"
+      @reflex_api_key = ENV["REFLEX_API_KEY"]
+      @reflex_master_key = ENV["REFLEX_MASTER_KEY"]
+      @reflex_auto_provision = true
+      @reflex_excluded_exceptions = []
+      @reflex_before_send = nil
+      @reflex_sample_rate = nil
+      @reflex_fingerprint = nil  # Custom fingerprint callback
+
+      # Pulse settings
+      @pulse_enabled = true
+      @pulse_url = ENV["PULSE_URL"] || "https://pulse.brainzlab.ai"
+      @pulse_api_key = ENV["PULSE_API_KEY"]
+      @pulse_master_key = ENV["PULSE_MASTER_KEY"]
+      @pulse_auto_provision = true
+      @pulse_buffer_size = 50
+      @pulse_flush_interval = 5
+      @pulse_sample_rate = nil
+      @pulse_excluded_paths = %w[/health /ping /up /assets]
+
+      # Filtering
+      @scrub_fields = %i[password password_confirmation token api_key secret]
+
+      # Internal logger for debugging SDK issues
+      @logger = nil
+
+      # Instrumentation
+      @instrument_http = true  # Enable HTTP client instrumentation (Net::HTTP, Faraday, HTTParty)
+      @instrument_active_record = true  # AR breadcrumbs for Reflex
+      @instrument_redis = true  # Redis command instrumentation
+      @instrument_sidekiq = true  # Sidekiq job instrumentation
+      @instrument_graphql = true  # GraphQL query instrumentation
+      @instrument_mongodb = true  # MongoDB/Mongoid instrumentation
+      @instrument_elasticsearch = true  # Elasticsearch instrumentation
+      @instrument_action_mailer = true  # ActionMailer instrumentation
+      @instrument_delayed_job = true  # Delayed::Job instrumentation
+      @instrument_grape = true  # Grape API instrumentation
+      @http_ignore_hosts = %w[localhost 127.0.0.1]
+      @redis_ignore_commands = %w[ping info]  # Commands to skip tracking
+
+      # Log formatter settings
+      @log_formatter_enabled = true
+      @log_formatter_colors = nil # auto-detect TTY
+      @log_formatter_hide_assets = false
+      @log_formatter_compact_assets = true
+      @log_formatter_show_params = true
+    end
+
+    def recall_min_level=(level)
+      level = level.to_sym
+      raise ArgumentError, "Invalid level: #{level}" unless LEVELS.include?(level)
+
+      @recall_min_level = level
+    end
+
+    def level_enabled?(level)
+      LEVELS.index(level.to_sym) >= LEVELS.index(@recall_min_level)
+    end
+
+    def valid?
+      !@secret_key.nil? && !@secret_key.empty?
+    end
+
+    def reflex_valid?
+      key = reflex_api_key || secret_key
+      !key.nil? && !key.empty?
+    end
+
+    def reflex_auth_key
+      reflex_api_key || secret_key
+    end
+
+    def pulse_valid?
+      key = pulse_api_key || secret_key
+      !key.nil? && !key.empty?
+    end
+
+    def pulse_auth_key
+      pulse_api_key || secret_key
+    end
+
+    def debug?
+      @debug == true
+    end
+
+    def debug_log(message)
+      return unless debug?
+
+      log_message = "[BrainzLab::Debug] #{message}"
+      if logger
+        logger.debug(log_message)
+      else
+        $stderr.puts(log_message)
+      end
+    end
+
+    private
+
+    def detect_environment
+      return ::Rails.env.to_s if defined?(::Rails) && ::Rails.respond_to?(:env)
+      return ENV["RACK_ENV"] if ENV["RACK_ENV"]
+      return ENV["RUBY_ENV"] if ENV["RUBY_ENV"]
+
+      "development"
+    end
+
+    def detect_host
+      require "socket"
+      Socket.gethostname
+    rescue StandardError
+      nil
+    end
+
+    def detect_git_commit
+      `git rev-parse HEAD 2>/dev/null`.strip.presence
+    rescue StandardError
+      nil
+    end
+
+    def detect_git_branch
+      `git rev-parse --abbrev-ref HEAD 2>/dev/null`.strip.presence
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/brainzlab/context.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module BrainzLab
+  class Context
+    THREAD_KEY = :brainzlab_context
+
+    class << self
+      def current
+        Thread.current[THREAD_KEY] ||= new
+      end
+
+      def clear!
+        Thread.current[THREAD_KEY] = nil
+      end
+    end
+
+    attr_accessor :user, :request_id, :session_id
+    attr_accessor :request_method, :request_path, :request_url, :request_params, :request_headers
+    attr_accessor :controller, :action
+    attr_reader :extra, :tags, :breadcrumbs
+
+    def initialize
+      @user = {}
+      @extra = {}
+      @tags = {}
+      @request_id = nil
+      @session_id = nil
+      @request_method = nil
+      @request_path = nil
+      @request_url = nil
+      @request_params = nil
+      @request_headers = nil
+      @controller = nil
+      @action = nil
+      @stack = []
+      @breadcrumbs = Reflex::Breadcrumbs.new
+    end
+
+    def set_user(id: nil, email: nil, name: nil, **extra)
+      @user = { id: id, email: email, name: name }.compact.merge(extra)
+    end
+
+    def set_context(**data)
+      @extra.merge!(data)
+    end
+
+    def set_tags(**data)
+      @tags.merge!(data)
+    end
+
+    def with_context(**data)
+      push_context(data)
+      yield
+    ensure
+      pop_context
+    end
+
+    def to_hash
+      result = {}
+      result[:request_id] = @request_id if @request_id
+      result[:session_id] = @session_id if @session_id
+
+      merged_extra = @extra.dup
+      @stack.each { |ctx| merged_extra.merge!(ctx) }
+
+      result[:user] = @user unless @user.empty?
+      result[:tags] = @tags unless @tags.empty?
+      result[:context] = merged_extra unless merged_extra.empty?
+
+      result
+    end
+
+    def data_hash
+      merged = @extra.dup
+      @stack.each { |ctx| merged.merge!(ctx) }
+      merged[:user] = @user unless @user.empty?
+      merged[:tags] = @tags unless @tags.empty?
+      merged
+    end
+
+    private
+
+    def push_context(data)
+      @stack.push(data)
+    end
+
+    def pop_context
+      @stack.pop
+    end
+  end
+end