Module: PostHog::Rails::Logs::Setup Private

Defined in:
lib/posthog/rails/logs/setup.rb

Overview

This module is part of a private API. You should avoid using this module if possible, as it may be removed or be changed in the future.

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.

Constant Summary collapse

SHUTDOWN_TIMEOUT_SECONDS =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

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.

2

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.appender ⇒ PostHog::Rails::Logs::Appender? (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns:



31
32
33
 
# File 'lib/posthog/rails/logs/setup.rb', line 31

def appender
  @appender
end

.provider ⇒ OpenTelemetry::SDK::Logs::LoggerProvider? (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns:

  • (OpenTelemetry::SDK::Logs::LoggerProvider, nil) 


28
29
30
 
# File 'lib/posthog/rails/logs/setup.rb', line 28

def provider
  @provider
end

Class Method Details

.install ⇒ PostHog::Rails::Logs::Appender?

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Build the logs pipeline and return the broadcastable appender.

Idempotent: subsequent calls return the previously built appender (or nil if setup was skipped).

Returns:



39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
 
# File 'lib/posthog/rails/logs/setup.rb', line 39

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

.remember_client_options(options) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

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.

Parameters:

  • options (Hash) —

    The options passed to Client.new.



93
94
95
96
97
98
99
 
# File 'lib/posthog/rails/logs/setup.rb', line 93

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

.reset ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Resets memoized state. Intended for tests.



104
105
106
107
108
109
110
111
112
 
# File 'lib/posthog/rails/logs/setup.rb', line 104

def reset
  @installed = false
  @provider = nil
  @appender = nil
  @warned = false
  @client_api_key = nil
  @client_host = nil
  @client_test_mode = nil
end

.shutdown(timeout: SHUTDOWN_TIMEOUT_SECONDS) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Shut the pipeline down, flushing buffered records.

Parameters:



80
81
82
83
84
 
# File 'lib/posthog/rails/logs/setup.rb', line 80

def shutdown(timeout: SHUTDOWN_TIMEOUT_SECONDS)
  @provider&.shutdown(timeout: timeout)
rescue StandardError => e
  logger.warn("Error shutting down PostHog Logs: #{e.message}")
end