tj-scale 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e070c5d82758136d8df85df78f7f6b021f7494cfa8a2b64ff417aff9ad386333
+  data.tar.gz: d4cdd0e53528d48a634b8ee929c498cf63756ae7fd8be239ad6aaf277174052f
+SHA512:
+  metadata.gz: 45b1804fc8ee06924b28d7230645fcb34d2d26fa4c37a412183cbfac6ff9bf82da108876d8012f275c774fc027e312ca0095b9bb6d0b89af6303023d0ae302fa
+  data.tar.gz: 46758b912e0a3ede622ed4ceae6ddb0b78c74b6dfe2cc4022fdf484892320db56204eea15600285bd7cbb6a09286974030b5ba73f983250cf3c3194ebd24632c

data/CHANGELOG.md

@@ -0,0 +1,77 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Changed
+
+- **Gem renamed to `tj-scale`** (was `tj-scale-ruby`); require path is now `require "tj-scale"`. Internal `TjScaleRuby` module and `lib/tj_scale_ruby/` paths are unchanged.
+
+### Removed
+
+- **`min_dynos` / `max_dynos` removed from the gem.** The control plane's dashboard settings are the single source of truth for scaling bounds. `TJ_SCALE_MIN_DYNOS` / `TJ_SCALE_MAX_DYNOS` are ignored, and payloads no longer include `min_dynos` / `max_dynos`.
+
+## [1.2.0] - 2026-06-12
+
+### Added
+
+- **Sidekiq support.** Worker metrics now come from a pluggable queue backend: **Delayed Job** or **Sidekiq**, selected with `TJ_SCALE_JOB_BACKEND` (`delayed_job` / `sidekiq` / `auto`). The default `auto` prefers Sidekiq when the host app has it loaded, otherwise Delayed Job — existing Delayed Job apps need no changes.
+- `TJ_SCALE_SIDEKIQ_QUEUES` — comma-separated list of Sidekiq queues to count (empty = all queues). Sidekiq `queue_time_s` is the latency of the slowest monitored queue.
+- Worker payloads include a `job_backend` field (`"delayed_job"` or `"sidekiq"`).
+- `TjScaleRuby::JobMonitor.backend` exposes the active backend; `TjScaleRuby::JobBackends.resolve/detect` for manual use.
+- **Control plane (tj-scale-dashboard):** Slack notifications. Configure an incoming webhook under Settings → Slack notifications; the control plane posts a message whenever web or worker dynos scale up or down (auto or manual) and, optionally, when a scale attempt fails (throttled to one per app/process per 15 minutes). Includes per-event toggles, channel/username overrides, and a "Send test message" button.
+
+### Changed (repository layout)
+
+- The Rails control plane moved out of this repo's `platform/` directory into the sibling **`tj-scale-dashboard`** project (Rails module renamed `Platform` → `TjScaleDashboard`).
+
+### Changed
+
+- **`delayed_job_active_record` is no longer a runtime dependency.** Host apps bring their own queue gem (`delayed_job_active_record` or `sidekiq`); the gem lazily loads whichever backend is selected. If you rely on Delayed Job, make sure it is in your app's Gemfile (it almost certainly already is).
+- Ingest requests send **`Authorization: Bearer`** as well as **`LOGPLEX_DRAIN_TOKEN`** (TJ Scale Agent API accepts either).
+
+## [1.1.0] - 2026-04-27
+
+### Changed
+
+- **Breaking:** `TJ_SCALE_API_URL` is **required**; hardcoded default ingest URLs were removed.
+- Documented end-to-end behavior in `lib/tj-scale-ruby.rb` (reporter vs control plane).
+- Depend on **`openssl` >= 3.2** and `require "openssl"` before HTTP so metric POSTs avoid CRL verification failures on newer OpenSSL/Ruby combinations (same class of issue as ruby/openssl#949).
+
+### Removed
+
+- `TjScaleRuby::JobMonitor.restart_dynos` and `TJ_SCALE_RESTART_URL` (platform ingest never performed restarts).
+- `TJ_SCALE_METRIC_SOURCE` / heartbeat mode (sent misleading zeros and could interact badly with autoscale rules). Web metrics use the web reporter path + queue middleware instead of skipping DJ queries.
+
+## [1.0.1] - 2026-04-14
+
+### Changed
+
+- Gemspec packaging includes only `lib/**` plus `README.md`, `CHANGELOG.md`, and `LICENSE.txt` (no Gemfile, Rakefile, or other dev-only root files).
+- The monorepo `platform/` app and test directories stay out of the gem.
+- When `.git` is missing, `gem build` still works using the same file list.
+- Require `active_support/core_ext/module/delegation` before `rails/railtie` so the entrypoint loads reliably when Active Support is not yet loaded.
+
+## [1.0.0] - 2026-04-14
+
+First public release of **tj-scale-ruby**.
+
+### Added
+
+- Automatic Delayed Job queue depth reporting to a configurable HTTP endpoint (default interval 20s).
+- Heroku-aware monitoring on the first `web.1` or `worker.1` dyno via `TJ_SCALE_MONITOR_PROCESS`.
+- `TjScaleRuby::Configuration` for target app, process type, min/max dynos (defaults 2–8), interval, priority filters (`TJ_MIN_PRIORITY` / `TJ_MAX_PRIORITY`), and optional heartbeat-only mode (`TJ_SCALE_METRIC_SOURCE=none`; **removed in 1.1.0**).
+- JSON payloads including `job_count`, `timestamp`, and when set `heroku_app`, `target_process`, `min_dynos`, `max_dynos`.
+- `TjScaleRuby::JobMonitor.restart_dynos` for restart requests via the scaling service (**removed in 1.1.0**).
+- `TjScaleRuby.monitor_on_this_dyno?` and `TjScaleRuby.start_monitoring_loop!` (Railtie starts the loop after Rails initializes).
+
+### Performance
+
+- Single `Time.zone.now` per `send_log` for consistent timestamps and queue counts.
+- Cached configuration for priority filters and Heroku app name (no repeated `ENV` reads in the hot path).
+- Memoized `monitor_on_this_dyno?` and parsed API URIs; `Net::HTTP.start` for bounded connection lifecycle per request.
+- Shared `http_post` helper for log and restart calls.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023-2024 Untechnickle
+
+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.
+
+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,504 @@
+# TjScaleRuby
+
+[![Ruby Version](https://img.shields.io/badge/ruby-%3E%3D%203.0.0-red.svg)](https://www.ruby-lang.org/)
+[![Rails Version](https://img.shields.io/badge/rails-%3E%3D%206.1-red.svg)](https://rubyonrails.org/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE.txt)
+
+TjScaleRuby is a Ruby gem that automatically monitors your background job queues — **Delayed Job or Sidekiq** — and your web traffic, and sends metrics to a remote monitoring service for auto-scaling purposes. It integrates seamlessly with Rails applications and Heroku deployments.
+
+## Features
+
+- 🔍 **Automatic Queue Monitoring**: Continuously monitors **Delayed Job or Sidekiq** queues for pending jobs
+- 🔀 **Pluggable Job Backend**: Flip between Delayed Job and Sidekiq with one env var (`TJ_SCALE_JOB_BACKEND`); auto-detected by default
+- 📊 **Metrics Reporting**: Sends job counts, queue latency, and web queue/response times to a remote monitoring service
+- 🚀 **Heroku Integration**: Automatically runs on the first web or worker dyno
+- ⚙️ **Configurable**: Customizable priority/queue filters and API endpoints
+- 🔔 **Slack Notifications** (control plane): message your team whenever web or worker dynos scale up/down, or when scaling fails
+- 🔒 **Error Handling**: Robust error handling with comprehensive logging
+- 🧪 **Well Tested**: Comprehensive test suite with RSpec
+
+## Control plane (Rails + PostgreSQL)
+
+The control plane lives in its own project, **`tj-scale-dashboard`** (a sibling directory / repository to this gem): dashboard, per-app scaling rules (web queue time + worker job counts), metrics ingest API compatible with the gem, Heroku formation updates, and **Slack notifications** for every scale event (Settings → Slack notifications). It uses **PostgreSQL** — see its `README.md` and `.env.example` in `../tj-scale-dashboard/`.
+
+## Installation
+
+### As a Gem
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "tj-scale-ruby", "~> 1.2"
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install tj-scale-ruby
+```
+
+### From Source
+
+1. Clone the repository:
+
+```bash
+git clone https://github.com/untechnickle/tj-scale-ruby.git
+cd tj-scale-ruby
+```
+
+2. Install dependencies:
+
+```bash
+bundle install
+```
+
+3. Run the setup script:
+
+```bash
+bin/setup
+```
+
+## End-to-end guide
+
+Build the gem, publish or reference it, add it to your Rails app, and set configuration (env / Heroku). Follow these steps in order the first time you ship and adopt the gem.
+
+### 1. Prerequisites
+
+- **Ruby** 3.0+ and **Bundler** 2+
+- A **Rails** 6.1+ app with **one job backend**:
+  - **`delayed_job_active_record`** (and a DB-backed `delayed_jobs` table), **or**
+  - **`sidekiq`** (and Redis)
+- **Heroku CLI** (if you deploy to Heroku)
+- A **RubyGems.org** account (if you publish publicly)
+
+### 2. Prepare and build the gem (in this repository)
+
+1. **Track files for the gem package** — the gemspec uses `git ls-files`, so the repo must be a git repository and files must be committed:
+
+   ```bash
+   cd /path/to/tj-scale
+   git init   # if needed
+   git add .
+   git commit -m "Release tj-scale-ruby"
+   ```
+
+2. **Install dependencies and verify quality**:
+
+   ```bash
+   bundle install
+   bundle exec rspec
+   bundle exec rake standard
+   ```
+
+3. **Set the version** in `lib/tj_scale_ruby/version.rb` (for example `1.0.0`).
+
+4. **Build the package**:
+
+   ```bash
+   gem build tj-scale-ruby.gemspec
+   ```
+
+   This produces `tj-scale-ruby-<version>.gem` in the current directory.
+
+### 3. Publish the gem (choose one)
+
+**RubyGems.org (public)**
+
+1. Create an API key at [rubygems.org/api_keys](https://rubygems.org/api_keys).
+2. Push the file you built (version must match `VERSION`):
+
+   ```bash
+   gem push tj-scale-ruby-1.0.0.gem
+   ```
+
+**Private gem host**
+
+```bash
+gem push tj-scale-ruby-1.0.0.gem --host https://your-gem-server.com
+```
+
+Configure Bundler in the app if your host needs authentication (see your provider’s docs).
+
+**Without publishing — use the repo directly**
+
+In the app’s `Gemfile`:
+
+```ruby
+gem "tj-scale-ruby", git: "https://github.com/untechnickle/tj-scale-ruby.git", branch: "main"
+# or path for local development:
+# gem "tj-scale-ruby", path: "../tj-scale"
+```
+
+Then `bundle install`.
+
+### 4. Add the gem to your Rails application
+
+1. Open the app’s **`Gemfile`** and add (adjust version or source as above):
+
+   ```ruby
+   gem "tj-scale-ruby", "~> 1.2"
+   ```
+
+2. Run:
+
+   ```bash
+   bundle install
+   ```
+
+3. **No extra `require`** is needed in `application.rb`: the gem registers a **Rails Railtie** and loads with Rails. Ensure your app already bundles its job backend — **`delayed_job_active_record`** or **`sidekiq`** (the gem auto-detects which one is loaded, or set `TJ_SCALE_JOB_BACKEND` explicitly).
+
+4. Deploy or run the server as usual. The monitoring thread starts only on **`web.1`** or **`worker.1`**, depending on `TJ_SCALE_MONITOR_PROCESS` (see below).
+
+### 5. Configure environment variables
+
+Configuration is **entirely via environment variables** (and Heroku **config vars** in production). Copy [`.env.example`](.env.example) to `.env` for local use if you use **dotenv-rails** or similar.
+
+| Variable | Required | Purpose |
+|----------|----------|---------|
+| `TJ_SCALE_API_TOKEN` | Yes | Sent as **`LOGPLEX_DRAIN_TOKEN`** and **`Authorization: Bearer …`** on each ingest POST. |
+| `TJ_SCALE_API_URL` | Yes | Full URL of the Agent API ingest path: **`POST /api/v1/metrics`** or **`POST /api/v1/sys-logs`** (same handler). Example local: `http://127.0.0.1:5001/api/v1/metrics`. |
+| `TJ_SCALE_TARGET_APP` | No | Heroku app name to scale; defaults to **`HEROKU_APP_NAME`** if unset. |
+| `TJ_SCALE_TARGET_PROCESS` | No | `web` or `worker` to scale; defaults to `TJ_SCALE_MONITOR_PROCESS`. |
+| `TJ_SCALE_MONITOR_PROCESS` | No | `web` or `worker` — only that process’s **`.1`** dyno runs the reporter (default **`worker`**). |
+| `TJ_SCALE_INTERVAL_SECONDS` | No | Seconds between posts (default **20**). |
+| `TJ_SCALE_JOB_BACKEND` | No | Queue backend for the **worker** reporter: `delayed_job`, `sidekiq`, or `auto` (default). `auto` uses Sidekiq when the `sidekiq` gem is loaded, otherwise Delayed Job. |
+| `TJ_SCALE_SIDEKIQ_QUEUES` | No | Sidekiq backend only: comma-separated queue names to count (empty = all queues). |
+| `TJ_MIN_PRIORITY` / `TJ_MAX_PRIORITY` | No | Limit which job priorities are counted (`0` = no filter; **worker** reporter, Delayed Job backend only). |
+| `TJ_SCALE_QUEUE_TIME_MS` | No | When `TJ_SCALE_MONITOR_PROCESS=web`, supplies **`queue_time_ms`** if no middleware snapshot exists. |
+| `TJ_SCALE_ENABLE_QUEUE_TIME_MIDDLEWARE` | No | Set to **`1`**, **`true`**, **`yes`**, or **`on`** to enable Rack middleware that records **`queue_time_ms`** from **`X-Request-Start`** (Heroku). |
+
+**Payload by reporter:** **`web`** — `queue_time_ms` (when known), `job_count` (requests since last tick), optional `response_time_ms`. **`worker`** — `job_count`, `queue_time_s` (oldest waiting job age / queue latency, or **0**), and `job_backend` (`delayed_job` or `sidekiq`). Both send `heroku_app` and `target_process`. Scaling limits (min/max dynos) are configured in the control plane's dashboard settings, not by this gem. Autoscaling runs on the **control plane** after ingest; this gem does not call Heroku.
+
+Heroku sets **`DYNO`** (for example `web.1`, `worker.1`) and typically **`HEROKU_APP_NAME`**; do not set **`DYNO`** manually in production.
+
+**Example: `revize-prod` (web) and `revize-prod-mirror` (workers)**
+
+Use the same token on both apps if one backend handles scaling.
+
+```bash
+# revize-prod — reporter on web.1, scale web dynos
+heroku config:set TJ_SCALE_API_TOKEN=your_token \
+  TJ_SCALE_API_URL=https://your-control-plane.example.com/api/v1/metrics \
+  TJ_SCALE_TARGET_APP=revize-prod \
+  TJ_SCALE_TARGET_PROCESS=web \
+  TJ_SCALE_MONITOR_PROCESS=web \
+  -a revize-prod
+
+# revize-prod-mirror — reporter on worker.1, scale worker dynos
+heroku config:set TJ_SCALE_API_TOKEN=your_token \
+  TJ_SCALE_API_URL=https://your-control-plane.example.com/api/v1/metrics \
+  TJ_SCALE_TARGET_APP=revize-prod-mirror \
+  TJ_SCALE_TARGET_PROCESS=worker \
+  TJ_SCALE_MONITOR_PROCESS=worker \
+  -a revize-prod-mirror
+```
+
+On the **web** app, enable **`TJ_SCALE_ENABLE_QUEUE_TIME_MIDDLEWARE=1`** (and restart) so `queue_time_ms` is populated from Heroku’s router; the web dyno does not need a shared Delayed Job DB for that path.
+
+### 6. Wire your monitoring service (Agent API)
+
+The TJ Scale **Agent API** accepts the same JSON on either route:
+
+- **`POST /api/v1/metrics`**
+- **`POST /api/v1/sys-logs`**
+
+Set **`TJ_SCALE_API_URL`** to the full URL of one of them (for example `http://127.0.0.1:5001/api/v1/metrics` in development). Authenticate with the ingest token using **`LOGPLEX_DRAIN_TOKEN`** or **`Authorization: Bearer`** (same secret as **`TJ_SCALE_API_TOKEN`**); the gem sends **both** headers.
+
+The gem POSTs JSON with **`timestamp`**, **`heroku_app`**, **`target_process`**, plus **web** metrics (`queue_time_ms`, `job_count`, optional `response_time_ms`) or **worker** metrics (`job_count`, `queue_time_s`). Your control plane ingests samples and applies scaling rules (thresholds, cooldowns) when calling the Heroku Platform API.
+
+### 7. Verify
+
+- At least one **web** dyno on `revize-prod` and one **worker** dyno on `revize-prod-mirror` so **`web.1`** and **`worker.1`** exist.
+- Check **Rails logs** for `TjScaleRuby` lines (debug/warn/error).
+- Confirm your API receives periodic requests with the expected payload.
+
+### Optional: manual calls in Ruby
+
+```ruby
+TjScaleRuby::JobMonitor.pending_job_count
+TjScaleRuby::JobMonitor.oldest_pending_queue_seconds
+TjScaleRuby.record_web_queue_time_ms!(42) # optional; middleware does this on each request
+TjScaleRuby::JobMonitor.send_log
+```
+
+## Configuration
+
+### Environment Variables
+
+Create a `.env` file in your project root (or set these in your Heroku config vars):
+
+```bash
+# Required: API token and ingest URL for your control plane
+TJ_SCALE_API_TOKEN=your_api_token_here
+TJ_SCALE_API_URL=http://127.0.0.1:5001/api/v1/metrics
+
+# --- Scaling metadata (sent to your monitoring API; defaults shown) ---
+# Heroku app name to scale (defaults to HEROKU_APP_NAME when unset).
+TJ_SCALE_TARGET_APP=my-heroku-app
+
+# Process type to scale on that app: "web" or "worker" (defaults to TJ_SCALE_MONITOR_PROCESS).
+TJ_SCALE_TARGET_PROCESS=web
+
+# Which process type runs the reporter loop: only the first dyno of this type (web.1 or worker.1).
+# Use "web" on the web app, "worker" on the worker app.
+TJ_SCALE_MONITOR_PROCESS=worker
+
+# Seconds between metric posts (default 20).
+TJ_SCALE_INTERVAL_SECONDS=20
+
+# Optional: Minimum priority filter for jobs (0 = no filter)
+# Only count jobs with priority >= this value
+TJ_MIN_PRIORITY=0
+
+# Optional: Maximum priority filter for jobs (0 = no filter)
+# Only count jobs with priority <= this value
+TJ_MAX_PRIORITY=0
+```
+
+Heroku sets `HEROKU_APP_NAME` for the current app. If you omit `TJ_SCALE_TARGET_APP`, the payload uses that value so each app reports scaling targets for itself.
+
+### Heroku Configuration
+
+Set the environment variables on Heroku:
+
+```bash
+heroku config:set TJ_SCALE_API_TOKEN=your_api_token_here
+heroku config:set TJ_SCALE_API_URL=https://your-control-plane.example.com/api/v1/metrics
+```
+
+The `DYNO` environment variable is automatically set by Heroku and is used to determine which dyno should run the monitoring loop (only `web.1` or `worker.1`, depending on `TJ_SCALE_MONITOR_PROCESS`).
+
+### Example: web on `revize-prod`, workers on `revize-prod-mirror`
+
+Use two Heroku apps (or one app with both process types—same idea). Configure each app’s config vars so the **monitoring service** receives `heroku_app`, `target_process`, and `job_count` on each POST. Scaling bounds (min/max dynos) are set in the control plane's dashboard.
+
+**App `revize-prod` (web dynos)** — run the reporter on the first web dyno and scale `web` dynos:
+
+```bash
+heroku config:set TJ_SCALE_API_TOKEN=your_token -a revize-prod
+heroku config:set TJ_SCALE_MONITOR_PROCESS=web -a revize-prod
+heroku config:set TJ_SCALE_TARGET_APP=revize-prod -a revize-prod
+heroku config:set TJ_SCALE_TARGET_PROCESS=web -a revize-prod
+heroku config:set TJ_SCALE_API_URL=https://your-control-plane.example.com/api/v1/metrics -a revize-prod
+heroku config:set TJ_SCALE_ENABLE_QUEUE_TIME_MIDDLEWARE=1 -a revize-prod
+```
+
+**App `revize-prod-mirror` (worker dynos)** — run the reporter on `worker.1` and scale `worker` dynos:
+
+```bash
+heroku config:set TJ_SCALE_API_TOKEN=your_token -a revize-prod-mirror
+heroku config:set TJ_SCALE_MONITOR_PROCESS=worker -a revize-prod-mirror
+heroku config:set TJ_SCALE_TARGET_APP=revize-prod-mirror -a revize-prod-mirror
+heroku config:set TJ_SCALE_TARGET_PROCESS=worker -a revize-prod-mirror
+heroku config:set TJ_SCALE_API_URL=https://your-control-plane.example.com/api/v1/metrics -a revize-prod-mirror
+```
+
+Ensure both apps have the `web` / `worker` process types in the `Procfile` as needed, deploy, and scale at least one dyno of each monitored type so `web.1` / `worker.1` exist.
+
+**Monitoring API:** Your receiver at `TJ_SCALE_API_URL` should read the JSON body and enforce the min/max dyno bounds from its own dashboard settings when calling the Heroku Platform API (or your own scaler). Fields sent include `job_count`, `timestamp`, and when set, `heroku_app` and `target_process`.
+
+## Usage
+
+### Automatic Monitoring
+
+Once installed and configured, the gem starts monitoring on the first dyno of the configured process type (`web.1` or `worker.1`, see `TJ_SCALE_MONITOR_PROCESS`). The loop runs every `TJ_SCALE_INTERVAL_SECONDS` (default 20) and POSTs metrics to the configured API.
+
+### Manual Usage
+
+You can also use the gem's methods manually in your code:
+
+```ruby
+# Get the count of pending jobs
+count = TjScaleRuby::JobMonitor.pending_job_count
+puts "Pending jobs: #{count}"
+
+# Send current job count to the monitoring service
+response = TjScaleRuby::JobMonitor.send_log
+if response
+  puts "Log sent successfully"
+end
+
+```
+
+### Priority Filtering
+
+You can filter jobs by priority using environment variables:
+
+```ruby
+# Only count jobs with priority between 5 and 10
+ENV['TJ_MIN_PRIORITY'] = '5'
+ENV['TJ_MAX_PRIORITY'] = '10'
+```
+
+## How It Works
+
+1. **Initialization**: When your Rails application starts, the `Railtie` checks if it's running on the first monitored dyno (`web.1` or `worker.1`, per `TJ_SCALE_MONITOR_PROCESS`)
+2. **Background Thread**: If conditions are met, a background thread is started
+3. **Monitoring Loop**: Every N seconds (`TJ_SCALE_INTERVAL_SECONDS`), the thread POSTs a payload: on **worker** reporters it counts waiting jobs on the active backend; on **web** reporters it sends router queue time (middleware / env) plus request volume and average response time for the interval.
+4. **Job counting (worker reporters, Delayed Job backend)**: `pending_job_count` filters jobs based on:
+   - Jobs past their `run_at` time (with 5 second buffer)
+   - Jobs that haven't failed (`failed_at IS NULL`)
+   - Jobs that aren't locked (`locked_at IS NULL`)
+   - Optional priority range filters
+5. **Job counting (worker reporters, Sidekiq backend)**: `pending_job_count` sums enqueued jobs across queues (all queues, or only those in `TJ_SCALE_SIDEKIQ_QUEUES`), and `queue_time_s` is the latency of the slowest monitored queue.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+### Running Tests
+
+```bash
+# Run all tests
+bundle exec rspec
+
+# Run tests with documentation format
+bundle exec rspec --format documentation
+
+# Run a specific test file
+bundle exec rspec spec/lib/tj_scale_ruby/models/tj_scale_ruby_spec.rb
+```
+
+### Code Quality
+
+The project uses [Standard](https://github.com/testdouble/standard) for code formatting:
+
+```bash
+# Check code style
+bundle exec rake standard
+
+# Auto-fix code style issues
+bundle exec rake standard:fix
+```
+
+## Building and Publishing the Gem
+
+For a full checklist (git, tests, version, integrate in the app, Heroku), see **[End-to-end guide](#end-to-end-guide)** above.
+
+### Building the Gem
+
+1. Update the version in `lib/tj_scale_ruby/version.rb`
+2. Ensure files are tracked by git (the gemspec uses `git ls-files`).
+3. Build the gem:
+
+```bash
+gem build tj-scale-ruby.gemspec
+```
+
+This will create a `.gem` file in the current directory.
+
+### Publishing to RubyGems
+
+1. Make sure you have a RubyGems account
+2. Get your API key from https://rubygems.org/api_keys
+3. Configure your credentials:
+
+```bash
+gem push --key your_api_key tj-scale-ruby-1.0.0.gem
+```
+
+Or use the credentials file:
+
+```bash
+# Create ~/.gem/credentials
+# Add your API key:
+# ---
+# :rubygems_api_key: your_api_key_here
+
+gem push tj-scale-ruby-1.0.0.gem
+```
+
+### Publishing to a Private Gem Server
+
+If you're using a private gem server:
+
+```bash
+gem push tj-scale-ruby-1.0.0.gem --host https://your-gem-server.com
+```
+
+## Deployment
+
+### Heroku Deployment
+
+1. Add the gem to your `Gemfile`:
+
+```ruby
+gem "tj-scale-ruby", "~> 1.2"
+```
+
+2. Set the required environment variables:
+
+```bash
+heroku config:set TJ_SCALE_API_TOKEN=your_token
+```
+
+3. Deploy your application:
+
+```bash
+git push heroku main
+```
+
+The gem will automatically start monitoring on the first worker dyno.
+
+### Docker Deployment
+
+1. Add the gem to your `Gemfile`
+2. Set environment variables in your Docker configuration
+3. The gem will automatically start when the Rails application initializes
+
+### Other Platforms
+
+The gem works with any Rails application. Just ensure:
+- Delayed Job or Sidekiq is configured
+- Environment variables are set
+- The application has worker dynos (for automatic monitoring)
+
+## Requirements
+
+- Ruby >= 3.0.0
+- Rails >= 6.1
+- One job backend (worker reporters only; bring your own gem):
+  - delayed_job_active_record >= 4.1 and PostgreSQL, **or**
+  - sidekiq and Redis
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/untechnickle/tj-scale-ruby.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Add tests for your changes
+5. Ensure all tests pass (`bundle exec rspec`)
+6. Ensure code style is correct (`bundle exec rake standard`)
+7. Commit your changes (`git commit -am 'Add some amazing feature'`)
+8. Push to the branch (`git push origin feature/amazing-feature`)
+9. Open a Pull Request
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for a list of changes and version history.
+
+## Support
+
+For issues, questions, or contributions, please open an issue on the [GitHub repository](https://github.com/untechnickle/tj-scale-ruby/issues).
+
+## Authors
+
+- **Tanuj** - *Initial work* - [tanuj@untechnickle.com](mailto:tanuj@untechnickle.com)
+
+## Acknowledgments
+
+- Built for Untechnickle
+- Works with [Delayed Job](https://github.com/collectiveidea/delayed_job) and [Sidekiq](https://github.com/sidekiq/sidekiq) for background job processing
+

data/lib/tj-scale.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+# Railties expect ActiveSupport core extensions (e.g. `delegate_missing_to`) before load.
+require "active_support/core_ext/module/delegation"
+require "rails/railtie"
+require "tj_scale_ruby/configuration"
+require "tj_scale_ruby/models/tj_scale_ruby"
+
+# ## How this gem participates in autoscaling
+#
+# TJ Scale (the control plane) scales Heroku formation when ingested metrics cross rules
+# you configure there. This gem only **reports signals**; it never calls Heroku directly.
+#
+# **Where it runs:** A single background thread on **one** dyno — the first dyno of the
+# process you choose (`web.1` or `worker.1` via +TJ_SCALE_MONITOR_PROCESS+). Heroku sets +DYNO+.
+#
+# **What it sends:** On each tick (+TJ_SCALE_INTERVAL_SECONDS+), it POSTs JSON to
+# +TJ_SCALE_API_URL+ (e.g. +/api/v1/metrics+ or +/api/v1/sys-logs+ — same handler on the
+# platform) with +LOGPLEX_DRAIN_TOKEN+ and +Authorization: Bearer+ set from +TJ_SCALE_API_TOKEN+.
+# Payload always
+# includes +heroku_app+ and +target_process+; scaling limits (min/max dynos) live in the
+# control plane's settings, not in this gem.
+#
+# - **Worker monitor** (+TJ_SCALE_MONITOR_PROCESS=worker+): counts waiting jobs
+#   (+job_count+, +queue_time_s+) on the configured queue backend — **Delayed Job** or **Sidekiq**,
+#   toggled with +TJ_SCALE_JOB_BACKEND+ (+delayed_job+ / +sidekiq+ / +auto+, the default, which
+#   prefers Sidekiq when loaded). Delayed Job needs +delayed_job_active_record+ and a shared DB;
+#   Sidekiq needs the +sidekiq+ gem and Redis (+TJ_SCALE_SIDEKIQ_QUEUES+ limits counted queues).
+# - **Web monitor** (+TJ_SCALE_MONITOR_PROCESS=web+): sends +queue_time_ms+ from Rack middleware
+#   (router queue via +X-Request-Start+) when +TJ_SCALE_ENABLE_QUEUE_TIME_MIDDLEWARE=1+, plus
+#   request volume and average +response_time_ms+ for the tick. Without middleware, set
+#   +TJ_SCALE_QUEUE_TIME_MS+ or the platform will not scale on queue time until data exists.
+#
+# **Platform side:** You create a monitored app, set thresholds (e.g. upscale above N jobs or ms),
+# and supply a Heroku API token there. Scaling runs in jobs after each accepted ingest.
+#
+# Main entry point for TjScaleRuby gem
+module TjScaleRuby
+  # Rails integration: optional Rack middleware (web queue timing) + metrics loop on +web.1+ / +worker.1+.
+  class Railtie < Rails::Railtie
+    initializer "tj_scale_ruby.rack_queue_time_middleware" do |app|
+      flag = ENV.fetch("TJ_SCALE_ENABLE_QUEUE_TIME_MIDDLEWARE", "").to_s.strip.downcase
+      next unless %w[1 true yes on].include?(flag)
+
+      require "tj_scale_ruby/rack_queue_time_middleware"
+      app.middleware.insert(0, RackQueueTimeMiddleware)
+    end
+
+    config.after_initialize do
+      TjScaleRuby.start_monitoring_loop!
+    end
+  end
+
+  # Starts a background thread on the designated first dyno (see {#monitor_on_this_dyno?}).
+  def self.start_monitoring_loop!
+    return unless monitor_on_this_dyno?
+
+    interval = configuration.interval_seconds
+    Thread.new do
+      loop do
+        begin
+          JobMonitor.send_log
+        rescue StandardError => e
+          Rails.logger.error("TjScaleRuby: Error in monitoring loop: #{e.message}")
+        end
+
+        sleep(interval)
+      end
+    end
+  end
+
+  # True when this dyno should run the metrics loop (first of TJ_SCALE_MONITOR_PROCESS).
+  # Result is memoized; cleared by {.reset_configuration!}.
+  def self.monitor_on_this_dyno?
+    return @monitor_on_this_dyno if defined?(@monitor_on_this_dyno)
+
+    dyno = ENV["DYNO"]
+    @monitor_on_this_dyno = if dyno.nil? || dyno.empty?
+      false
+    else
+      parts = dyno.split(".", 2)
+      if parts.size != 2
+        false
+      else
+        process, index = parts
+        process == configuration.monitor_process && index.to_i == 1
+      end
+    end
+  end
+
+  def self.clear_monitoring_memo!
+    remove_instance_variable(:@monitor_on_this_dyno) if defined?(@monitor_on_this_dyno)
+  end
+end

data/lib/tj_scale_ruby/configuration.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module TjScaleRuby
+  # Reads Heroku / scaling settings from environment variables.
+  class Configuration
+    DEFAULT_INTERVAL_SECONDS = 20
+    JOB_BACKENDS = %w[auto delayed_job sidekiq].freeze
+
+    attr_reader :monitor_process, :interval_seconds,
+      :min_priority, :max_priority, :job_backend, :sidekiq_queues
+
+    def initialize(env = ENV)
+      @monitor_process = normalize_process(env["TJ_SCALE_MONITOR_PROCESS"]) || "worker"
+      @job_backend = normalize_job_backend(env["TJ_SCALE_JOB_BACKEND"])
+      @sidekiq_queues = parse_list(env["TJ_SCALE_SIDEKIQ_QUEUES"])
+      @interval_seconds = parse_positive_int(env["TJ_SCALE_INTERVAL_SECONDS"], DEFAULT_INTERVAL_SECONDS)
+      @target_app = nonempty_string(env["TJ_SCALE_TARGET_APP"])
+      @heroku_app_name = nonempty_string(env["HEROKU_APP_NAME"])
+      @target_process = normalize_process(env["TJ_SCALE_TARGET_PROCESS"]) || @monitor_process
+      @min_priority = env["TJ_MIN_PRIORITY"].to_i
+      @max_priority = env["TJ_MAX_PRIORITY"].to_i
+    end
+
+    # Heroku app name the scaler should act on (defaults to HEROKU_APP_NAME when unset).
+    def target_app
+      @target_app || @heroku_app_name
+    end
+
+    # Process type to scale on that app: "web" or "worker".
+    def target_process
+      @target_process
+    end
+
+    private
+
+    def normalize_process(value)
+      p = value.to_s.strip.downcase
+      return nil if p.empty?
+
+      %w[web worker].include?(p) ? p : nil
+    end
+
+    # "delayed_job" | "sidekiq" | "auto" (default; detects from loaded gems).
+    def normalize_job_backend(value)
+      b = value.to_s.strip.downcase
+      JOB_BACKENDS.include?(b) ? b : "auto"
+    end
+
+    def parse_list(value)
+      value.to_s.split(",").map(&:strip).reject(&:empty?)
+    end
+
+    def parse_positive_int(raw, default)
+      n = raw.to_i
+      n.positive? ? n : default
+    end
+
+    def nonempty_string(value)
+      s = value.to_s.strip
+      s.empty? ? nil : s
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configuration=(config)
+      @configuration = config
+    end
+
+    def reset_configuration!
+      @configuration = nil
+      TjScaleRuby.clear_monitoring_memo!
+      TjScaleRuby.clear_web_queue_time_snapshot!
+      TjScaleRuby.clear_web_traffic_stats!
+    end
+
+    # Latest web router queue time (ms) captured by {RackQueueTimeMiddleware}; thread-safe.
+    def record_web_queue_time_ms!(ms)
+      v = Integer(ms)
+      return if v.negative?
+
+      web_queue_mutex.synchronize { @web_queue_time_ms = v }
+    rescue ArgumentError, TypeError
+      nil
+    end
+
+    def last_web_queue_time_ms
+      web_queue_mutex.synchronize { @web_queue_time_ms }
+    end
+
+    def clear_web_queue_time_snapshot!
+      web_queue_mutex.synchronize { @web_queue_time_ms = nil }
+    end
+
+    # Request volume + response time for +web+ metrics (flushed each ingest tick).
+    def record_web_request_finished!(duration_ms)
+      v = Integer(duration_ms)
+      return if v.negative?
+
+      web_traffic_mutex.synchronize do
+        @web_request_count = (@web_request_count || 0) + 1
+        @web_response_time_sum_ms = (@web_response_time_sum_ms || 0) + v
+      end
+    rescue ArgumentError, TypeError
+      nil
+    end
+
+    # @return [Hash] +:job_count+ requests since last flush; +:response_time_ms+ average ms or +nil+
+    def flush_web_traffic_stats_for_payload!
+      web_traffic_mutex.synchronize do
+        c = @web_request_count || 0
+        sum = @web_response_time_sum_ms || 0
+        @web_request_count = 0
+        @web_response_time_sum_ms = 0
+        avg = c.positive? ? (sum.to_f / c).round : nil
+        { job_count: c, response_time_ms: avg }
+      end
+    end
+
+    def clear_web_traffic_stats!
+      web_traffic_mutex.synchronize do
+        @web_request_count = 0
+        @web_response_time_sum_ms = 0
+      end
+    end
+
+    def web_queue_mutex
+      @web_queue_mutex ||= Mutex.new
+    end
+    private :web_queue_mutex
+
+    def web_traffic_mutex
+      @web_traffic_mutex ||= Mutex.new
+    end
+    private :web_traffic_mutex
+  end
+end

data/lib/tj_scale_ruby/job_backends/delayed_job.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module TjScaleRuby
+  module JobBackends
+    # Counts runnable +Delayed::Job+ rows in the shared database.
+    # Requires the host app to bundle +delayed_job_active_record+.
+    class DelayedJob
+      class << self
+        def backend_name
+          "delayed_job"
+        end
+
+        # Relation for runnable Delayed::Job rows (priority filters applied).
+        def pending_jobs_relation(now = Time.zone.now)
+          ensure_loaded!
+          min_priority = TjScaleRuby.configuration.min_priority
+          max_priority = TjScaleRuby.configuration.max_priority
+
+          query = ::Delayed::Job.where("run_at + interval '5 seconds' < ?", now)
+          query = query.where("failed_at IS NULL")
+          query = query.where("locked_at IS NULL")
+          query = query.where("priority >= ?", min_priority) unless min_priority.zero?
+          query = query.where("priority <= ?", max_priority) unless max_priority.zero?
+
+          query
+        end
+
+        def pending_job_count(now = Time.zone.now)
+          pending_jobs_relation(now).count
+        end
+
+        # Approximate age in seconds of the oldest runnable job (+run_at+ vs +now+). Zero if none.
+        def oldest_pending_queue_seconds(now = Time.zone.now)
+          oldest = pending_jobs_relation(now).minimum(:run_at)
+          return 0 if oldest.nil?
+
+          [(now - oldest).to_f.ceil, 0].max
+        end
+
+        private
+
+        def ensure_loaded!
+          return if defined?(::Delayed::Job)
+
+          require "delayed/backend/active_record"
+        end
+      end
+    end
+  end
+end

data/lib/tj_scale_ruby/job_backends/sidekiq.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module TjScaleRuby
+  module JobBackends
+    # Reads queue depth and latency from the Sidekiq API (Redis).
+    # Requires the host app to bundle +sidekiq+; priority filters do not apply —
+    # use +TJ_SCALE_SIDEKIQ_QUEUES+ to limit which queues are counted.
+    class Sidekiq
+      class << self
+        def backend_name
+          "sidekiq"
+        end
+
+        def pending_job_count(_now = nil)
+          ensure_loaded!
+          queues.sum(&:size)
+        end
+
+        # Latency (seconds since the oldest enqueued job) of the slowest monitored queue.
+        def oldest_pending_queue_seconds(_now = nil)
+          ensure_loaded!
+          latency = queues.map(&:latency).max
+          latency.nil? ? 0 : latency.ceil
+        end
+
+        private
+
+        def queues
+          names = TjScaleRuby.configuration.sidekiq_queues
+          return ::Sidekiq::Queue.all if names.empty?
+
+          names.map { |name| ::Sidekiq::Queue.new(name) }
+        end
+
+        def ensure_loaded!
+          return if defined?(::Sidekiq::Queue)
+
+          require "sidekiq/api"
+        end
+      end
+    end
+  end
+end

data/lib/tj_scale_ruby/job_backends.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "tj_scale_ruby/job_backends/delayed_job"
+require "tj_scale_ruby/job_backends/sidekiq"
+
+module TjScaleRuby
+  # Pluggable queue backends for worker metrics. Selected with
+  # +TJ_SCALE_JOB_BACKEND+ (+delayed_job+, +sidekiq+, or +auto+ — the default).
+  # +auto+ prefers Sidekiq when the host app has it loaded, else Delayed Job.
+  module JobBackends
+    def self.current
+      resolve(TjScaleRuby.configuration.job_backend)
+    end
+
+    def self.resolve(name)
+      case name.to_s
+      when "sidekiq" then Sidekiq
+      when "delayed_job" then DelayedJob
+      else detect
+      end
+    end
+
+    def self.detect
+      defined?(::Sidekiq) ? Sidekiq : DelayedJob
+    end
+  end
+end

data/lib/tj_scale_ruby/models/tj_scale_ruby.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "net/http"
+require "uri"
+require "json"
+require "tj_scale_ruby/job_backends"
+
+module TjScaleRuby
+  # Posts metrics to your TJ Scale (or compatible) ingest URL. Scaling decisions happen on the server.
+  class JobMonitor
+    class << self
+      # Active queue backend (Delayed Job or Sidekiq) per +TJ_SCALE_JOB_BACKEND+.
+      def backend
+        JobBackends.current
+      end
+
+      # Relation for runnable Delayed::Job rows (Delayed Job backend only; kept for manual use).
+      def pending_jobs_relation(now = Time.zone.now)
+        JobBackends::DelayedJob.pending_jobs_relation(now)
+      end
+
+      # Counts jobs waiting to run on the active backend (DJ: runnable rows with priority
+      # filters; Sidekiq: enqueued jobs across monitored queues).
+      def pending_job_count(now = Time.zone.now)
+        backend.pending_job_count(now)
+      rescue StandardError => e
+        Rails.logger.error("TjScaleRuby: Error counting pending jobs: #{e.message}")
+        0
+      end
+
+      # Age in seconds of the oldest waiting job (DJ: +run_at+ vs +now+; Sidekiq: queue latency).
+      def oldest_pending_queue_seconds(now = Time.zone.now)
+        backend.oldest_pending_queue_seconds(now)
+      rescue StandardError => e
+        Rails.logger.error("TjScaleRuby: Error computing queue_time_s: #{e.message}")
+        0
+      end
+
+      def send_log
+        token = ENV["TJ_SCALE_API_TOKEN"]
+        unless token
+          Rails.logger.warn("TjScaleRuby: TJ_SCALE_API_TOKEN not configured")
+          return false
+        end
+
+        api_url = ENV["TJ_SCALE_API_URL"].to_s.strip
+        if api_url.empty?
+          Rails.logger.warn("TjScaleRuby: TJ_SCALE_API_URL not configured")
+          return false
+        end
+
+        now = Time.zone.now
+        cfg = TjScaleRuby.configuration
+        payload = build_log_payload(now)
+
+        response = http_post(URI.parse(api_url), body: payload.compact.to_json, token: token)
+
+        if response.is_a?(Net::HTTPSuccess)
+          if cfg.monitor_process == "web"
+            Rails.logger.debug do
+              "TjScaleRuby: Sent web metrics queue_time_ms=#{payload[:queue_time_ms].inspect}"
+            end
+          else
+            Rails.logger.debug do
+              "TjScaleRuby: Sent worker metrics job_count=#{payload[:job_count]} " \
+                "queue_time_s=#{payload[:queue_time_s]}"
+            end
+          end
+        else
+          Rails.logger.warn("TjScaleRuby: API returned #{response.code}: #{response.message}")
+        end
+
+        response
+      rescue StandardError => e
+        Rails.logger.error("TjScaleRuby: Error sending log: #{e.message}")
+        false
+      end
+
+      private
+
+      def web_queue_time_ms_for_payload
+        snap = TjScaleRuby.last_web_queue_time_ms
+        return snap unless snap.nil?
+
+        env = ENV["TJ_SCALE_QUEUE_TIME_MS"]
+        return nil if env.blank?
+
+        env.to_i
+      end
+
+      def build_log_payload(now)
+        cfg = TjScaleRuby.configuration
+        base = {
+          timestamp: now.iso8601,
+          heroku_app: cfg.target_app,
+          target_process: cfg.target_process
+        }
+
+        if cfg.monitor_process == "web"
+          payload = base.dup
+          qms = web_queue_time_ms_for_payload
+          payload[:queue_time_ms] = qms unless qms.nil?
+          traffic = TjScaleRuby.flush_web_traffic_stats_for_payload!
+          payload[:job_count] = traffic[:job_count]
+          payload[:response_time_ms] = traffic[:response_time_ms] if traffic[:response_time_ms]
+          payload
+        else
+          job_count = pending_job_count(now)
+          queue_time_s = oldest_pending_queue_seconds(now)
+          base.merge(job_count: job_count, queue_time_s: queue_time_s, job_backend: backend.backend_name)
+        end
+      end
+
+      def http_post(uri, body:, token:)
+        Net::HTTP.start(
+          uri.host,
+          uri.port,
+          use_ssl: uri.scheme == "https",
+          read_timeout: 10,
+          open_timeout: 10
+        ) do |http|
+          request = Net::HTTP::Post.new(uri)
+          request["Content-Type"] = "application/json"
+          request["Accept"] = "application/vnd.heroku+json; version=3"
+          request["LOGPLEX_DRAIN_TOKEN"] = token
+          request["Authorization"] = "Bearer #{token}"
+          request.body = body if body
+          http.request(request)
+        end
+      end
+    end
+  end
+end

data/lib/tj_scale_ruby/rack_queue_time_middleware.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module TjScaleRuby
+  # Records approximate router queue wait from {Heroku's X-Request-Start}[https://devcenter.heroku.com/articles/http-routing#request-queueing]
+  # so +web.1+ metrics can send +queue_time_ms+ without relying on a static ENV value.
+  #
+  # Enable with +TJ_SCALE_ENABLE_QUEUE_TIME_MIDDLEWARE=1+ (see Railtie).
+  class RackQueueTimeMiddleware
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_millisecond)
+      ms = self.class.queue_wait_ms(env)
+      TjScaleRuby.record_web_queue_time_ms!(ms) unless ms.nil?
+      status, headers, body = @app.call(env)
+      elapsed = (Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_millisecond) - t0).round
+      TjScaleRuby.record_web_request_finished!(elapsed)
+      [status, headers, body]
+    end
+
+    # @return [Integer, nil] milliseconds since request entered the router, or nil if header missing/invalid
+    def self.queue_wait_ms(env)
+      start_ms = request_start_epoch_ms(env)
+      return nil unless start_ms
+
+      now_ms = (Time.now.utc.to_f * 1000).round
+      [now_ms - start_ms, 0].max
+    end
+
+    def self.request_start_epoch_ms(env)
+      raw = env["HTTP_X_REQUEST_START"]
+      return nil if raw.nil? || raw.strip.empty?
+
+      m = raw.to_s.match(/t=(\d+(?:\.\d+)?)/i)
+      return nil unless m
+
+      v = m[1].to_f
+      v *= 1000 if v < 1_000_000_000_000 # seconds (or fractional) -> ms
+      v.round
+    end
+    private_class_method :request_start_epoch_ms
+  end
+end

data/lib/tj_scale_ruby/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Version module for TjScaleRuby gem
+module TjScaleRuby
+  VERSION = "1.0.0"
+end

metadata

@@ -0,0 +1,209 @@
+--- !ruby/object:Gem::Specification
+name: tj-scale
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Tanuj
+bindir: exe
+cert_chain: []
+date: 2026-06-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+- !ruby/object:Gem::Dependency
+  name: openssl
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+- !ruby/object:Gem::Dependency
+  name: delayed_job_active_record
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.1'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+description: |
+  TjScaleRuby reports metrics from your Rails app to an TJ Scale (or compatible)
+  control plane so it can autoscale Heroku formation from rules you configure there.
+
+  Behavior at a glance:
+  - Runs a background loop on exactly one dyno: web.1 or worker.1 (configurable).
+  - Worker reporter: waiting job count and oldest-job age (queue_time_s) from Delayed Job
+    or Sidekiq — pick with TJ_SCALE_JOB_BACKEND (auto-detected by default).
+  - Web reporter: router queue_time_ms (Rack middleware + X-Request-Start), request volume,
+    and average response time per reporting interval.
+  - Sends target Heroku app and process type on every POST; scaling limits
+    (min/max dynos) are configured in the control plane's dashboard settings.
+  - Configure with environment variables; no Rails initializer required.
+
+  Requires Rails 6.1+ and Ruby 3.0+. Bring your own queue gem: delayed_job_active_record
+  or sidekiq (worker reporters only).
+email:
+- tanuj@untechnickle.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/tj-scale.rb
+- lib/tj_scale_ruby/configuration.rb
+- lib/tj_scale_ruby/job_backends.rb
+- lib/tj_scale_ruby/job_backends/delayed_job.rb
+- lib/tj_scale_ruby/job_backends/sidekiq.rb
+- lib/tj_scale_ruby/models/tj_scale_ruby.rb
+- lib/tj_scale_ruby/rack_queue_time_middleware.rb
+- lib/tj_scale_ruby/version.rb
+homepage: https://github.com/Untechnickle/tj-scale-gem
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/Untechnickle/tj-scale-gem
+  changelog_uri: https://github.com/Untechnickle/tj-scale-gem/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/Untechnickle/tj-scale-gem/issues
+  documentation_uri: https://github.com/Untechnickle/tj-scale-gem#readme
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: 'Rails gem: Delayed Job / Sidekiq queue metrics for Heroku auto-scaling (web
+  or worker dynos)'
+test_files: []