AllSpark Monitoring Gem

A comprehensive monitoring and instrumentation library that transforms Rails applications into highly compatible targets for AllSpark Builder development workflows. This gem provides auto-instrumentation, real-time monitoring, error tracking, and seamless integration with the AllSpark Builder platform.

Features

• Auto-Instrumentation: Automatically instruments your Rails application with zero configuration
• Real-Time Monitoring: Tracks console logs, network requests, performance metrics, and errors
• DevTools Integration: Seamlessly integrates with browser DevTools for enhanced debugging
• Security-First: Built-in data sanitization and configurable security settings
• Environment-Aware: Smart defaults based on Rails environment (development/staging/production)
• Flexible Configuration: Extensive configuration options to customize monitoring behavior
• Webhook Communication: Secure webhook-based communication with AllSpark Builder
• Client-Side Monitoring: JavaScript injection for browser-side event tracking

Installation

Add this line to your application's Gemfile:

gem 'allspark'

And then execute:

bundle install

Or install it yourself as:

gem install allspark

Configuration

Basic Setup

The gem automatically configures itself with sensible defaults when Rails is present. For custom configuration, create an initializer:

# config/initializers/allspark.rb
AllSpark.configure do |config|
  # Core settings
  config.enabled = true # Enable/disable monitoring
  config.builder_url = 'https://builder.allspark.build' # AllSpark Builder URL
  config.api_key = ENV['ALLSPARK_API_KEY'] # Your API key
  config.app_id = 'my_app' # Application identifier
  
  # Context for correlation
  config.app_project_id = ENV['ALLSPARK_APP_PROJECT_ID']
  config.build_session_id = ENV['ALLSPARK_BUILD_SESSION_ID']
  
  # Monitoring settings
  config.monitoring_level = :full # :minimal or :full
  config.console_monitoring = true # Track console logs
  config.network_monitoring = true # Track network requests
  config.performance_monitoring = true # Track performance metrics
  config.error_monitoring = true # Track errors
  config.dom_monitoring = true # Track DOM events
  
  # Security settings
  config.sanitize_data = true # Sanitize sensitive data
  config.audit_logging = false # Enable audit logging
  
  # Feature flags
  config.enable_console_api = true # Enable console API endpoints
  config.enable_file_operations = false # Enable file operation tracking
  config.enable_database_introspection = false # Enable database introspection
end

Environment Variables

The gem supports configuration through environment variables:

• ALLSPARK_ENABLED - Enable/disable the gem (true/false)
• ALLSPARK_BUILDER_URL - AllSpark Builder URL
• ALLSPARK_API_KEY or ALLSPARK_INSTANCE_API_KEY - API key for authentication
• ALLSPARK_APP_ID - Application identifier
• ALLSPARK_APP_PROJECT_ID - Project ID for correlation
• ALLSPARK_BUILD_SESSION_ID - Build session ID for correlation

Rails Integration

When Rails is present, the gem automatically:

1. Loads the instrumentation middleware
2. Mounts the engine for API endpoints
3. Configures environment-specific defaults
4. Injects monitoring scripts into HTML responses

Usage

Automatic Monitoring

Once configured, the gem automatically:

• Instruments all HTTP requests/responses
• Tracks Rails errors and exceptions
• Monitors performance metrics
• Injects client-side monitoring scripts

Manual Reporting

You can also manually report events:

# Report an error
begin
  # some code
rescue => e
  AllSpark::Monitoring::Reporter.report_error(e, { 
    user_id: current_user.id,
    action: 'process_payment'
  })
end

# Report console logs
AllSpark::Monitoring::Reporter.report_console_log(:info, "Payment processed", {
  amount: 100.00,
  currency: 'USD'
})

# Report performance metrics
AllSpark::Monitoring::Reporter.report_performance_metric('database_query_time', 125.5, {
  query: 'complex_aggregation'
})

# Report custom events
AllSpark::Monitoring::Reporter.report_custom_event('user_action', {
  action: 'clicked_checkout',
  timestamp: Time.now
})

Security Features

The gem includes built-in security features:

• Data Sanitization: Automatically sanitizes sensitive data before transmission
• Allowed Origins: Configurable list of allowed origins for CORS
• Audit Logging: Optional audit trail of all monitoring activities
• Environment Protection: Different defaults for production vs development

Middleware

The gem includes Rack middleware that:

• Instruments HTTP requests and responses
• Injects monitoring scripts into HTML pages
• Tracks request timing and performance
• Captures and reports errors
• Sends telemetry data via webhooks

API Endpoints

When mounted in a Rails application, the gem provides:

• /allspark/api/console - Console API for DevTools integration
• /allspark/assets/allspark-monitor.js - Client-side monitoring script

Development Workflow Integration

The AllSpark gem is designed to work seamlessly with AllSpark Builder:

1. Auto-Discovery: AllSpark Builder automatically detects gem-instrumented applications
2. Real-Time Monitoring: See live updates in the Builder DevTools
3. Error Tracking: Errors are automatically captured and displayed
4. Performance Insights: Track and optimize application performance
5. Development Tools: Enhanced debugging capabilities in development

Testing

Run the test suite:

bundle exec rspec

Run with coverage:

COVERAGE=true bundle exec rspec

Advanced Configuration

Custom Communication Manager

You can implement custom communication strategies:

class MyCustomManager < AllSpark::Communication::Manager
  def send_monitoring_data(event_type, data)
    # Custom implementation
  end
end

Monitoring Levels

• :minimal - Basic error tracking and critical metrics only
• :full - Complete monitoring including console, network, and DOM events

Environment-Specific Behavior

The gem automatically adjusts its behavior based on the Rails environment:

• Development: Full monitoring, console API enabled, detailed logging
• Test: Minimal monitoring, suitable for test suites
• Production: Security-focused, performance-optimized, audit logging

Troubleshooting

Monitoring Not Working

1. Check if the gem is enabled: AllSpark.enabled?
2. Verify configuration is valid: AllSpark.configuration.valid?
3. Check environment variables are set correctly
4. Ensure middleware is loaded: Check Rails.application.middleware

Performance Impact

The gem is designed to have minimal performance impact:

• Asynchronous webhook communication
• Intelligent sampling for high-traffic applications
• Configurable monitoring levels
• Automatic disabling in production when not configured

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/TanookiLabs/allspark-monitoring-gem.

License

The gem is available as open source under the terms of the MIT License.

Support

For support, please contact the AllSpark team at [email protected] or visit https://allspark.build

Version History

See CHANGELOG.md for a history of changes.