posthog-rails 3.11.1 → 3.12.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 986306ebedb5f7c0f06df369401a65a717eba7644285798a52152ef2a56748e9
-  data.tar.gz: 2ebc32708ed7a022ee45aed29abdee657843374e979633f4f5ab56777a8a5262
+  metadata.gz: 2fadda53222559f077f30facbf0d0ecf6edfba62e116aaf5eb48bba8bd8cac5f
+  data.tar.gz: 4bc7f6753ef7bd80fca9418c679085ae894441b5efcb06bd4d31348a30ec2ef7
 SHA512:
-  metadata.gz: 48c9c6daf2ae309243f04e62093152d59acbc772968fd241634b28a0948721ab9626fbe4db15f83aae03c73bec43d3d643237a3054e063f41b020a028224ba4c
-  data.tar.gz: 6ce744037de3fe24245ae3bae7f6b111647abc0118147d49ba9b10ed17af823b58db3894ac750bbcec73b30a18a713a9fbd09d78fbfd1aa2559e5b090ccee867
+  metadata.gz: ddf76534a44251b45498328de34a5414b27aa3886de584c2f62b953658a5fafa2f77a6dac0f4938502e4a86dc905b35f7f5e4423fcb1e981995552cb6ea0fe02
+  data.tar.gz: 2f117183afbf4ec5cce029afe3e4170739b1f52707c4465a2a3312891bf10cc2a0d0202c37622ea32e6ccae6d4e2e211057b8fdbe1851cdf66d33414de086a8e

data/lib/generators/posthog/install_generator.rb

@@ -23,6 +23,14 @@ module Posthog
         say '     - POSTHOG_API_KEY (required)'
         say '     - POSTHOG_PERSONAL_API_KEY (optional, for feature flags)'
         say ''
+        say 'Optional: forward Rails.logger to PostHog 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://posthog.com/docs/logs'
+        say ''
         say 'For more information, see: https://posthog.com/docs/libraries/ruby'
         say ''
       end

data/lib/generators/posthog/templates/posthog.rb

@@ -43,6 +43,48 @@ PostHog::Rails.configure do |config|
   #   # 'MyCustom404Error',
   #   # 'MyCustomValidationError'
   # ]
+
+  # --------------------------------------------------------------------------
+  # POSTHOG LOGS (OpenTelemetry) - opt-in
+  # --------------------------------------------------------------------------
+  # Forward Rails.logger output to PostHog 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 — posthog-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 PostHog 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:

data/lib/posthog/rails/configuration.rb

@@ -7,6 +7,9 @@
 module PostHog
   module Rails
     class Configuration
+      # Default cap on log records forwarded to PostHog Logs per minute.
+      DEFAULT_LOGS_MAX_RECORDS_PER_MINUTE = 6_000
+
       # @return [Boolean] Whether to automatically capture exceptions from Rails. Defaults to false.
       attr_accessor :auto_capture_exceptions
 
@@ -33,6 +36,29 @@ module PostHog
       #   posthog_distinct_id, distinct_id, id, pk, uuid in order.
       attr_accessor :user_id_method
 
+      # @return [Boolean] Master switch for forwarding logs to PostHog Logs over OTLP. Defaults to false.
+      attr_accessor :logs_enabled
+
+      # @return [Boolean] Whether to broadcast Rails.logger output into the PostHog Logs sink. Defaults to true
+      #   (only takes effect when {#logs_enabled} is true).
+      attr_accessor :logs_forward_rails_logger
+
+      # @return [Integer, Symbol, nil] Minimum severity to forward to PostHog Logs. When nil, inherits the
+      #   current Rails.logger level. Accepts a Logger severity constant (e.g. Logger::INFO) or symbol (:info).
+      attr_accessor :logs_level
+
+      # @return [Integer, String, nil] Maximum log records forwarded to PostHog Logs per minute, protecting
+      #   the ingestion quota from runaway log volume. Defaults to 6000. Numeric strings (e.g. from ENV) are
+      #   coerced. Set to nil, 0, or a negative value to disable the cap; an unparseable value falls back to
+      #   the default with a warning.
+      attr_accessor :logs_max_records_per_minute
+
+      # @return [Proc, nil] Callback invoked with each log record hash (:timestamp, :severity, :body,
+      #   :attributes — where :severity is a symbol such as :warn) before it is sent to PostHog Logs.
+      #   Return a (possibly modified) hash to send, or nil to drop the record — useful for scrubbing
+      #   PII. If the callback raises, the record is dropped. Defaults to nil.
+      attr_accessor :logs_before_send
+
       # @return [PostHog::Rails::Configuration]
       def initialize
         @auto_capture_exceptions = false
@@ -43,6 +69,11 @@ module PostHog
         @capture_user_context = true
         @current_user_method = :current_user
         @user_id_method = nil
+        @logs_enabled = false
+        @logs_forward_rails_logger = true
+        @logs_level = nil
+        @logs_max_records_per_minute = DEFAULT_LOGS_MAX_RECORDS_PER_MINUTE
+        @logs_before_send = nil
       end
 
       # Default exceptions that Rails apps typically don't want to track.

data/lib/posthog/rails/logs/appender.rb

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+require 'logger'
+require 'time'
+require 'posthog/internal/context'
+require 'posthog/logging'
+require 'posthog/rails/logs/severity'
+
+module PostHog
+  module Rails
+    module Logs
+      # A `Logger`-compatible sink that forwards each log record to an
+      # OpenTelemetry logger as an OTLP log record.
+      #
+      # It is designed to be broadcast alongside the app's existing
+      # `Rails.logger` so that ordinary `Rails.logger.info(...)` calls flow to
+      # PostHog Logs in addition to the normal output. Each record is stamped
+      # with the request-scoped PostHog identity captured by
+      # {PostHog::Rails::RequestContext}.
+      #
+      # Thread-safety: intentionally lock-free apart from the optional rate
+      # limiter's counter. Emitting touches no shared mutable state
+      # (`@otel_logger` is assigned once, attributes are built per call, and
+      # `Internal::Context.current` is thread/fiber-local), and the OTel
+      # BatchLogRecordProcessor synchronizes its buffer internally — the same
+      # split as stdlib `Logger`, which locks in `LogDevice`, not
+      # `Logger#add`. A mutex around emit would serialize all app logging
+      # needlessly.
+      #
+      # @api private
+      class Appender < ::Logger
+        SELF_LOG_PREFIX = '[posthog-ruby]'
+        SELF_LOG_PROGNAME = 'PostHog'
+        # Maps PostHog event-property names (as stored in Internal::Context) to
+        # the OTel semantic-convention attribute names used on log records,
+        # matching the web SDK so one filter works across SDKs.
+        REQUEST_ATTRIBUTE_NAMES = {
+          '$current_url' => 'url.full',
+          '$request_method' => 'http.request.method',
+          '$request_path' => 'url.path'
+        }.freeze
+
+        # @param otel_logger [#on_emit] An OpenTelemetry logger.
+        # @param level [Integer, nil] Minimum severity to forward.
+        # @param rate_limiter [PostHog::Rails::Logs::RateLimiter, nil] Optional cap on
+        #   forwarded records, protecting the ingestion quota from runaway log volume.
+        # @param before_send [#call, nil] Optional callback invoked with each record hash
+        #   (:timestamp, :severity, :body, :attributes — where :severity is a symbol such
+        #   as :warn) before it is emitted. Return a (possibly modified) hash to send, or
+        #   nil to drop — useful for scrubbing PII. If the callback raises, the record is
+        #   dropped.
+        def initialize(otel_logger, level: nil, rate_limiter: nil, before_send: nil)
+          super(nil)
+          @otel_logger = otel_logger
+          @rate_limiter = rate_limiter
+          @before_send = before_send
+          # The forwarding threshold deliberately does NOT live in Logger#level.
+          # Rails 7.1+ BroadcastLogger computes #level as the min and #debug?
+          # etc. as the any? across sinks, so storing it there would widen the
+          # app-wide predicates (logs_level = :debug would flip
+          # Rails.logger.debug? true and make e.g. ActiveRecord start
+          # generating SQL debug lines), and a broadcast-wide
+          # `Rails.logger.level =` would clobber the configured logs_level.
+          # Pinning the inherited level to UNKNOWN keeps this sink invisible
+          # to those calculations; filtering happens against @threshold in #add.
+          @threshold = level || ::Logger::DEBUG
+          self.level = ::Logger::UNKNOWN
+        end
+
+        # Re-entrancy guard key. Fiber-local (Thread.current[]), which is what
+        # recursion needs: if anything inside #add logs through a broadcast
+        # that includes this appender (e.g. a logs_before_send callback calling
+        # Rails.logger), the nested call would recurse until SystemStackError —
+        # which, as an Exception, escapes the rescue below and breaks the app.
+        REENTRANCY_KEY = :posthog_rails_logs_emitting
+
+        # Mirrors `Logger#add` message/progname resolution, then emits to OTel
+        # instead of writing to a log device.
+        #
+        # @return [Boolean] Always true so it composes with broadcast loggers.
+        def add(severity, message = nil, progname = nil)
+          return true if Thread.current[REENTRANCY_KEY]
+
+          begin
+            Thread.current[REENTRANCY_KEY] = true
+
+            severity ||= ::Logger::UNKNOWN
+            return true if severity < @threshold
+
+            if message.nil?
+              if block_given?
+                message = yield
+              else
+                message = progname
+                progname = nil
+              end
+            end
+
+            return true if message.nil?
+            return true if self_log?(message, progname)
+
+            record = apply_before_send(build_record(severity, message, progname))
+            return true if record.nil?
+
+            case @rate_limiter&.record
+            when :reject
+              return true
+            when :reject_first
+              emit_rate_cap_notice
+              return true
+            end
+
+            emit(record)
+            true
+          rescue StandardError => e
+            # Never let log forwarding break the calling code path, but leave
+            # one breadcrumb: a persistent emit failure would otherwise drop
+            # 100% of records with no signal anywhere.
+            warn_emit_error(e)
+            true
+          ensure
+            Thread.current[REENTRANCY_KEY] = nil
+          end
+        end
+
+        private
+
+        def build_record(severity, message, progname)
+          {
+            timestamp: Time.now,
+            severity: Severity.name_for(severity),
+            body: body_for(message),
+            attributes: attributes_for(progname)
+          }
+        end
+
+        def emit(record)
+          # The before_send callback sees a single :severity enum; the OTel
+          # number/text pair is derived here so the two can never be set
+          # inconsistently.
+          severity_number, severity_text = Severity.for_name(record[:severity])
+          @otel_logger.on_emit(
+            timestamp: record[:timestamp],
+            severity_number: severity_number,
+            severity_text: severity_text,
+            body: record[:body],
+            attributes: record[:attributes]
+          )
+        end
+
+        # One discoverable notice per window so truncation isn't silent. Emitted
+        # directly (bypassing before_send) so a scrubber can't accidentally
+        # suppress the only signal that records are being dropped.
+        def emit_rate_cap_notice
+          emit(
+            timestamp: Time.now,
+            severity: :warn,
+            body: "PostHog Logs rate cap reached (#{@rate_limiter.limit} records/minute); " \
+                  'dropping further records for the remainder of this window',
+            attributes: {}
+          )
+        end
+
+        # Runs before the rate-cap check (matching the other PostHog SDKs) so
+        # records dropped by the callback never consume window budget — a
+        # before_send that drops noisy logs must not starve the legitimate
+        # records behind them.
+        #
+        # Unlike the events before_send (which sends the original event when the
+        # callback raises), a failing callback drops the record: the likeliest
+        # use is PII scrubbing, where shipping the unscrubbed original is worse
+        # than losing the line.
+        def apply_before_send(record)
+          return record unless @before_send
+
+          result = @before_send.call(record)
+          return result if result.is_a?(Hash)
+
+          # nil is an intentional drop and stays silent; any other type is
+          # likely a bug (e.g. a proc whose last expression isn't the record).
+          warn_before_send("returned #{result.class} instead of a Hash or nil") unless result.nil?
+          nil
+        rescue StandardError => e
+          warn_before_send("raised (#{e.class}: #{e.message})")
+          nil
+        end
+
+        def warn_before_send(description)
+          # Benign race: concurrent first failures may warn more than once.
+          return if @before_send_warned
+
+          @before_send_warned = true
+          PostHog::Logging.logger.warn("logs_before_send #{description}; dropping the record")
+        end
+
+        def warn_emit_error(error)
+          # Benign race: concurrent first failures may warn more than once.
+          return if @emit_error_warned
+
+          @emit_error_warned = true
+          PostHog::Logging.logger.warn(
+            "PostHog Logs failed to emit a record (#{error.class}: #{error.message}); " \
+            'further failures will be dropped silently'
+          )
+        end
+
+        def body_for(message)
+          str = stringify(message)
+          str = str.encode(Encoding::UTF_8, invalid: :replace, undef: :replace) unless str.encoding == Encoding::UTF_8
+          str.valid_encoding? ? str : str.scrub
+        end
+
+        # Mirrors stdlib Logger::Formatter#msg2str so the body matches what the
+        # file logger writes — most importantly, an Exception renders with its
+        # class, message, and backtrace instead of a backtrace-less #inspect.
+        # Array() guards a never-raised exception whose backtrace is nil. The
+        # returned String is always freshly built (dup/interpolation/inspect)
+        # so a logs_before_send callback can mutate it without touching frozen
+        # app strings.
+        def stringify(message)
+          case message
+          when String
+            message.dup
+          when Exception
+            "#{message.message} (#{message.class})\n#{Array(message.backtrace).join("\n")}"
+          else
+            message.inspect
+          end
+        end
+
+        def attributes_for(progname)
+          attributes = {}
+          # Ruby's progname is the closest analog to the OTel-world "logger name";
+          # logger.name is the key users coming from other ecosystems will expect.
+          attributes['logger.name'] = progname.to_s if progname
+
+          context = Internal::Context.current
+          return attributes unless context
+
+          attributes['posthogDistinctId'] = context.distinct_id if context.distinct_id
+          attributes['sessionId'] = context.session_id if context.session_id
+
+          properties = context.properties || {}
+          REQUEST_ATTRIBUTE_NAMES.each do |key, attribute_name|
+            value = properties[key] || properties[key.to_sym]
+            attributes[attribute_name] = value if value
+          end
+
+          attributes
+        end
+
+        def self_log?(message, progname)
+          return true if progname.to_s == SELF_LOG_PROGNAME
+
+          # PrefixedLogger always places the prefix at the start of the message,
+          # so start_with? suffices and avoids suppressing app logs that merely
+          # mention the SDK mid-string.
+          message.is_a?(String) && message.start_with?(SELF_LOG_PREFIX)
+        end
+      end
+    end
+  end
+end

data/lib/posthog/rails/logs/rate_limiter.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module PostHog
+  module Rails
+    module Logs
+      # Fixed-window rate limiter protecting the PostHog Logs ingestion quota
+      # from runaway log volume (PostHog Logs bills by data ingested).
+      #
+      # Thread-safe: the counter is the one piece of shared mutable state in
+      # the logs pipeline, guarded by a mutex scoped to a counter bump.
+      #
+      # @api private
+      class RateLimiter
+        WINDOW_SECONDS = 60
+
+        # @return [Integer] Maximum records allowed per window.
+        attr_reader :limit
+
+        # @param limit [Integer] Maximum records allowed per {WINDOW_SECONDS} window.
+        def initialize(limit)
+          @limit = limit
+          @mutex = Mutex.new
+          @window = nil
+          @count = 0
+        end
+
+        # Records one attempt and returns the verdict.
+        #
+        # @return [Symbol] :allow when under the cap, :reject_first for the
+        #   first rejection of a window (callers may emit a single notice),
+        #   :reject thereafter.
+        def record
+          @mutex.synchronize do
+            window = Process.clock_gettime(Process::CLOCK_MONOTONIC).to_i / WINDOW_SECONDS
+            if window != @window
+              @window = window
+              @count = 0
+            end
+            @count += 1
+            next :allow if @count <= @limit
+
+            @count == @limit + 1 ? :reject_first : :reject
+          end
+        end
+      end
+    end
+  end
+end

data/lib/posthog/rails/logs/setup.rb

@@ -0,0 +1,256 @@
+# frozen_string_literal: true
+
+require 'logger'
+require 'posthog/logging'
+require 'posthog/rails/configuration'
+require 'posthog/rails/logs/appender'
+require 'posthog/rails/logs/rate_limiter'
+
+module PostHog
+  module Rails
+    module Logs
+      # Bootstraps the OpenTelemetry logs pipeline that ships PostHog Logs.
+      #
+      # The OpenTelemetry gems are optional/soft dependencies. They are required
+      # lazily here so that apps which do not enable logs (or run on a Ruby
+      # version the logs SDK does not support) are unaffected.
+      #
+      # @api private
+      module Setup
+        # Bounds the at_exit flush. Without a timeout, the batch processor
+        # joins its worker thread unbounded and the exporter retries each
+        # batch with backoff — during an outage that can eat the whole
+        # SIGTERM grace period and starve the events client of its flush.
+        SHUTDOWN_TIMEOUT_SECONDS = 2
+
+        class << self
+          # @return [OpenTelemetry::SDK::Logs::LoggerProvider, nil]
+          attr_reader :provider
+
+          # @return [PostHog::Rails::Logs::Appender, nil]
+          attr_reader :appender
+
+          # Build the logs pipeline and return the broadcastable appender.
+          #
+          # Idempotent: subsequent calls return the previously built appender
+          # (or nil if setup was skipped).
+          #
+          # @return [PostHog::Rails::Logs::Appender, nil]
+          def install
+            return @appender if @installed
+
+            @installed = true
+
+            # Respect the core client's test_mode: when it is on, the client
+            # swaps in a NoopWorker so events never ship, and the logs pipeline
+            # should likewise stay off so test suites don't emit real records.
+            # Intentional state, so skip quietly (no warning).
+            return nil if @client_test_mode
+
+            return nil unless require_otel_gems
+
+            config = PostHog::Rails.config
+            token = resolve_token
+            if token.nil?
+              warn_once(
+                'PostHog Logs enabled but no project token could be resolved ' \
+                '(set config.api_key or POSTHOG_API_KEY); skipping.'
+              )
+              return nil
+            end
+
+            @provider = build_provider(token)
+            otel_logger = @provider.logger(name: 'posthog-rails', version: PostHog::VERSION)
+            level = resolve_level(config.logs_level) || rails_logger_level
+            @appender = Appender.new(
+              otel_logger,
+              level: level,
+              rate_limiter: build_rate_limiter(config),
+              before_send: config.logs_before_send
+            )
+          rescue StandardError => e
+            warn_once("Failed to initialize PostHog Logs: #{e.message}")
+            nil
+          end
+
+          # Shut the pipeline down, flushing buffered records.
+          #
+          # @param timeout [Numeric] Max seconds to spend; see {SHUTDOWN_TIMEOUT_SECONDS}.
+          # @return [void]
+          def shutdown(timeout: SHUTDOWN_TIMEOUT_SECONDS)
+            @provider&.shutdown(timeout: timeout)
+          rescue StandardError => e
+            logger.warn("Error shutting down PostHog Logs: #{e.message}")
+          end
+
+          # Remembers the api_key/host the PostHog client was initialized with
+          # (called by PostHog.init) so the logs pipeline can reuse them without
+          # the core client exposing public readers.
+          #
+          # @api private
+          # @param options [Hash] The options passed to {PostHog::Client.new}.
+          # @return [void]
+          def remember_client_options(options)
+            return unless options.is_a?(Hash)
+
+            @client_api_key = options[:api_key] || options['api_key']
+            @client_host = options[:host] || options['host']
+            @client_test_mode = options[:test_mode] || options['test_mode']
+          end
+
+          # Resets memoized state. Intended for tests.
+          #
+          # @return [void]
+          def reset
+            @installed = false
+            @provider = nil
+            @appender = nil
+            @warned = false
+            @client_api_key = nil
+            @client_host = nil
+            @client_test_mode = nil
+          end
+
+          private
+
+          # The logs token is the same project token the core client uses
+          # (i.e. config.api_key, captured by PostHog.init), falling back to
+          # ENV['POSTHOG_API_KEY'].
+          def resolve_token
+            normalize(@client_api_key) || normalize(ENV.fetch('POSTHOG_API_KEY', nil))
+          end
+
+          # The logs host follows the core client's configured host (captured by
+          # PostHog.init), falling back to ENV['POSTHOG_HOST'] and finally the
+          # US cloud endpoint.
+          def resolve_host
+            normalize(@client_host) ||
+              normalize(ENV.fetch('POSTHOG_HOST', nil)) ||
+              'https://us.i.posthog.com'
+          end
+
+          # nil, 0, and negative values intentionally disable the cap. Numeric
+          # strings (e.g. from ENV) are coerced — deliberately via Integer()
+          # rather than to_i, since "abc".to_i == 0 would silently disable the
+          # cap. Unparseable values warn and fall back to the default cap:
+          # a misconfiguration should not switch the protection off.
+          def build_rate_limiter(config)
+            raw = config.logs_max_records_per_minute
+            return nil if raw.nil?
+
+            limit = Integer(raw, exception: false)
+            if limit.nil?
+              logger.warn(
+                "logs_max_records_per_minute=#{raw.inspect} is not a number; using the default cap " \
+                "of #{Configuration::DEFAULT_LOGS_MAX_RECORDS_PER_MINUTE} records/minute"
+              )
+              limit = Configuration::DEFAULT_LOGS_MAX_RECORDS_PER_MINUTE
+            end
+            return nil unless limit.positive?
+
+            RateLimiter.new(limit)
+          end
+
+          def require_otel_gems
+            require 'opentelemetry-sdk'
+            require 'opentelemetry-logs-sdk'
+            require 'opentelemetry/exporter/otlp_logs'
+            true
+          rescue LoadError => e
+            warn_once(
+              "PostHog Logs enabled but the OpenTelemetry gems are missing (#{e.message}). " \
+              "Add 'opentelemetry-sdk', 'opentelemetry-logs-sdk', and " \
+              "'opentelemetry-exporter-otlp-logs' (each with require: false) to your Gemfile " \
+              'to enable log forwarding.'
+            )
+            false
+          end
+
+          def build_provider(token)
+            resource = OpenTelemetry::SDK::Resources::Resource.create(resource_attributes)
+            provider = OpenTelemetry::SDK::Logs::LoggerProvider.new(resource: resource)
+            exporter = OpenTelemetry::Exporter::OTLP::Logs::LogsExporter.new(
+              endpoint: logs_endpoint(resolve_host),
+              headers: { 'Authorization' => "Bearer #{token}" }
+            )
+            processor = OpenTelemetry::SDK::Logs::Export::BatchLogRecordProcessor.new(exporter)
+            provider.add_log_record_processor(processor)
+            provider
+          end
+
+          def resource_attributes
+            # service.version is intentionally omitted. Per OpenTelemetry semantic
+            # conventions it is the deployed application's version, not this gem's.
+            # The posthog-rails name/version travel with each record via the
+            # instrumentation scope (see LoggerProvider#logger above).
+            {
+              'service.name' => service_name,
+              'deployment.environment' => ::Rails.env.to_s
+            }
+          end
+
+          def service_name
+            app = ::Rails.application
+            return 'unknown_service' unless app
+
+            name = app.class.respond_to?(:module_parent_name) ? app.class.module_parent_name : nil
+            name && !name.empty? ? name.to_s : 'unknown_service'
+          rescue StandardError
+            'unknown_service'
+          end
+
+          def logs_endpoint(host)
+            base = (host || 'https://us.i.posthog.com').to_s.sub(%r{/+\z}, '')
+            "#{base}/i/v1/logs"
+          end
+
+          def resolve_level(level)
+            return nil if level.nil?
+            return level if level.is_a?(Integer)
+
+            # const_get can return non-severity values without raising: Logger's
+            # own VERSION/SEV_LABEL, and (via the default inherited lookup) any
+            # top-level all-caps constant like ENV/ARGV/STDOUT. The Integer guard
+            # rejects them so they don't later blow up the severity comparison.
+            # (inherit must stay true — the severity constants live in the
+            # included Logger::Severity module.)
+            result = ::Logger.const_get(level.to_s.upcase)
+            raise NameError, 'not a severity integer' unless result.is_a?(Integer)
+
+            result
+          rescue NameError
+            warn_once(
+              "Invalid logs_level #{level.inspect}; expected one of :debug, :info, :warn, " \
+              ':error, :fatal, :unknown (or an Integer). Falling back to the Rails logger level.'
+            )
+            nil
+          end
+
+          def rails_logger_level
+            ::Rails.logger&.level
+          rescue StandardError
+            nil
+          end
+
+          def normalize(value)
+            return nil unless value.is_a?(String)
+
+            stripped = value.strip
+            stripped.empty? ? nil : stripped
+          end
+
+          def warn_once(message)
+            return if @warned
+
+            @warned = true
+            logger.warn(message)
+          end
+
+          def logger
+            PostHog::Logging.logger
+          end
+        end
+      end
+    end
+  end
+end

data/lib/posthog/rails/logs/severity.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+module PostHog
+  module Rails
+    module Logs
+      # Maps Ruby `Logger` severities to OpenTelemetry log severity numbers and text.
+      #
+      # OpenTelemetry defines severity ranges (DEBUG=5-8, INFO=9-12, WARN=13-16,
+      # ERROR=17-20, FATAL=21-24); we map each Ruby level to the base of its range.
+      #
+      # @api private
+      module Severity
+        module_function
+
+        # @param severity [Integer, nil] A Ruby `Logger` severity constant.
+        # @return [Symbol] The severity name (:debug, :info, :warn, :error, :fatal).
+        def name_for(severity)
+          NAMES.fetch(severity, :info)
+        end
+
+        # @param name [Symbol, String, nil] A severity name such as :warn.
+        # @return [Array(Integer, String)] OpenTelemetry severity number and text;
+        #   unrecognized names fall back to INFO.
+        def for_name(name)
+          OTEL.fetch(name.to_s.downcase.to_sym, OTEL[:info])
+        end
+
+        NAMES = {
+          ::Logger::DEBUG => :debug,
+          ::Logger::INFO => :info,
+          ::Logger::WARN => :warn,
+          ::Logger::ERROR => :error,
+          ::Logger::FATAL => :fatal,
+          ::Logger::UNKNOWN => :info
+        }.freeze
+
+        OTEL = {
+          debug: [5, 'DEBUG'],
+          info: [9, 'INFO'],
+          warn: [13, 'WARN'],
+          error: [17, 'ERROR'],
+          fatal: [21, 'FATAL']
+        }.freeze
+      end
+    end
+  end
+end

data/lib/posthog/rails/railtie.rb

@@ -34,8 +34,21 @@ module PostHog
                 options = config.to_client_options
               end
 
-              # Create the PostHog client
+              # Let the PostHog Logs pipeline reuse the same api_key/host without
+              # the core client exposing public readers.
+              PostHog::Rails::Logs::Setup.remember_client_options(options) if defined?(PostHog::Rails::Logs::Setup)
+
+              # Create the PostHog client. If a client already exists, shut it down
+              # after replacement so repeated init calls do not leave background
+              # resources from the previous instance running.
+              previous_client = @client
               @client = PostHog::Client.new(options)
+              begin
+                previous_client&.shutdown
+              rescue StandardError => e
+                PostHog::Logging.logger.warn("Failed to shut down previous PostHog client: #{e.message}")
+              end
+              @client
             end
 
             # Define delegated methods using metaprogramming
@@ -118,12 +131,20 @@ module PostHog
         register_error_subscriber if rails_version_above_7?
       end
 
+      # Opt-in: forward logs to PostHog Logs over OTLP
+      config.after_initialize do
+        install_posthog_logs if PostHog::Rails.config&.logs_enabled
+      end
+
       # Ensure PostHog shuts down gracefully (register only once)
       config.after_initialize do
         next if @posthog_at_exit_registered
 
         @posthog_at_exit_registered = true
-        at_exit { PostHog.client&.shutdown if PostHog.initialized? }
+        at_exit do
+          PostHog::Rails::Logs::Setup.shutdown
+          PostHog.client&.shutdown if PostHog.initialized?
+        end
       end
 
       # @api private
@@ -144,6 +165,54 @@ module PostHog
         app.config.middleware.insert_before(target, middleware)
       end
 
+      # Build the PostHog Logs pipeline and broadcast Rails.logger into it.
+      #
+      # @api private
+      # @return [void]
+      def self.install_posthog_logs
+        unless PostHog.initialized?
+          # logs_enabled is an explicit opt-in, so leave a breadcrumb instead
+          # of silently skipping when PostHog.init never ran.
+          PostHog::Logging.logger.warn(
+            'PostHog Logs is enabled but PostHog.init has not been called; ' \
+            'skipping log forwarding. Call PostHog.init in your initializer.'
+          )
+          return
+        end
+
+        # Mirror the core client: when it is disabled (missing/blank api_key)
+        # every capture no-ops, so log forwarding should stay off too. The
+        # client already logs its own missing-api_key error, so skip quietly.
+        return unless PostHog.client.enabled?
+
+        appender = PostHog::Rails::Logs::Setup.install
+        return if appender.nil?
+
+        broadcast_rails_logger(appender) if PostHog::Rails.config&.logs_forward_rails_logger
+      rescue StandardError => e
+        PostHog::Logging.logger.warn("Failed to set up PostHog Logs: #{e.message}")
+      end
+
+      # Attach the appender to Rails.logger, supporting both the Rails 7.1+
+      # BroadcastLogger and the older ActiveSupport::Logger.broadcast mechanism.
+      #
+      # @api private
+      # @return [void]
+      def self.broadcast_rails_logger(appender)
+        logger = ::Rails.logger
+        return unless logger
+
+        if logger.respond_to?(:broadcast_to)
+          logger.broadcast_to(appender)
+        elsif defined?(ActiveSupport::Logger) && ActiveSupport::Logger.respond_to?(:broadcast)
+          logger.extend(ActiveSupport::Logger.broadcast(appender))
+        else
+          PostHog::Logging.logger.warn(
+            'PostHog Logs could not broadcast Rails.logger; no compatible broadcast mechanism found.'
+          )
+        end
+      end
+
       # @api private
       # @return [void]
       def self.register_error_subscriber

data/lib/posthog/rails.rb

@@ -8,6 +8,10 @@ require 'posthog/rails/capture_exceptions'
 require 'posthog/rails/rescued_exception_interceptor'
 require 'posthog/rails/active_job'
 require 'posthog/rails/error_subscriber'
+require 'posthog/rails/logs/severity'
+require 'posthog/rails/logs/rate_limiter'
+require 'posthog/rails/logs/appender'
+require 'posthog/rails/logs/setup'
 require 'posthog/rails/railtie'
 
 module PostHog

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: posthog-rails
 version: !ruby/object:Gem::Version
-  version: 3.11.1
+  version: 3.12.1
 platform: ruby
 authors:
 - PostHog
@@ -29,14 +29,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.11'
+        version: '3.12'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.11'
+        version: '3.12'
 description: Automatic exception tracking and instrumentation for Ruby on Rails applications
   using PostHog
 email: engineering@posthog.com
@@ -52,6 +52,10 @@ files:
 - lib/posthog/rails/capture_exceptions.rb
 - lib/posthog/rails/configuration.rb
 - lib/posthog/rails/error_subscriber.rb
+- lib/posthog/rails/logs/appender.rb
+- lib/posthog/rails/logs/rate_limiter.rb
+- lib/posthog/rails/logs/setup.rb
+- lib/posthog/rails/logs/severity.rb
 - lib/posthog/rails/parameter_filter.rb
 - lib/posthog/rails/railtie.rb
 - lib/posthog/rails/request_context.rb