otel_beacon 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 87071db6d653ac58e3543e8913fb4fec68ead62da10b082d29df4febed98a9ee
+  data.tar.gz: 352b451298dff4b8c68974eb425f1197f590f0b43fad5433b191d04822b8025d
+SHA512:
+  metadata.gz: 8c09144054ee299d399a2e5f88bc0de27af87383c45920a50ad358307eca420385a7c01f09dd88bd4e41765683b8abe689dc6ee5167d061adb4032317d4b1f45
+  data.tar.gz: c785d4c5067ca5cf533d970278c99989f10d4c617fddfa64d45cfa3ad3c004bff3ed5f1665a099dc6928293a4ed725717e9731d464df2ddf63a908627eeea792

data/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## [0.1.0] - 2024-01-29
+
+### Added
+- Initial release
+- Sentry-style user context (`set_user`)
+- Tags support (`set_tags`)
+- Extra data support (`set_extra`)
+- Breadcrumbs (`add_breadcrumb`)
+- Structured contexts (`set_context`)
+- Fingerprinting for error grouping (`set_fingerprint`)
+- Scoped context (`with_scope`)
+- Manual exception capture (`capture_exception`)
+- Message capture (`capture_message`)
+- Custom spans (`in_span`)
+- Rails integration (controllers, jobs, mailers)
+- Sidekiq integration
+- Runtime context (Ruby, OS, app, device, browser)
+- Configurable current user detection
+- Parameter sanitization

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024
+
+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,258 @@
+# 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:
+
+```ruby
+gem 'otel_beacon'
+```
+
+## Quick Start
+
+```ruby
+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
+
+```ruby
+OtelBeacon.set_user(
+  id: user.id,
+  email: user.email,
+  username: user.name,
+  subscription: "premium"
+)
+```
+
+Custom attributes beyond id/email/username are also supported.
+
+### Tags
+
+```ruby
+OtelBeacon.set_tags(
+  feature: "checkout",
+  priority: "high",
+  release: "1.2.3"
+)
+```
+
+### Extra Data
+
+```ruby
+OtelBeacon.set_extra(
+  cart_id: 123,
+  items_count: 5,
+  total_amount: 99.99
+)
+```
+
+### Breadcrumbs
+
+```ruby
+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
+
+```ruby
+OtelBeacon.set_context(:payment, provider: "stripe", amount: 99.99)
+OtelBeacon.set_context(:feature_flags, dark_mode: true, beta: false)
+```
+
+### Fingerprinting (Error Grouping)
+
+```ruby
+OtelBeacon.set_fingerprint("payment", "stripe", "card-declined")
+```
+
+### Scoped Context
+
+```ruby
+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
+
+```ruby
+begin
+  risky_operation
+rescue => e
+  OtelBeacon.capture_exception(e,
+    extra: { operation: "payment" },
+    fingerprint: ["payment", "timeout"]
+  )
+  raise
+end
+```
+
+### Custom Spans
+
+```ruby
+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
+
+```ruby
+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:**
+```ruby
+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:**
+```ruby
+OtelBeacon.sanitize_fields = %w[password token secret key auth credential api_key access_token]
+```
+
+**Limits:**
+```ruby
+OtelBeacon.max_breadcrumbs = 50
+OtelBeacon.max_stacktrace_lines = 20
+```
+
+**Hooks:**
+```ruby
+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

data/UPGRADING.md

@@ -0,0 +1,60 @@
+# Upgrading OtelBeacon
+
+## Version 0.1.0
+
+This is the initial public release following solid_queue Rails patterns.
+
+### Configuration
+
+Configuration uses direct attribute setters on the module:
+
+```ruby
+OtelBeacon.enabled = true
+OtelBeacon.service_name = "my_app"
+OtelBeacon.max_breadcrumbs = 100
+OtelBeacon.sanitize_fields = %w[password token secret]
+```
+
+### Rails Configuration
+
+In Rails, you can also configure via `config/application.rb` or environment files:
+
+```ruby
+config.otel_beacon.enabled = true
+config.otel_beacon.service_name = "my_app"
+config.otel_beacon.max_breadcrumbs = 100
+```
+
+### Predicate Methods
+
+Boolean configuration options have predicate methods:
+
+```ruby
+OtelBeacon.enabled?
+OtelBeacon.capture_exceptions?
+OtelBeacon.capture_logs?
+```
+
+### Error Reporting
+
+Errors are reported via `Rails.error.report` when running in Rails. The `on_thread_error` callback is available for custom error handling:
+
+```ruby
+OtelBeacon.on_thread_error = ->(exception) { Sentry.capture_exception(exception) }
+```
+
+### Instrumentation
+
+ActiveSupport::Notifications events are available:
+
+- `capture_exception.otel_beacon`
+- `capture_message.otel_beacon`
+- `add_breadcrumb.otel_beacon`
+
+Subscribe to events:
+
+```ruby
+ActiveSupport::Notifications.subscribe("capture_exception.otel_beacon") do |event|
+  puts "Exception captured: #{event.payload[:exception].class}"
+end
+```

data/lib/otel_beacon/breadcrumb.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module OtelBeacon
+  class Breadcrumb
+    attr_reader :category, :message, :level, :data, :timestamp
+
+    def initialize(category, message = nil, level: :info, **data)
+      @category = category.to_s
+      @message = message
+      @level = level.to_s
+      @data = data
+      @timestamp = Time.now.iso8601
+    end
+
+    def to_h
+      { category: @category, message: @message, level: @level, data: @data, timestamp: @timestamp }
+    end
+
+    class << self
+      def info(category, message = nil, **data) = new(category, message, level: :info, **data)
+      def warn(category, message = nil, **data) = new(category, message, level: :warn, **data)
+      def error(category, message = nil, **data) = new(category, message, level: :error, **data)
+      def debug(category, message = nil, **data) = new(category, message, level: :debug, **data)
+
+      def build(category:, message: nil, level: :info, data: {}, **extra)
+        new(category, message, level: level, **data.merge(extra))
+      end
+    end
+  end
+end

data/lib/otel_beacon/client.rb

@@ -0,0 +1,296 @@
+# frozen_string_literal: true
+
+module OtelBeacon
+  module Client
+    class << self
+      def reset_context!
+        Context.reset!
+      end
+
+      def set_user(id: nil, email: nil, username: nil, ip_address: nil, **extra)
+        Context.current[:user] =
+          { id: id, email: email, username: username, ip_address: ip_address }.compact.merge(extra)
+      end
+
+      def set_tags(**tags)
+        Context.tags.merge!(tags.transform_values(&:to_s))
+      end
+
+      def set_extra(**extra)
+        Context.extra.merge!(extra)
+      end
+
+      def set_context(name, **data)
+        Context.contexts[name.to_sym] = data
+      end
+
+      def set_fingerprint(*fingerprint)
+        Context.fingerprint = fingerprint.flatten
+      end
+
+      def with_scope
+        Context.push_scope
+        scope = Scope.new
+        yield scope
+      ensure
+        Context.pop_scope
+      end
+
+      def add_breadcrumb(category_or_crumb, message = nil, level: :info, **data)
+        crumb = if category_or_crumb.is_a?(Breadcrumb)
+                  category_or_crumb.to_h
+        else
+                  Breadcrumb.new(category_or_crumb, message, level: level, **data).to_h
+        end
+        Context.breadcrumbs << crumb
+        Context.breadcrumbs.shift if Context.breadcrumbs.size > OtelBeacon.max_breadcrumbs
+      end
+
+      def tracer
+        OpenTelemetry.tracer_provider.tracer(OtelBeacon.service_name, OtelBeacon::VERSION)
+      end
+
+      def in_span(name, attributes: {}, record_exception: true)
+        tracer.in_span(name, attributes: attributes) do |span|
+          yield span
+        rescue StandardError => e
+          if record_exception
+            span.record_exception(e)
+            span.status = OpenTelemetry::Trace::Status.error(e.message)
+          end
+          raise
+        end
+      end
+
+      def capture_message(message, level: :info, tags: nil, extra: nil, user: nil, request: nil, fingerprint: nil)
+        return unless OtelBeacon.enabled?
+        return unless otel_logger_available?
+
+        attrs = build_message_attributes(
+          message: message, level: level, tags: tags, extra: extra,
+          user: user, request: request, fingerprint: fingerprint
+        )
+
+        current_span = OpenTelemetry::Trace.current_span
+        emit_breadcrumbs_to_span(current_span) if current_span&.recording?
+
+        otel_logger.on_emit(
+          severity_text: level.to_s.upcase,
+          body: message,
+          attributes: attrs,
+          context: OpenTelemetry::Context.current
+        )
+
+        OtelBeacon.instrument(:capture_message, message: message, level: level)
+      rescue StandardError
+      end
+
+      def capture_exception(exception, request: nil, params: nil, user: nil, tags: nil, extra: nil, fingerprint: nil)
+        return unless OtelBeacon.enabled?
+
+        current_span = OpenTelemetry::Trace.current_span
+        return unless current_span&.recording?
+
+        exc_attrs = build_exception_attributes(
+          exception: exception, request: request, params: params,
+          user: user, tags: tags, extra: extra, fingerprint: fingerprint
+        )
+
+        set_span_attributes(current_span, exc_attrs)
+        emit_breadcrumbs_to_span(current_span)
+        current_span.record_exception(exception, attributes: exc_attrs)
+        current_span.status = OpenTelemetry::Trace::Status.error(exception.message)
+
+        log_exception(exception, exc_attrs)
+        OtelBeacon.instrument(:capture_exception, exception: exception)
+      end
+
+      def record_event(name, attributes: {})
+        current_span = OpenTelemetry::Trace.current_span
+        return unless current_span&.recording?
+
+        current_span.add_event(name, attributes: attributes)
+      end
+
+      def flush_context_to_span
+        current_span = OpenTelemetry::Trace.current_span
+        return unless current_span&.recording?
+
+        attrs = {}
+        add_user_attributes(attrs, nil)
+        add_tag_attributes(attrs, nil)
+        add_extra_attributes(attrs, nil)
+        add_context_attributes(attrs)
+        add_environment_attributes(attrs)
+
+        set_span_attributes(current_span, attrs)
+        emit_breadcrumbs_to_span(current_span)
+      end
+
+      private
+
+      def otel_logger_available?
+        OpenTelemetry.logger_provider&.respond_to?(:logger)
+      end
+
+      def otel_logger
+        OpenTelemetry.logger_provider.logger(name: OtelBeacon.service_name, version: OtelBeacon::VERSION)
+      end
+
+      def emit_breadcrumbs_to_span(span)
+        Context.breadcrumbs.each_with_index do |crumb, idx|
+          span.add_event("breadcrumb", attributes: {
+                           "breadcrumb.index" => idx,
+                           "breadcrumb.category" => crumb[:category],
+                           "breadcrumb.message" => crumb[:message],
+                           "breadcrumb.level" => crumb[:level],
+                           "breadcrumb.timestamp" => crumb[:timestamp],
+                           "breadcrumb.data" => crumb[:data].to_json
+                         })
+        end
+      end
+
+      def build_message_attributes(message:, level:, tags: nil, extra: nil, user: nil, request: nil, fingerprint: nil)
+        attrs = { "message.text" => message, "message.level" => level.to_s }
+        attrs["message.fingerprint"] = fingerprint.join(":") if fingerprint.is_a?(Array)
+
+        add_request_attributes(attrs, request) if request
+        add_user_attributes(attrs, user)
+        add_tag_attributes(attrs, tags)
+        add_extra_attributes(attrs, extra)
+        add_environment_attributes(attrs)
+
+        attrs.compact
+      end
+
+      def build_exception_attributes(exception:, request: nil, params: nil, user: nil, tags: nil, extra: nil,
+                                     fingerprint: nil)
+        attrs = {
+          "exception.type" => exception.class.name,
+          "exception.message" => exception.message
+        }
+        if exception.backtrace
+          attrs["exception.stacktrace"] = exception.backtrace.first(OtelBeacon.max_stacktrace_lines).join("\n")
+        end
+
+        add_request_attributes(attrs, request) if request
+        add_params_attributes(attrs, params) if params
+        add_user_attributes(attrs, user)
+        add_tag_attributes(attrs, tags)
+        add_extra_attributes(attrs, extra)
+        add_context_attributes(attrs)
+        add_fingerprint_attributes(attrs, fingerprint)
+        add_environment_attributes(attrs)
+        attrs["service.version"] = OtelBeacon.service_version
+
+        attrs.compact
+      end
+
+      def add_request_attributes(attrs, request)
+        attrs["http.method"] = begin
+          request.request_method
+        rescue StandardError
+          nil
+        end
+        attrs["http.url"] = begin
+          request.original_url
+        rescue StandardError
+          nil
+        end
+        attrs["http.host"] = begin
+          request.host
+        rescue StandardError
+          nil
+        end
+        attrs["http.path"] = begin
+          request.path
+        rescue StandardError
+          nil
+        end
+        attrs["http.user_agent"] = begin
+          request.user_agent
+        rescue StandardError
+          nil
+        end
+        attrs["http.referer"] = begin
+          request.referer
+        rescue StandardError
+          nil
+        end
+        attrs["client.ip"] = begin
+          request.remote_ip
+        rescue StandardError
+          nil
+        end
+        attrs["http.request_id"] = begin
+          request.request_id
+        rescue StandardError
+          nil
+        end
+      end
+
+      def add_params_attributes(attrs, params)
+        sanitized = Sanitizer.extract_params(params)
+        attrs["request.params"] = sanitized.to_json unless sanitized.empty?
+      end
+
+      def add_user_attributes(attrs, user)
+        merged = Context.user.merge(user || {})
+        return if merged.empty?
+
+        attrs["user.id"] = merged[:id].to_s if merged[:id]
+        attrs["user.email"] = merged[:email] if merged[:email]
+        attrs["user.username"] = merged[:username] if merged[:username]
+        attrs["user.ip_address"] = merged[:ip_address] if merged[:ip_address]
+      end
+
+      def add_tag_attributes(attrs, tags)
+        merged = Context.tags.merge(tags || {})
+        merged.each { |k, v| attrs["tag.#{k}"] = v.to_s }
+      end
+
+      def add_extra_attributes(attrs, extra)
+        merged = Context.extra.merge(extra || {})
+        attrs["extra"] = merged.to_json unless merged.empty?
+      end
+
+      def add_context_attributes(attrs)
+        Context.contexts.each do |name, data|
+          data.each { |k, v| attrs["context.#{name}.#{k}"] = v.to_s }
+        end
+      end
+
+      def add_fingerprint_attributes(attrs, fingerprint)
+        fp = fingerprint || Context.fingerprint
+        attrs["error.fingerprint"] = fp.join(":") if fp.is_a?(Array) && fp.any?
+      end
+
+      def add_environment_attributes(attrs)
+        attrs["environment"] = OtelBeacon.environment.to_s
+        attrs["service.name"] = OtelBeacon.service_name
+      end
+
+      def set_span_attributes(span, attrs)
+        attrs.each do |key, value|
+          next if value.nil?
+
+          span.set_attribute(key.to_s, value.to_s)
+        rescue StandardError
+          next
+        end
+      end
+
+      def log_exception(exception, attributes)
+        return unless otel_logger_available?
+
+        otel_logger.on_emit(
+          severity_text: "ERROR",
+          body: "#{exception.class}: #{exception.message}",
+          attributes: attributes,
+          context: OpenTelemetry::Context.current
+        )
+      rescue StandardError
+      end
+    end
+  end
+end