RightSignals Docs

RightSignals is a standards-first error tracking and trace-debugging product. The reporting side is intentionally open; the product value sits in grouping, correlation, workflow, and the operator UI.

RightSignals is OpenTelemetry-native. No proprietary SDK is required or published — not for Ruby, not Crystal, not any language. The "SDK" is the official OpenTelemetry library for your language. Add the OTel gems, point the OTLP exporter at this host with a bearer token, and you are reporting in minutes — not days. Agents: see /llms.txt.

Concepts: Trace, Occurrence, Issue

Three core nouns, each mapped to OpenTelemetry. The supporting nouns hang off them.

Two keys, two questions. A trace_id is which request (shared by every span in one request); a fingerprint is which bug — a hash of exception type + normalized stack frames, shared across requests. A trace has no fingerprint; an occurrence has both. Example: six real occurrences of one RuntimeError share one fingerprint so they collapse into a single Issue — but each has a different trace_id (six separate requests). The same fingerprint groups them; the differing trace_ids do not.

Hierarchy: Trace → Spans → (a span's exception) → Occurrence → grouped by fingerprint → Issue.

One analogy: the Trace is the flight recorder of one journey; an Occurrence is one alarm that went off; an Issue is "this alarm keeps going off."

• Span — one operation within a trace.
• Log / Event — a timestamped OTLP log record; an "event" is a log record with an event.name. Not always an error (capturing occurrences from error logs is planned).
• Release — a deployed service.version; occurrences and issues are tagged with the release they appeared in.
• Environment — deployment.environment.name (staging / production); a dimension across every signal.

Key Model Tradeoffs

Telemetry submission and private account automation have different blast radii. RightSignals treats those as separate keys on purpose.

Open Vs Proprietary

RightSignals does not currently ship a proprietary reporting SDK, a proprietary wire protocol, or a proprietary collector agent. The proprietary layer is the product behavior above telemetry transport.

Ruby On Rails Quick Start

RightSignals uses standard OpenTelemetry gems instead of a proprietary reporting gem. This means slightly more setup up front, but your instrumentation stays portable across vendors.

1. 1. Add the OpenTelemetry gems

   Use the Ruby metapackage for the fastest first pass, or swap in the narrower opentelemetry-instrumentation-rails gem if you want tighter control.

   gem "opentelemetry-sdk"
   gem "opentelemetry-exporter-otlp"
   gem "opentelemetry-instrumentation-all"
   

2. 2. Add a Rails initializer

   Put this in config/initializers/opentelemetry.rb so Rails configures tracing on boot.

   # config/initializers/opentelemetry.rb
   require "opentelemetry/sdk"
   require "opentelemetry/instrumentation/all"
   require "opentelemetry-exporter-otlp"
   
   OpenTelemetry::SDK.configure do |c|
     c.service_name = ENV.fetch("OTEL_SERVICE_NAME", "your-app")
     c.resource = OpenTelemetry::SDK::Resources::Resource.create(
       "service.version"             => ENV.fetch("HEROKU_SLUG_COMMIT", "unknown"),
       "deployment.environment.name" => ENV.fetch("RAILS_ENV", "production")
     )
     c.use_all
   end
   

   service.version is set in code from the runtime build variable (e.g. HEROKU_SLUG_COMMIT on Heroku). Do NOT use OTEL_RESOURCE_ATTRIBUTES for this — that env var does not expand $VARS , so the literal string would be sent instead of the actual commit SHA.

3. 3. Set the exporter env vars

   These tell the OTLP exporter where to send data and authenticate with the project's reporter key. Get your reporter key from the project settings page after signing in. Use a literal space after Bearer — do not URL-encode it as %20.

   OTEL_EXPORTER_OTLP_ENDPOINT=https://app.rightsignals.com
   OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer YOUR_REPORTER_KEY
   OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
   OTEL_SERVICE_NAME=your-app
   

   The reporter key ( rsp_… ) is per-project and publishable — safe to set in CI config or a collector. If it leaks, the risk is spammy telemetry only. service.version and deployment.environment.name are set from HEROKU_SLUG_COMMIT and RAILS_ENV in the initializer above, so they don't need separate env vars.

4. 4. Deploy and generate traffic

   After deploy, load a few Rails pages, run a background job, or trigger an exception path. Your service should appear in the RightSignals dashboard within seconds.

How it compares

Recording Custom Errors As Issues

Unhandled exceptions in instrumented code paths (controller actions, background jobs) are captured automatically. But when you rescue an error and want RightSignals to still track it as an issue, you need to tell OpenTelemetry about it explicitly.

tracer = OpenTelemetry.tracer_provider.tracer("myapp.external")

tracer.in_span("model.unavailable", attributes: {
  "model.name"   => "gemini-3.1-flash",
  "model.status" => "429",
  "model.detail" => "Quota exceeded for free tier"
}) do |span|
  # Mark the span as errored — shows red in trace views
  span.status = OpenTelemetry::Trace::Status.error("Model unavailable: gemini-3.1-flash (429)")

  # Record an exception event — this is what creates a RightSignals issue
  span.record_exception(RuntimeError.new("Model unavailable: gemini-3.1-flash (429)"))
end

Why both calls?

CLI

The RightSignals CLI lets you query issues, traces, occurrences, and events from your terminal.

brew install aluminumio/tap/rightsignals
export RIGHTSIGNALS_TOKEN=rsg_...   # from Setup page

Add -j for JSON output, -e ENV to filter by environment, --service=NAME to filter by service.

Claude Code Skill

Add this skill to your Claude Code setup so it can find and fix production exceptions automatically. Create the file ~/.claude/skills/rightsignals-debug/SKILL.md with the contents below.

---
name: rightsignals-debug
description: Use when debugging production exceptions, finding errors in an application, or when the user wants to see what's broken in production.
user-invocable: true
argument-hint: [--status=open] [issue-id]
allowed-tools: Bash, Read, Edit, Glob, Grep
---

Find and fix production exceptions using the RightSignals CLI.

## Setup

```bash
brew install aluminumio/tap/rightsignals
export RIGHTSIGNALS_TOKEN=rsg_...
```

## Workflow

### 1. Find open issues
```bash
rightsignals issues --status=open
```
Prioritize high-count or recently-seen issues.

### 2. Get the stack trace
```bash
rightsignals issues <id>
```
The top application frame (not gems/libraries) is usually the fix site.

### 3. Find the source code
Use the stack trace file and line number to locate the code in the codebase.

### 4. Check the request trace (optional)
```bash
rightsignals traces <trace-id>
```

### 5. Fix and verify
Apply the fix and run specs.

### 6. Resolve
```bash
rightsignals issues:resolve <id>
```
RightSignals auto-reopens if the issue regresses.

Once installed, use /rightsignals-debug or ask Claude "what's broken in production?" and it will use the CLI to find and fix issues.