Ruby Integration
Add the spyglasses gem to track AI bots and AI referral traffic in Rails, Sinatra or any Rack app. Covers installation, middleware and configuration.
Spyglasses integrates seamlessly with Ruby web applications through our official gem. The gem provides a Rack middleware that works with Rails, Sinatra, and any other Rack-based Ruby framework.
Installation
-
Add the gem to your Gemfile:
Then run:
Or install directly:
-
Set your API key: Add your Spyglasses API key to your environment variables:
Rails Integration
Option 1: Application Configuration (Recommended)
Add the middleware to your Rails application in config/application.rb:
Option 2: Initializer with Configuration
Create an initializer for more control over the configuration:
Rails-Specific Considerations
Active Storage: By default, Rails Active Storage routes (/rails/active_storage/*) are automatically excluded from monitoring.
Asset Pipeline: Static assets are automatically excluded, but if you have custom asset routes, add them to exclude_paths.
API-Only Applications: For Rails API applications, the middleware works the same way:
Development vs Production: Consider enabling debug mode only in development:
Sinatra Integration
For Sinatra applications, add the middleware using the use directive:
Sinatra with Options
You can also pass options directly to the middleware:
Other Ruby Frameworks
Hanami
Roda
Rack Application
For pure Rack applications:
Configuration Options
The middleware accepts these configuration options:
Environment Variables
Set these environment variables for configuration:
| Variable | Description | Default |
|---|---|---|
SPYGLASSES_API_KEY | Your Spyglasses API key | Required |
SPYGLASSES_DEBUG | Enable debug logging | false |
SPYGLASSES_AUTO_SYNC | Auto-sync patterns on startup | true |
SPYGLASSES_CACHE_TTL | Pattern cache TTL in seconds | 86400 (24 hours) |
SPYGLASSES_COLLECT_ENDPOINT | Custom collector endpoint | https://www.spyglasses.io/api/collect |
SPYGLASSES_PATTERNS_ENDPOINT | Custom patterns endpoint | https://www.spyglasses.io/api/patterns |
Deployment
Heroku
Add your API key to Heroku config vars:
Docker
Add environment variables to your Dockerfile:
Or use docker-compose:
AWS/EC2
Set environment variables in your deployment configuration or use AWS Systems Manager Parameter Store:
DigitalOcean App Platform
Add environment variables in your app configuration:
Performance Considerations
The Spyglasses middleware is designed for high-performance Ruby applications:
- Minimal Overhead: Typically under 1ms per request
- Background Logging: API calls run in background threads
- Smart Exclusions: Static assets automatically excluded
- Pattern Caching: Compiled regex patterns are cached
Thread Safety
The middleware is thread-safe and works well with:
- Puma: Multi-threaded web server
- Unicorn: Multi-process web server
- Passenger: Both threading and forking modes
Testing
In your test environment, disable API calls:
For RSpec, you might want to stub API calls:
Manual Usage
You can also use Spyglasses outside of the middleware for manual detection:
Verifying Installation
After deploying your Ruby application with Spyglasses, verify the installation by:
- Check logs for Spyglasses initialization messages (if debug enabled)
- Visit your site with different user agents to generate test traffic
- Monitor your dashboard at spyglasses.io for incoming data
Enable debug mode temporarily to see detection in action:
Troubleshooting
Common Issues
Gem not loading
- Ensure gem is in your Gemfile and
bundle installwas run - Check for conflicting gems or Ruby version issues
API key not found
- Verify
SPYGLASSES_API_KEYenvironment variable is set - Check for typos in the environment variable name
- Ensure deployment includes environment variables
Middleware not detecting traffic
- Verify middleware is properly added to your application
- Check exclude_paths configuration for overly broad exclusions
- Enable debug mode to see processing logs
Performance issues
- Review exclude_paths to ensure static assets are excluded
- Monitor background thread performance in production
- Check network latency to Spyglasses endpoints
Rails-specific issues
- Ensure middleware is added in the correct location
- Check for conflicts with other middleware (especially authentication)
- Verify Rails version compatibility (6.0+ recommended)
Debug Mode
Enable debug logging to troubleshoot issues:
This will output detailed logs about:
- Pattern loading and synchronization
- Request processing and detection results
- API communication attempts and responses
Memory Usage
If you notice memory issues:
- Monitor pattern cache size
- Check for thread leaks in background logging
- Consider adjusting cache TTL for frequent pattern updates
Need help? Contact support@spyglasses.io