Lescopr Ruby SDK

Lescopr is a zero-configuration Ruby monitoring SDK that automatically captures logs, errors, and exceptions from any Ruby project and streams them in real-time to the Lescopr app.

Works out of the box with Rails, Sinatra, Rack, Hanami, Grape, and plain Ruby.

Features
Requirements
Installation
Quick Start
Framework Integration
- Rails
- Sinatra
- Rack
- Plain Ruby
Architecture
CLI Reference
Advanced Configuration
RubyGems
License

Features

✅ Automatic error capture — hooks into Rails process_action, Rack middleware, and at_exit
✅ Framework auto-detection — detects Rails, Sinatra, Hanami, Grape, Padrino and plain Rack from Gemfile
✅ Background daemon — Ruby thread, completely non-blocking, flushes every 5 seconds
✅ HTTP batch transport — logs are batched and sent via net/http (no external gem required)
✅ Zero runtime dependencies — only json (already in stdlib since Ruby 2.7)
✅ Works everywhere — Rails, Sinatra, Rack, scripts, plain Ruby

Requirements

Requirement	Version
Ruby	≥ 2.7
Bundler	≥ 2.0
`json`	bundled with Ruby

Note: No external gem required at runtime. net/http and openssl are part of Ruby's stdlib.

Installation

Add to your Gemfile:

gem "lescopr"

Then run:

bundle install

Or install directly:

gem install lescopr

Quick Start

Step 1 — Initialise the SDK in your project directory:

bundle exec lescopr init --sdk-key YOUR_SDK_KEY

This detects your framework, registers the project with the Lescopr API, and writes .lescopr.json.

Step 2 — Integrate into your application (see Framework Integration below).

That's it. All logs and exceptions are forwarded to the Lescopr app automatically.

Framework Integration

Rails

The SDK registers automatically via the Railtie. Simply add the gem and create an initializer:

config/initializers/lescopr.rb:

Lescopr.configure do |c|
  c.sdk_key     = ENV["LESCOPR_SDK_KEY"]
  c.api_key     = ENV["LESCOPR_API_KEY"]
  c.environment = Rails.env
end

Environment variables (.env / credentials):

LESCOPR_SDK_KEY=lsk_xxxx
LESCOPR_API_KEY=lak_xxxx
LESCOPR_ENVIRONMENT=production

All controller exceptions are captured automatically via process_action.action_controller notification.

Sinatra

require "sinatra"
require "lescopr"

Lescopr.init!(sdk_key: ENV["LESCOPR_SDK_KEY"], api_key: ENV["LESCOPR_API_KEY"])

class MyApp < Sinatra::Base
  register Lescopr::Integrations::Sinatra::Extension

  get "/" do
    lescopr_log(:info, "Home page visited")
    "Hello!"
  end
end

Rack

# config.ru
require "lescopr"

Lescopr.init!(sdk_key: ENV["LESCOPR_SDK_KEY"], api_key: ENV["LESCOPR_API_KEY"])

use Lescopr::Integrations::Rack::Middleware

run MyApp

Plain Ruby

require "lescopr"

Lescopr.init!(
  sdk_key:     "lsk_xxxx",
  api_key:     "lak_xxxx",
  environment: "production"
)

# Manual logging
Lescopr.log(:info, "Job started", { job: "EmailWorker" })

# Exceptions are captured automatically at_exit

Architecture

Your Ruby Application
        │
        │  Rails.logger / raise / Lescopr.log
        ▼
┌─────────────────────────────────┐
│  Railtie / Rack Middleware      │  (framework hooks)
│  OR at_exit handler             │  (plain Ruby)
└──────────────┬──────────────────┘
               │ push to LogQueue
               ▼
┌─────────────────────────────────┐
│      DaemonRunner (Thread)      │  flushes every 5 s
│      Heartbeat every 30 s       │
└──────────────┬──────────────────┘
               │ HTTPS batch (net/http)
               ▼
     https://api.lescopr.com
               │
               ▼
     Lescopr App
  https://app.lescopr.com

Key components:

Component	Path	Role
`Lescopr` (module)	`lib/lescopr.rb`	Entry point, `configure`, `init!`, `log`
`Core::Client`	`lib/lescopr/core/client.rb`	Central client — config, queue, daemon lifecycle
`Core::DaemonRunner`	`lib/lescopr/core/daemon_runner.rb`	Background thread — flush + heartbeat
`Core::LogQueue`	`lib/lescopr/core/log_queue.rb`	Thread-safe in-memory queue
`Transport::HttpClient`	`lib/lescopr/transport/http_client.rb`	HTTPS delivery via `net/http`
`Filesystem::ProjectAnalyzer`	`lib/lescopr/filesystem/project_analyzer.rb`	Framework detection from `Gemfile`
`Filesystem::ConfigManager`	`lib/lescopr/filesystem/config_manager.rb`	Thread-safe `.lescopr.json` r/w
`Integrations::Rails::Railtie`	`lib/lescopr/integrations/rails/railtie.rb`	Auto-registers in Rails
`Integrations::Rack::Middleware`	`lib/lescopr/integrations/rack/middleware.rb`	Exception capture for Rack apps
`Integrations::Sinatra::Extension`	`lib/lescopr/integrations/sinatra/extension.rb`	`register` for Sinatra
CLI	`exe/lescopr`	`init`, `status`, `diagnose`, `reset`

CLI Reference

bundle exec lescopr [COMMAND] [OPTIONS]

Command	Description
`init --sdk-key KEY`	Initialise the SDK in the current project
`status`	Show SDK configuration and daemon status
`diagnose`	Run a full diagnostic (Ruby env, config, API connectivity)
`reset`	Remove `.lescopr.json`, `.lescopr.pid`, `.lescopr.log`

Advanced Configuration

.lescopr.json is generated automatically by lescopr init:

{
  "sdk_id": "proj_xxxx",
  "sdk_key": "lsk_xxxx",
  "api_key": "lak_xxxx",
  "environment": "production",
  "project_name": "my-app",
  "project_stack": ["rails"]
}

Security: Add .lescopr.json to your .gitignore.

Environment variables

Variable	Description
`LESCOPR_SDK_KEY`	SDK key (overrides `.lescopr.json`)
`LESCOPR_API_KEY`	API key (overrides `.lescopr.json`)
`LESCOPR_ENVIRONMENT`	`development` or `production`
`LESCOPR_DEBUG=true`	Enables verbose output to `.lescopr.log`

RubyGems

The gem is available on RubyGems: lescopr

To publish a new release:

./scripts/release.sh 0.2.0

Support

Channel	Link
📖 Documentation	https://lescopr.com/docs
🌐 App	https://app.lescopr.com
📧 Email	support@lescopr.com
🐛 Bug reports	https://github.com/Lescopr/lescopr-ruby/issues