fluyenta-ruby 0.1.14

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 87d4a26be4c3abfeaeda6fc7c0c197215a457d1444f24ba224305c9e080f286b
+  data.tar.gz: 609546d538388627c1ace6840f7c518ca92fbcd27b618fa37ffd681a6d604f99
+SHA512:
+  metadata.gz: 6313badd5547bee8de8d489cb353d8c1265fcfc84bfd13eacba22c33cdd5982a309fdb153332c45aa04770bb0eb9d381f902bbefa5fac3fc0781691d878b5d91
+  data.tar.gz: b6b248d819cac668ace6cba23f2fe6f71afcca695b3cc6fdd3c1a675654a5e795be72ba985791d2666d94c02007389acf40bfec91d48a964083f10f47dbf2bd5

data/CHANGELOG.md

@@ -0,0 +1,68 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.13] - 2026-02-24
+
+### Fixed
+
+- **Rails LogFormatter** - Fix `TypeError: wrong element type Hash at 0 (expected array)` in `format_params_toml`
+  - `hash_like?` incorrectly matched Arrays (they respond to `to_h` and `each`), causing `Array#to_h` to fail when params contained arrays of hashes
+
+## [0.1.1] - 2025-12-23
+
+### Fixed
+
+- **Reflex** - Improved backtrace parsing
+  - Handle different Ruby backtrace formats (backtick+quote and single quotes)
+  - Parse backtrace lines without method names
+  - Better `in_app` frame detection for absolute paths
+
+## [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,11 @@
+OSAaSy License
+
+Copyright © 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,571 @@
+# BrainzLab Ruby SDK
+
+[![Gem Version](https://badge.fury.io/rb/brainzlab.svg)](https://rubygems.org/gems/brainzlab)
+[![CI](https://github.com/brainz-lab/brainzlab-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/brainz-lab/brainzlab-ruby/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/brainz-lab/brainzlab-ruby/actions/workflows/codeql.yml/badge.svg)](https://github.com/brainz-lab/brainzlab-ruby/actions/workflows/codeql.yml)
+[![codecov](https://codecov.io/gh/brainz-lab/brainzlab-ruby/graph/badge.svg)](https://codecov.io/gh/brainz-lab/brainzlab-ruby)
+[![Docs](https://img.shields.io/badge/docs-brainzlab.ai-orange)](https://docs.brainzlab.ai/sdk/ruby/installation)
+[![License: OSAaSy](https://img.shields.io/badge/License-OSAaSy-blue.svg)](LICENSE)
+
+Official Ruby SDK for [BrainzLab](https://brainzlab.ai) - the complete observability platform.
+
+- **Recall** - Structured logging
+- **Reflex** - Error tracking
+- **Pulse** - APM & distributed tracing
+
+## Installation
+
+### From RubyGems (recommended)
+
+Add to your Gemfile:
+
+```ruby
+gem 'brainzlab'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+### From GitHub Packages
+
+Add the GitHub Packages source to your Gemfile:
+
+```ruby
+source "https://rubygems.pkg.github.com/brainz-lab" do
+  gem 'brainzlab'
+end
+```
+
+Configure Bundler with your GitHub token:
+
+```bash
+bundle config set --global rubygems.pkg.github.com USERNAME:TOKEN
+```
+
+## Quick Start
+
+### Get Your API Key
+
+1. Sign up at [platform.brainzlab.ai](https://platform.brainzlab.ai)
+2. Create or select a project
+3. Copy your API key (`sk_live_xxx` or `sk_test_xxx`)
+4. Set it as `BRAINZLAB_SECRET_KEY` environment variable
+
+**One key, all products**: Your Platform API key works across Recall, Reflex, Pulse, and all BrainzLab products. No separate keys needed.
+
+### Configuration
+
+```ruby
+# config/initializers/brainzlab.rb
+BrainzLab.configure do |config|
+  # Authentication (required) - Your Platform API key
+  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`) |
+| `BRAINZLAB_MODE` | SDK mode: `production` (default) or `development` (offline) |
+| `BRAINZLAB_DEV_DB_PATH` | SQLite database path for development mode |
+| `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
+
+Debug mode provides detailed visibility into SDK operations, including all API requests and responses with timing information. This is invaluable for troubleshooting integration issues.
+
+### Enabling Debug Mode
+
+```ruby
+# In your initializer
+BrainzLab.configure do |config|
+  config.debug = true
+end
+
+# Or via environment variable
+# BRAINZLAB_DEBUG=true
+```
+
+### Debug Output Format
+
+When debug mode is enabled, you'll see colorized output in your terminal:
+
+```
+[BrainzLab] 12:34:56 -> Recall POST /api/v1/logs (count: 5)
+[BrainzLab] 12:34:56 <- Recall 200 OK (45ms)
+
+[BrainzLab] 12:34:57 -> Reflex POST /api/v1/errors (exception: RuntimeError)
+[BrainzLab] 12:34:57 <- Reflex 201 Created (23ms)
+
+[BrainzLab] 12:34:58 -> Pulse POST /api/v1/traces (name: GET /users)
+[BrainzLab] 12:34:58 <- Pulse 200 OK (18ms)
+```
+
+The output includes:
+- Timestamp for each operation
+- Service name (Recall, Reflex, Pulse, etc.)
+- Request method and path
+- Payload summary (log count, exception type, etc.)
+- Response status code and message
+- Request duration with color coding (green < 100ms, yellow < 1s, red > 1s)
+
+### Custom Logger
+
+You can provide your own logger to capture debug output:
+
+```ruby
+BrainzLab.configure do |config|
+  config.debug = true
+  config.logger = Rails.logger
+  # Or any Logger-compatible object
+  config.logger = Logger.new('log/brainzlab.log')
+end
+```
+
+### Debug Callbacks
+
+For advanced debugging and monitoring, you can hook into SDK operations:
+
+```ruby
+BrainzLab.configure do |config|
+  # Called before each API request
+  config.on_send = ->(service, method, path, payload) {
+    Rails.logger.debug "[BrainzLab] Sending to #{service}: #{method} #{path}"
+
+    # You can use this to:
+    # - Log all outgoing requests
+    # - Send metrics to your monitoring system
+    # - Add custom tracing
+  }
+
+  # Called when an SDK error occurs
+  config.on_error = ->(error, context) {
+    Rails.logger.error "[BrainzLab] Error in #{context[:service]}: #{error.message}"
+
+    # You can use this to:
+    # - Alert on SDK failures
+    # - Track error rates
+    # - Fallback to alternative logging
+
+    # Note: This is for SDK errors, not application errors
+    # Application errors are sent to Reflex as normal
+  }
+end
+```
+
+### Programmatic Debug Logging
+
+You can also use the Debug module directly:
+
+```ruby
+# Log a debug message (only outputs when debug=true)
+BrainzLab::Debug.log("Custom message", level: :info)
+BrainzLab::Debug.log("Something went wrong", level: :error, error_code: 500)
+
+# Measure operation timing
+BrainzLab::Debug.measure(:custom, "expensive_operation") do
+  # Your code here
+end
+
+# Check if debug mode is enabled
+if BrainzLab::Debug.enabled?
+  # Perform additional debug operations
+end
+```
+
+### Debug Output Levels
+
+Debug messages are color-coded by level:
+- **DEBUG** (gray) - Verbose internal operations
+- **INFO** (cyan) - Normal operations
+- **WARN** (yellow) - Potential issues
+- **ERROR** (red) - Failed operations
+
+## Development Mode
+
+Development mode allows you to use the SDK without a BrainzLab server connection. Events are logged to stdout in a readable format and stored locally in a SQLite database.
+
+### Configuration
+
+```ruby
+# config/initializers/brainzlab.rb
+BrainzLab.configure do |config|
+  # Enable development mode (works offline)
+  config.mode = :development
+
+  # Optional: customize the SQLite database path (default: tmp/brainzlab.sqlite3)
+  config.development_db_path = 'tmp/brainzlab_dev.sqlite3'
+
+  # Other settings still apply
+  config.environment = Rails.env
+  config.service = 'my-app'
+end
+```
+
+Or use the environment variable:
+
+```bash
+export BRAINZLAB_MODE=development
+```
+
+### Features
+
+In development mode:
+
+- **No server connection required** - Works completely offline
+- **Stdout logging** - All events are pretty-printed to the console with colors
+- **Local storage** - Events are stored in SQLite at `tmp/brainzlab.sqlite3`
+- **Queryable** - Use `BrainzLab.development_events` to query stored events
+
+### Querying Events
+
+```ruby
+# Get all events
+events = BrainzLab.development_events
+
+# Filter by service
+logs = BrainzLab.development_events(service: :recall)
+errors = BrainzLab.development_events(service: :reflex)
+traces = BrainzLab.development_events(service: :pulse)
+
+# Filter by event type
+BrainzLab.development_events(event_type: 'log')
+BrainzLab.development_events(event_type: 'error')
+BrainzLab.development_events(event_type: 'trace')
+
+# Filter by time
+BrainzLab.development_events(since: 1.hour.ago)
+
+# Limit results
+BrainzLab.development_events(limit: 10)
+
+# Combine filters
+BrainzLab.development_events(
+  service: :recall,
+  since: 30.minutes.ago,
+  limit: 50
+)
+
+# Get stats by service
+BrainzLab.development_stats
+# => { recall: 42, reflex: 3, pulse: 15 }
+
+# Clear all stored events
+BrainzLab.clear_development_events!
+```
+
+### Console Output
+
+In development mode, events are pretty-printed to stdout:
+
+```
+[14:32:15.123] [RECALL] log [INFO] User signed up
+  user_id: 123
+  data: {email: "user@example.com"}
+
+[14:32:16.456] [REFLEX] error RuntimeError: Something went wrong
+  error_class: "RuntimeError"
+  environment: "development"
+  request_id: "abc-123"
+
+[14:32:17.789] [PULSE] trace GET /users (45.2ms)
+  request_method: "GET"
+  request_path: "/users"
+  status: 200
+  db_ms: 12.3
+```
+
+### Use Cases
+
+Development mode is useful for:
+
+- **Local development** without setting up a BrainzLab account
+- **Testing** SDK integration in CI/CD pipelines
+- **Debugging** to inspect exactly what events would be sent
+- **Offline development** when working without internet access
+
+## 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)
+
+## Related
+
+- [Recall](https://github.com/brainz-lab/recall) - Logging service
+- [Reflex](https://github.com/brainz-lab/reflex) - Error tracking service
+- [Pulse](https://github.com/brainz-lab/pulse) - APM service
+- [Stack](https://github.com/brainz-lab/stack) - Self-hosted deployment
+
+## Contributors
+
+<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
+<!-- prettier-ignore-start -->
+<!-- markdownlint-disable -->
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
+<!-- ALL-CONTRIBUTORS-LIST:END -->
+
+Thanks to all our contributors! See [all-contributors](https://allcontributors.org) for how to add yourself.
+
+
+## License
+
+OSAaSy License - see [LICENSE](LICENSE) for details.