txlemetry-rails 4.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f59e5f965cb9ed894ce85ddfda78b7d932fff6d1879d930dba5851371d7e30e0
+  data.tar.gz: f672ae2ae805ca8dbe721cc233e82b7e9e7a6dd581796f3597267c2673badc03
+SHA512:
+  metadata.gz: 8d75c19096f1526aa77a4dfed383ee7aaac3b679e4328c154dd93cb27e13a2737a4af80f381441cb31fb9973a46e18df698f23ae4a0c9e48698374b5a6e21df4
+  data.tar.gz: 0b6ef6fc63481e2cba86c8dc2e98e219aa972f869a2a1b774c097c814c35478df7b64583238455a9f8d5094f545479126020ebdd17a5ddfa2ae2369fd472f2c8

data/LICENSE

@@ -0,0 +1,48 @@
+Copyright (c) 2025 PostHog (part of Hiberly Inc)
+
+Copyright (c) 2013 Segment Inc. friends@segment.com
+
+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.
+
+---
+
+Some files in this codebase contain code from getsentry/sentry-ruby.
+In such cases it is explicitly stated in the file header. This license only applies to the relevant code in such cases.
+
+The MIT License (MIT)
+
+Copyright (c) 2020 Sentry
+
+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/NOTICE

@@ -0,0 +1,5 @@
+Txlemetry ruby SDK sources
+Derived from https://github.com/PostHog/posthog-ruby, tag posthog-rails-v3.18.9, commit 820d4bfe8aa3fb3284c4fdf3fb356530340e1c7a.
+Original license files and author notices are retained.
+Public names, package identity, default hosts and distribution are maintained for Txlemetry.
+Candidate source migration and validation are in progress; no release has been published.

data/lib/generators/txlemetry/install_generator.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module Txlemetry
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      desc 'Creates a Txlemetry initializer file at config/initializers/txlemetry.rb'
+
+      source_root File.expand_path('templates', __dir__)
+
+      def copy_initializer
+        copy_file 'txlemetry.rb', 'config/initializers/txlemetry.rb'
+      end
+
+      def show_readme
+        say ''
+        say 'Txlemetry Rails has been installed!', :green
+        say ''
+        say 'Next steps:', :yellow
+        say '  1. Edit config/initializers/txlemetry.rb with your Txlemetry API key'
+        say '  2. Set environment variables:'
+        say '     - TXLEMETRY_API_KEY (required)'
+        say '     - TXLEMETRY_SECRET_KEY (optional, for feature flags)'
+        say ''
+        say 'Optional: forward Rails.logger to Txlemetry Logs', :yellow
+        say '  - Add to your Gemfile (requires Ruby 3.3+):'
+        say "      gem 'opentelemetry-sdk', require: false"
+        say "      gem 'opentelemetry-logs-sdk', '>= 0.6.0', require: false"
+        say "      gem 'opentelemetry-exporter-otlp-logs', require: false"
+        say '  - Set config.logs_enabled = true in the initializer'
+        say '  - Docs: https://txlemetry.com/docs/logs'
+        say ''
+        say 'For more information, see: https://txlemetry.com/docs/libraries/ruby'
+        say ''
+      end
+    end
+  end
+end

data/lib/generators/txlemetry/templates/txlemetry.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+# Txlemetry Rails Initializer
+# Place this file in config/initializers/txlemetry.rb
+
+# ============================================================================
+# RAILS-SPECIFIC CONFIGURATION
+# ============================================================================
+# Configure Rails-specific options via Txlemetry::Rails.configure
+# These settings control how Txlemetry integrates with Rails features.
+
+Txlemetry::Rails.configure do |config|
+  # Automatically capture exceptions (default: false)
+  # Set to true to enable automatic exception tracking
+  # config.auto_capture_exceptions = true
+
+  # Report exceptions that Rails rescues (e.g., with rescue_from) (default: false)
+  # Set to true to capture rescued exceptions
+  # config.report_rescued_exceptions = true
+
+  # Automatically instrument ActiveJob background jobs (default: false)
+  # Set to true to enable automatic ActiveJob exception tracking
+  # config.auto_instrument_active_job = true
+
+  # Use Txlemetry tracing headers for request-scoped identity/session context (default: true)
+  # Request metadata (current URL, method, path, user agent, and IP) is always captured during Rails requests
+  # Set to false to ignore client-supplied X-PostHog-Distinct-Id and X-PostHog-Session-Id headers
+  # config.use_tracing_headers = true
+
+  # Capture authenticated user context with exceptions (default: true)
+  # Authenticated Rails user context takes precedence over client-supplied tracing headers for exception identity
+  # config.capture_user_context = true
+
+  # Controller method name to get current user (default: :current_user)
+  # Change this if your app uses a different method name (e.g., :authenticated_user)
+  # When configured, exceptions will include user context (distinct_id, email, name),
+  # making it easier to identify affected users and debug user-specific issues.
+  # config.current_user_method = :current_user
+
+  # Or provide a resolver for apps that store user context outside controllers,
+  # such as ActiveSupport::CurrentAttributes. The resolver takes precedence over
+  # current_user_method and may accept the controller as an argument.
+  # config.current_user_resolver = proc { Current.user }
+  # config.current_user_resolver = proc { |controller| controller.current_user }
+
+  # Additional exception classes to exclude from reporting
+  # These are added to the default excluded exceptions
+  # config.excluded_exceptions = [
+  #   # 'MyCustom404Error',
+  #   # 'MyCustomValidationError'
+  # ]
+
+  # --------------------------------------------------------------------------
+  # TXLEMETRY LOGS (OpenTelemetry) - opt-in
+  # --------------------------------------------------------------------------
+  # Forward Rails.logger output to Txlemetry Logs over OTLP, automatically
+  # correlated with the request's distinct_id and session_id.
+  #
+  # Requires the OpenTelemetry gems (Ruby 3.3+) in your Gemfile. Use
+  # require: false — txlemetry-rails loads them only when logs are enabled.
+  # logs-sdk must be >= 0.6.0 (older versions lack LogRecordData#event_name,
+  # which the OTLP exporter needs, raising NoMethodError on export):
+  #   gem 'opentelemetry-sdk', require: false
+  #   gem 'opentelemetry-logs-sdk', '>= 0.6.0', require: false
+  #   gem 'opentelemetry-exporter-otlp-logs', require: false
+  #
+  # Enable log forwarding (default: false)
+  # config.logs_enabled = true
+
+  # Broadcast Rails.logger into Txlemetry Logs (default: true when logs enabled)
+  # config.logs_forward_rails_logger = true
+
+  # Minimum severity to forward; nil inherits Rails.logger's level (default: nil)
+  # config.logs_level = :info
+
+  # Maximum records forwarded per minute, protecting your ingestion quota from
+  # runaway log volume. Numeric strings (e.g. from ENV) are coerced.
+  # (default: 6000; set to nil or 0 to disable the cap)
+  # config.logs_max_records_per_minute = 6_000
+
+  # Modify or drop log records before they are sent, e.g. to scrub PII.
+  # Receives a hash (:timestamp, :severity, :body, :attributes — :severity is
+  # a symbol such as :warn); return the (modified) hash to send or nil to
+  # drop. Records are dropped if the callback raises. (default: nil)
+  # config.logs_before_send = proc { |record|
+  #   next nil if record[:severity] == :debug
+  #
+  #   record[:body] = record[:body].gsub(/\b[\w.+-]+@[\w-]+\.[\w.]+\b/, '[redacted email]')
+  #   record
+  # }
+
+  # Logs reuse the same project token (api_key) and host configured below, so
+  # there is nothing extra to set. Logs are sent to <host>/i/v1/logs.
+end
+
+# You can also configure Rails options directly:
+# Txlemetry::Rails.config.auto_capture_exceptions = true
+
+# ============================================================================
+# CORE TXLEMETRY CONFIGURATION
+# ============================================================================
+# Initialize the Txlemetry client with core SDK options.
+# IMPORTANT: Use Txlemetry.init once — creating multiple clients can cause dropped events.
+# Txlemetry.init provides a singleton-like pattern; use Txlemetry.capture, Txlemetry.identify, etc.
+
+Txlemetry.init do |config|
+  # ============================================================================
+  # REQUIRED CONFIGURATION
+  # ============================================================================
+
+  # Your Txlemetry project API key (required)
+  # Get this from: Txlemetry Project Settings > API Keys
+  # https://app.txlemetry.com/settings/project-details#variables
+  config.api_key = ENV.fetch('TXLEMETRY_API_KEY', nil)
+
+  # ============================================================================
+  # OPTIONAL CONFIGURATION
+  # ============================================================================
+
+  # For Txlemetry Cloud, use: https://app.txlemetry.com or https://app.txlemetry.com
+  config.host = ENV.fetch('TXLEMETRY_HOST', 'https://app.txlemetry.com')
+
+  # Secret key (optional, but required for local feature flag evaluation).
+  # Accepts a Personal API Key (phx_...) or a Project Secret API Key (phs_...).
+  # Get this from: Txlemetry Settings > Personal API Keys / Project API Keys
+  config.secret_key = ENV.fetch('TXLEMETRY_SECRET_KEY', nil)
+
+  # Maximum number of events to queue before dropping (default: 10000)
+  config.max_queue_size = 10_000
+
+  # Feature flags polling interval in seconds (default: 30)
+  config.feature_flags_polling_interval = 30
+
+  # Feature flag request timeout in seconds (default: 3)
+  config.feature_flag_request_timeout_seconds = 3
+
+  # Error callback - called when Txlemetry encounters an error
+  # config.on_error = proc { |status, message|
+  #   Rails.logger.error("[Txlemetry] Error #{status}: #{message}")
+  # }
+
+  # Before send callback - modify or filter events before sending
+  # Return nil to prevent the event from being sent
+  # config.before_send = proc { |event|
+  #   # Filter out test users
+  #   return nil if event[:properties]&.dig('$user_email')&.end_with?('@test.com')
+  #
+  #   # Add custom properties to all events
+  #   event[:properties] ||= {}
+  #   event[:properties]['environment'] = Rails.env
+  #
+  #   event
+  # }
+
+  # ============================================================================
+  # ENVIRONMENT-SPECIFIC CONFIGURATION
+  # ============================================================================
+
+  # Disable in test environment
+  config.test_mode = true if Rails.env.test?
+
+  # Optional: Disable in development
+  # config.test_mode = true if Rails.env.test? || Rails.env.development?
+end
+
+# ============================================================================
+# DEFAULT EXCLUDED EXCEPTIONS
+# ============================================================================
+# The following exceptions are excluded by default:
+#
+# - AbstractController::ActionNotFound
+# - ActionController::BadRequest
+# - ActionController::InvalidAuthenticityToken
+# - ActionController::InvalidCrossOriginRequest
+# - ActionController::MethodNotAllowed
+# - ActionController::NotImplemented
+# - ActionController::ParameterMissing
+# - ActionController::RoutingError
+# - ActionController::UnknownFormat
+# - ActionController::UnknownHttpMethod
+# - ActionDispatch::Http::MimeNegotiation::InvalidType
+# - ActionDispatch::Http::Parameters::ParseError
+# - ActiveRecord::RecordNotFound
+# - ActiveRecord::RecordNotUnique
+#
+# These can be re-enabled by removing them from the exclusion list if needed.

data/lib/txlemetry/rails/active_job.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require 'txlemetry/rails/parameter_filter'
+
+module Txlemetry
+  module Rails
+    # ActiveJob integration to capture exceptions from background jobs
+    module ActiveJobExtensions
+      include ParameterFilter
+
+      def self.prepended(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        # DSL for defining how to extract distinct_id from job arguments.
+        #
+        # @param proc [Proc, nil] Callable that receives the job's perform arguments.
+        # @yield The block receives the job's perform arguments.
+        # @return [Proc, nil] The configured extractor.
+        #
+        # Example:
+        #   class MyJob < ApplicationJob
+        #     txlemetry_distinct_id ->(user, arg1, arg2) { user.id }
+        #     def perform(user, arg1, arg2)
+        #       # ...
+        #     end
+        #   end
+        def txlemetry_distinct_id(proc = nil, &block)
+          @txlemetry_distinct_id_proc = proc || block
+        end
+
+        # @return [Proc, nil] The configured distinct_id extractor.
+        def txlemetry_distinct_id_proc
+          @txlemetry_distinct_id_proc
+        end
+      end
+
+      def perform_now
+        super
+      rescue StandardError => e
+        # Capture the exception with job context
+        capture_job_exception(e)
+        raise
+      end
+
+      private
+
+      def capture_job_exception(exception)
+        return unless Txlemetry::Rails.config&.auto_instrument_active_job
+
+        # Build distinct_id from job arguments if possible
+        distinct_id = extract_distinct_id_from_job
+
+        properties = {
+          '$exception_source' => 'active_job',
+          '$job_class' => self.class.name,
+          '$job_id' => job_id,
+          '$queue_name' => queue_name,
+          '$job_priority' => priority,
+          '$job_executions' => executions
+        }
+
+        # Add serialized job arguments (be careful with sensitive data)
+        properties['$job_arguments'] = sanitize_job_arguments(arguments) if arguments.present?
+
+        Txlemetry.capture_exception(
+          exception,
+          distinct_id,
+          properties,
+          mechanism: { 'type' => 'active_job', 'handled' => false }
+        )
+        Txlemetry::Rails.mark_active_job_exception_captured(exception)
+      rescue StandardError => e
+        # Don't let Txlemetry errors break job processing
+        Txlemetry::Logging.logger.error("Failed to capture job exception: #{e.message}")
+      end
+
+      def extract_distinct_id_from_job
+        # First, check if the job class defines a custom extractor
+        return self.class.txlemetry_distinct_id_proc.call(*arguments) if self.class.txlemetry_distinct_id_proc
+
+        # Fallback: look for explicit user_id in hash arguments only
+        arguments.each do |arg|
+          if arg.is_a?(Hash) && arg['user_id']
+            return arg['user_id']
+          elsif arg.is_a?(Hash) && arg[:user_id]
+            return arg[:user_id]
+          end
+        end
+
+        nil # No user context found
+      end
+
+      def sanitize_job_arguments(args)
+        # Convert arguments to a safe format
+        args.map do |arg|
+          case arg
+          when String
+            # Truncate long strings to prevent huge payloads
+            arg.length > 100 ? "[FILTERED: #{arg.length} chars]" : arg
+          when Integer, Float, TrueClass, FalseClass, NilClass
+            arg
+          when Hash
+            # Use Rails' filter_parameters to filter sensitive data
+            filter_sensitive_params(arg)
+          when defined?(ActiveRecord::Base) && ActiveRecord::Base
+            { class: arg.class.name, id: arg.id }
+          else
+            arg.class.name
+          end
+        end
+      rescue StandardError
+        ['<serialization error>']
+      end
+    end
+  end
+end

data/lib/txlemetry/rails/capture_exceptions.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require 'txlemetry/rails/parameter_filter'
+
+module Txlemetry
+  module Rails
+    # Middleware that captures exceptions and sends them to Txlemetry.
+    #
+    # @api private
+    class CaptureExceptions
+      include ParameterFilter
+
+      # @param app [#call] Rack application.
+      def initialize(app)
+        @app = app
+      end
+
+      # @param env [Hash] Rack environment.
+      # @return [Array] Rack response.
+      def call(env)
+        # Signal that we're in a web request context
+        # ErrorSubscriber will skip capture for web requests to avoid duplicates
+        Txlemetry::Rails.enter_web_request
+
+        response = @app.call(env)
+        env['txlemetry.response_status_code'] = response_status(response)
+
+        # Check if there was an exception that Rails handled
+        exception = collect_exception(env)
+
+        capture_exception(exception, env) if exception && should_capture?(exception)
+
+        response
+      rescue StandardError => e
+        # Capture unhandled exceptions
+        capture_exception(e, env) if should_capture?(e)
+        raise
+      ensure
+        Txlemetry::Rails.exit_web_request
+      end
+
+      private
+
+      def collect_exception(env)
+        # Rails stores exceptions in these env keys
+        env['action_dispatch.exception'] ||
+          env['rack.exception'] ||
+          env['txlemetry.rescued_exception']
+      end
+
+      def should_capture?(exception)
+        return false unless Txlemetry::Rails.config&.auto_capture_exceptions
+        return false unless Txlemetry::Rails.config&.should_capture_exception?(exception)
+
+        true
+      end
+
+      def capture_exception(exception, env)
+        request = ActionDispatch::Request.new(env)
+        distinct_id = extract_distinct_id(env)
+        additional_properties = build_properties(request, env)
+
+        captured = Txlemetry.capture_exception(
+          exception,
+          distinct_id,
+          additional_properties,
+          mechanism: { 'type' => 'rails', 'handled' => false }
+        )
+        Txlemetry::Rails.mark_web_exception_captured(exception) if captured
+      rescue StandardError => e
+        Txlemetry::Logging.logger.error("Failed to capture exception: #{e.message}")
+        Txlemetry::Logging.logger.error("Backtrace: #{e.backtrace&.first(5)&.join("\n")}")
+      end
+
+      def extract_distinct_id(env)
+        # Prefer authenticated Rails user context. Request/tracing context is
+        # applied later by the core capture path if this returns nil.
+        return nil unless Txlemetry::Rails.config&.capture_user_context
+
+        user = extract_current_user(env['action_controller.instance'])
+        user_id = extract_user_id(user) if user
+        return user_id if present?(user_id)
+
+        nil
+      end
+
+      def extract_current_user(controller)
+        resolver = Txlemetry::Rails.config&.current_user_resolver
+        return resolve_current_user(resolver, controller) if resolver
+
+        method_name = Txlemetry::Rails.config&.current_user_method || :current_user
+        return unless controller.respond_to?(method_name, true)
+
+        controller.send(method_name)
+      end
+
+      def resolve_current_user(resolver, controller)
+        call_current_user_resolver(resolver, controller)
+      rescue StandardError => e
+        Txlemetry::Logging.logger.warn("current_user_resolver failed: #{e.message}")
+        nil
+      end
+
+      def call_current_user_resolver(resolver, controller)
+        if resolver.arity.zero?
+          controller ? controller.instance_exec(&resolver) : resolver.call
+        elsif controller
+          resolver.call(controller)
+        end
+      end
+
+      def extract_user_id(user)
+        # Use configured method if specified
+        method_name = Txlemetry::Rails.config&.user_id_method
+        return user.send(method_name) if method_name && user.respond_to?(method_name)
+
+        # Try explicit Txlemetry method (allows users to customize without config)
+        return user.txlemetry_distinct_id if user.respond_to?(:txlemetry_distinct_id)
+        return user.distinct_id if user.respond_to?(:distinct_id)
+
+        # Try common ID methods
+        return user.id if user.respond_to?(:id)
+        return user['id'] if user.respond_to?(:[]) && user['id']
+        return user.pk if user.respond_to?(:pk)
+        return user['pk'] if user.respond_to?(:[]) && user['pk']
+        return user.uuid if user.respond_to?(:uuid)
+        return user['uuid'] if user.respond_to?(:[]) && user['uuid']
+
+        user.to_s
+      end
+
+      def build_properties(request, env)
+        properties = {
+          '$exception_source' => 'rails'
+        }
+
+        # Add controller and action if available
+        if env['action_controller.instance']
+          controller = env['action_controller.instance']
+          properties['$controller'] = safe_serialize(controller.controller_name)
+          properties['$action'] = safe_serialize(controller.action_name)
+        end
+
+        # Add request parameters (be careful with sensitive data)
+        if request.params.present?
+          filtered_params = filter_sensitive_params(request.params)
+          # Safe serialize to handle any complex objects in params
+          properties['$request_params'] = safe_serialize(filtered_params) unless filtered_params.empty?
+        end
+
+        response_status_code = env['txlemetry.response_status_code']
+        properties['$response_status_code'] = response_status_code if response_status_code
+
+        # Add referrer
+        properties['$referrer'] = safe_serialize(request.referrer) if request.referrer
+
+        properties
+      end
+
+      def response_status(response)
+        status = response.respond_to?(:[]) ? response[0] : nil
+        status if status.is_a?(Integer)
+      end
+
+      def present?(value)
+        !(value.nil? || (value.respond_to?(:empty?) && value.empty?))
+      end
+    end
+  end
+end