OtelBeacon

Sentry-style error tracking and context for OpenTelemetry. Get the familiar Sentry developer experience (breadcrumbs, user context, tags, fingerprinting) with any OpenTelemetry backend like SigNoz, Jaeger, Honeycomb, or Grafana Tempo.

Installation

Add to your Gemfile:

gem 'otel_beacon'

Quick Start

OtelBeacon.service_name = "my-app"
OtelBeacon.service_version = "1.0.0"
OtelBeacon.environment = Rails.env
OtelBeacon.current_user_method = :current_user

User detection supports multiple formats:

• Symbol: :current_user (calls method on controller)
• String: "Current.user" (for CurrentAttributes)
• Proc: -> (ctx) { ctx.session[:user] } (custom logic)

Usage

User Context

OtelBeacon.set_user(
  id: user.id,
  email: user.email,
  username: user.name,
  subscription: "premium"
)

Custom attributes beyond id/email/username are also supported.

Tags

OtelBeacon.set_tags(
  feature: "checkout",
  priority: "high",
  release: "1.2.3"
)

Extra Data

OtelBeacon.set_extra(
  cart_id: 123,
  items_count: 5,
  total_amount: 99.99
)

Breadcrumbs

OtelBeacon.add_breadcrumb(:http, "GET /api/users", status: 200, duration: 150)
OtelBeacon.add_breadcrumb(:user_action, "Clicked checkout button")
OtelBeacon.add_breadcrumb(:navigation, "Navigated to /checkout")

Structured Contexts

OtelBeacon.set_context(:payment, provider: "stripe", amount: 99.99)
OtelBeacon.set_context(:feature_flags, dark_mode: true, beta: false)

Fingerprinting (Error Grouping)

OtelBeacon.set_fingerprint("payment", "stripe", "card-declined")

Scoped Context

OtelBeacon.with_scope do |scope|
  scope.set_tags(feature: "checkout")
  scope.set_extra(cart_id: 123)
  scope.set_fingerprint("checkout", "payment-error")
  process_checkout
end

Any exception within the block gets the scoped context. Context is automatically restored after the block.

Manual Exception Capture

begin
  risky_operation
rescue => e
  OtelBeacon.capture_exception(e,
    extra: { operation: "payment" },
    fingerprint: ["payment", "timeout"]
  )
  raise
end

Custom Spans

OtelBeacon.in_span("payment.process", attributes: { "payment.provider" => "stripe" }) do |span|
  result = process_payment
  span.add_event("payment.complete", attributes: { "payment.id" => result.id })
end

Message Capture

OtelBeacon.capture_message("User completed onboarding", level: :info, tags: { flow: "signup" })

Rails Integration

OtelBeacon automatically integrates with Rails when the Railtie loads:

• Controllers: Auto-captures user, request context, and exceptions
• Jobs: Auto-captures job metadata and exceptions
• Mailers: Auto-captures mailer context and exceptions

Configuration

User detection:

OtelBeacon.current_user_method = :current_user
OtelBeacon.user_attributes = {
  id: :id,
  email: :email,
  username: %i[username name]
}

The user_attributes mapping tries each method in order until one returns a value.

Sanitization:

OtelBeacon.sanitize_fields = %w[password token secret key auth credential api_key access_token]

Limits:

OtelBeacon.max_breadcrumbs = 50
OtelBeacon.max_stacktrace_lines = 20

Hooks:

OtelBeacon.before_capture = ->(event) { ... }
OtelBeacon.before_breadcrumb = ->(crumb) { ... }

Sidekiq Integration

Automatically enabled when Sidekiq is present. For each job, OtelBeacon sets:

• Tags: job_class, queue, job_id
• Context (:sidekiq): queue, retry_count, created_at, enqueued_at
• On exceptions: filtered job arguments are captured

Runtime Context

Automatically captured at startup:

• :runtime - Ruby version, platform, engine, engine_version
• :os - OS name, version, kernel_version
• :app - Service name, version, environment, Rails version (if Rails)

Captured per request (in controllers):

• :device - User agent, IP address
• :browser - Browser name/version (parsed from user agent)

Comparison with Sentry

Feature	Sentry	OtelBeacon
User context	✅	✅
Tags	✅	✅
Extra data	✅	✅
Breadcrumbs	✅	✅
Fingerprinting	✅	✅
Scopes	✅	✅
Contexts	✅	✅
Rails integration	✅	✅
Sidekiq integration	✅	✅
Backend	Sentry.io	Any OTel backend

Viewing Sentry-style Data in SigNoz

OtelBeacon stores all Sentry-style context as OpenTelemetry span attributes and events. Here's how to find them in SigNoz:

Traces View

1. Go to Traces in SigNoz
2. Click on any trace/span to see details
3. Look in the Attributes tab for:

Attribute	Description
user.id, user.email, user.username	User context
tag.*	Custom tags (e.g., tag.feature, tag.priority)
extra	Extra data as JSON
error.fingerprint	Custom error grouping
context.*.*	Structured contexts (e.g., context.payment.provider)
environment, service.name, service.version	Environment info

Breadcrumbs

Breadcrumbs appear as span events named breadcrumb:

1. In trace details, look at the Events section
2. Each breadcrumb has attributes:
   • breadcrumb.category - Category (http, user_action, etc.)
   • breadcrumb.message - Description
   • breadcrumb.level - Severity (info, warning, error)
   • breadcrumb.data - Additional data as JSON

Exceptions

Exceptions are recorded with full context:

1. Filter traces by status: error or look for spans with exceptions
2. In span details, find:
   • exception.type - Exception class name
   • exception.message - Error message
   • exception.stacktrace - Stack trace
   • All user/tags/extra context attached

Querying in SigNoz

Use the query builder to filter by OtelBeacon attributes:

Query	Description
user.id = "123" AND status = error	Find all errors for a specific user
tag.feature = "checkout"	Find traces with specific tag
error.fingerprint CONTAINS "payment"	Find traces with fingerprint

Logs View

Messages from capture_message appear in Logs with:

• message.text - Log message
• message.level - Log level
• All context attributes attached

License

MIT