feat(rails): forward Rails.logger to PostHog Logs via OpenTelemetry by johnnagro · Pull Request #167 · PostHog/posthog-ruby

johnnagro · 2026-06-04T18:30:54Z

💡 Motivation and Context

Adds an opt-in integration that forwards Rails.logger output to PostHog Logs
(https://posthog.com/docs/logs) over OpenTelemetry/OTLP, automatically correlated
with the request's distinct_id and session_id captured by the existing
request-context middleware.
The OpenTelemetry gems are optional/soft dependencies loaded lazily, so the
feature no-ops with a single warning when absent (and on Ruby < 3.3 where the
logs SDK is unsupported). The logs token and host are derived from the configured
client (config.api_key / config.host) with ENV fallbacks, so logs always
target the same project as analytics. Disabled by default; enabled via
PostHog::Rails.config.logs_enabled.

💚 How did you test it?

Unit specs for the appender, setup (gems present/absent + token/host resolution),
and railtie broadcast wiring (full suite green on Ruby 3.2.2, rubocop clean).
End-to-end in an ephemeral rails new app against a real PostHog project:
Rails.logger output appears in PostHog Logs.

📝 Checklist

I reviewed the submitted code.
I added tests to verify the changes.
I updated the docs if needed.
No breaking change or entry added to the changelog.

greptile-apps · 2026-06-04T18:35:13Z

Prompt To Fix All With AI

Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 2
posthog-rails/lib/posthog/rails/logs/setup.rb:136-140
The `service.version` OTel resource attribute is being set to `PostHog::VERSION`, which is the SDK/integration gem version — not the Rails application's version. Per OpenTelemetry semantic conventions, `service.version` represents the deployed application version, so this would cause every service to report the PostHog gem version as its "version" in PostHog Logs. Consider using `telemetry.sdk.version` for the SDK version instead, and omitting `service.version` from the defaults (users can supply it via `logs_resource_attributes`).

```suggestion
            attrs = {
              'service.name' => service_name,
              'telemetry.sdk.name' => 'posthog-rails',
              'telemetry.sdk.version' => PostHog::VERSION,
              'deployment.environment' => ::Rails.env.to_s
            }
```

### Issue 2 of 2
spec/posthog/rails/logs/appender_spec.rb:40-46
Non-parametric severity tests per project convention — `Severity::MAPPING` defines 6 entries (DEBUG→5, INFO→9, WARN→13, ERROR→17, FATAL→21, UNKNOWN→9) but only INFO and ERROR are verified. An RSpec `using` table (e.g., a `described_class` parametric approach with `let`/`subject` per row, or a shared example loop over `MAPPING`) would cover all cases with no duplication and catch a mapping regression for WARN, FATAL, or the UNKNOWN→INFO fallback.

_{Reviews (1): Last reviewed commit: "feat(rails): forward Rails.logger to Pos..." | Re-trigger Greptile}

turnipdabeets · 2026-06-04T18:41:22Z

Cc @PostHog/logs

johnnagro · 2026-06-10T22:58:56Z

Thanks for taking the time to look this over and leave such thoughtful comments, I appreciate it @turnipdabeets @DanielVisca

I made some changes based on your feedback. There is one open question about feature flags.

turnipdabeets · 2026-06-11T21:09:02Z

+          record = apply_before_send(record)
+          return if record.nil?
+
+          @otel_logger.on_emit(**record)


Can we include traceId/spanId? The other SDKs' log records carry the trace fields, and the OTel logs SDK's on_emit should resolve the current active span from ambient context (or an explicit context: argument) — so apps already running OTel tracing may get logs↔trace correlation for free here. Worth verifying against our gem versions: if it already works; if not, it's likely a one-line context: argument.

Okay so, this "just works", I verified it against the source: on_emit defaults context: OpenTelemetry::Context.current and fills the top-level trace_id/span_id/trace_flags from the active span (https://github.com/open-telemetry/opentelemetry-ruby/blob/main/logs_sdk/lib/opentelemetry/sdk/logs/logger.rb). Apps that run the tracing instrumentation gems (opentelemetry-instrumentation-rails/-rack) get logs↔trace correlation for free; since our appender emits synchronously on the calling thread, the ambient context is the traced request's own.

My smoke test has no tracer, so the trace fields are empty as expected:

I did add a line to the README documenting that traced requests get trace_id/span_id on their log records automatically.

Thoughts?

I think as it's document that the tracing instrumentation gems are needed it should be ok. Ideally down the road we'd populate trace context ourselves so no extra gems are needed.

turnipdabeets · 2026-06-11T21:18:03Z

PR is looking really good. We'll also need a .changeset file for release automation system to run

johnnagro · 2026-06-12T02:13:49Z

thanks, @turnipdabeets - please take another look

turnipdabeets · 2026-06-12T14:16:17Z

@johnnagro "Commits must have verified signatures" in order to merge - mind signing these?

Add an opt-in integration that broadcasts Rails.logger output to PostHog Logs over OTLP, automatically correlated with the request's distinct_id and session_id captured by the existing request-context middleware. The OpenTelemetry gems (opentelemetry-sdk, opentelemetry-logs-sdk, opentelemetry-exporter-otlp-logs) are optional/soft dependencies loaded lazily at runtime, so the feature no-ops with a single warning when they are absent (and on Ruby < 3.3 where the logs SDK is unsupported). The logs token and host are derived from the configured PostHog client (config.api_key / config.host) with ENV fallbacks, so logs always target the same project as analytics. Exposes api_key/host readers on the core client to support this. Disabled by default; enable via PostHog::Rails.config.logs_enabled.

…ient readers

…ression

…r-minute rate

…ogs records

Co-authored-by: Anna Garcia <11654201+turnipdabeets@users.noreply.github.com>

…nvention

…ng OTel tracing

…nd record hash

…ds don't consume budget

…l.path) for log request attributes

…fety

…ad of silently dropping

…tly disabling it

…gems

…t starve the events flush

…gger for prefix consistency

…service metadata

…ecords

…he Rails logger level

…icates and level= are unaffected; document silence/tagged gaps

… fails persistently

…art through the logs pipeline

…arding

…t path

johnnagro · 2026-06-12T14:55:57Z

@johnnagro "Commits must have verified signatures" in order to merge - mind signing these?

np - signed.

…el-logs # Conflicts: # posthog-rails/README.md

dustinbyrne

Hey @johnnagro, thanks for this! I took a look and have a few comments, but otherwise this is looking pretty solid

dustinbyrne · 2026-06-12T16:18:56Z

+          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']
+          end


We should also consider test_mode here so that we don't emit logs in test

posthog-ruby/posthog-rails/lib/generators/posthog/templates/posthog.rb

Lines 111 to 112 in 0ab6692

# Disable in test environment

config.test_mode = true if Rails.env.test?

dustinbyrne · 2026-06-12T16:27:48Z

+        def body_for(message)
+          str = message.is_a?(String) ? message.dup : message.inspect
+          str = str.encode(Encoding::UTF_8, invalid: :replace, undef: :replace) unless str.encoding == Encoding::UTF_8
+          str.valid_encoding? ? str : str.scrub
+        end


If logging an exception, e.g.:

Rails.logger.error(ex)

It'll render as something like <#RuntimeError: unknown error occurred> instead of including the backtrace

we should consider doing something like Logger::Formatter#msg2str

dustinbyrne · 2026-06-12T16:42:03Z

+          def install!
+            return @appender if @installed
+
+            @installed = true
+            return nil unless require_otel_gems


Worth checking here if the PostHog client is disabled and skipping installation if it is

We have this pattern in a lot of methods internal to the client:

posthog-ruby/lib/posthog/client.rb

Lines 293 to 294 in 0ab6692

def capture_exception(exception, distinct_id = nil, additional_properties = {}, flags: nil)

return false if @disabled

posthog-ruby/lib/posthog/client.rb

Lines 208 to 209 in 0ab6692

def capture(attrs)

return false if @disabled

@disabled isn't exposed, but I think it's fine to expose it as a public method. Maybe we opt for the positive case, though - client.enabled?

dustinbyrne · 2026-06-12T16:56:12Z

+          #
+          # @param timeout [Numeric] Max seconds to spend; see {SHUTDOWN_TIMEOUT_SECONDS}.
+          # @return [void]
+          def shutdown!(timeout: SHUTDOWN_TIMEOUT_SECONDS)


nit considering this is private API space, but I think we should prefer a non-bang method name here (just shutdown)

it doesn't have a non-bang form, and it's not at risk of raising an exception

install! maybe has a stronger case given it's highly state changing, but I think we could do a non-bang there too

dustinbyrne · 2026-06-12T17:22:46Z

  gem 'oj', '~> 3.16.10'
+  # Soft dependency of posthog-rails' PostHog Logs feature; present here only
+  # so the fork-safety spec can exercise the real BatchLogRecordProcessor.
+  gem 'opentelemetry-logs-sdk', require: false


I tried running this as is, and got the following error

OpenTelemetry error: unexpected error in OTLP::Exporter#encode - undefined method 'event_name' for an instance of OpenTelemetry::SDK::Logs::LogRecordData

My lockfile resolved to:

opentelemetry-logs-sdk 0.4.0 opentelemetry-exporter-otlp-logs 0.5.1

and it looks like the exporter expects log_record_data.event_name to exist, but opentelemetry-logs-sdk v0.4.0 defines LogRecordData without an event_name field.

a fresh bundle with the following fixed it:

gem 'opentelemetry-sdk', require: false # resolved to 0.6.0 gem 'opentelemetry-logs-sdk', require: false gem 'opentelemetry-exporter-otlp-logs', require: false # resolved to 0.5.1

maybe we use something like this?

Suggested change

gem 'opentelemetry-logs-sdk', require: false

gem 'opentelemetry-logs-sdk', '>= 0.6.0', require: false

gem 'opentelemetry-exporter-otlp-logs', require: false

might be worth a test using real exports from these libs

johnnagro requested a review from a team as a code owner June 4, 2026 18:30

greptile-apps Bot reviewed Jun 4, 2026

View reviewed changes

Comment thread posthog-rails/lib/posthog/rails/logs/setup.rb Outdated

Comment thread spec/posthog/rails/logs/appender_spec.rb Outdated

turnipdabeets reviewed Jun 9, 2026

View reviewed changes

johnnagro requested review from DanielVisca and turnipdabeets June 10, 2026 22:57

turnipdabeets reviewed Jun 11, 2026

View reviewed changes

johnnagro requested a review from turnipdabeets June 12, 2026 02:12

turnipdabeets requested review from dustinbyrne and rafaeelaudibert June 12, 2026 13:35

turnipdabeets reviewed Jun 12, 2026

View reviewed changes

Comment thread posthog-rails/lib/posthog/rails/logs/severity.rb Outdated

johnnagro and others added 14 commits June 12, 2026 10:49

fix(rails): drop incorrect service.version OTel resource attribute

ef893c9

test(rails): cover all severity mappings in appender spec

33ba5e7

refactor(rails): capture init options for logs instead of exposing cl…

921777c

…ient readers

docs(rails): document Appender's lock-free thread-safety design

c29ffe5

fix(rails): match self-log prefix with start_with? to avoid over-supp…

fd95ed4

…ression

feat(rails): cap PostHog Logs forwarding at a configurable records-pe…

ca3c155

…r-minute rate

feat(rails): add logs_before_send callback to scrub or drop PostHog L…

0b07c9b

…ogs records

Update posthog-rails/lib/posthog/rails/logs/appender.rb

532165a

Co-authored-by: Anna Garcia <11654201+turnipdabeets@users.noreply.github.com>

fix: fallback to 'unknown_service' rather than 'rails'

8b45826

fix(rails): emit progname as logger.name to match OTel logger-name co…

e382f3c

…nvention

docs(rails): note automatic trace_id/span_id correlation for apps usi…

b5836cd

…ng OTel tracing

refactor(rails): expose a single :severity enum in the logs_before_se…

318e7d3

…nd record hash

fix(rails): run logs_before_send before the rate cap so dropped recor…

8329bf4

…ds don't consume budget

johnnagro added 16 commits June 12, 2026 10:49

fix(rails): use OTel semconv names (url.full, http.request.method, ur…

c29da56

…l.path) for log request attributes

test(rails): cover body UTF-8 normalization and before_send string sa…

0c8a179

…fety

fix(rails): warn when logs_before_send returns a non-Hash value inste…

bf8d01e

…ad of silently dropping

fix(rails): coerce numeric strings for logs rate cap instead of silen…

6f338b7

…tly disabling it

docs(rails): recommend require: false for the optional OpenTelemetry …

be99a7c

…gems

fix(rails): warn when logs are enabled but PostHog.init never ran

059d712

fix(rails): bound the at_exit logs flush with a 2s timeout so it can'…

100bdf5

…t starve the events flush

refactor(rails): rename forward_rails_logger to logs_forward_rails_lo…

a148692

…gger for prefix consistency

Remove logs_resource_attributes config; resource attrs are now fixed …

84bfd61

…service metadata

Remove unused Setup.force_flush; shutdown! already flushes buffered r…

9bcd5ad

…ecords

Warn once on invalid logs_level instead of silently falling back to t…

e7f1f83

…he Rails logger level

Keep forwarding threshold out of Logger#level so BroadcastLogger pred…

b5267ac

…icates and level= are unaffected; document silence/tagged gaps

Guard Appender#add against re-entrant logging and warn once when emit…

4687427

… fails persistently

Add fork-safety spec pinning BatchLogRecordProcessor's post-fork rest…

9f527a3

…art through the logs pipeline

feat(rails): add changeset and fork-safety spec for PostHog Logs forw…

87b49fc

…arding

Remove unused Severity.for; name_for and for_name cover the split emi…

ce9ca0e

…t path

johnnagro force-pushed the feat/posthog-rails-otel-logs branch from dddc3a8 to ce9ca0e Compare June 12, 2026 14:53

Merge remote-tracking branch 'origin/main' into feat/posthog-rails-ot…

1dfe9a8

…el-logs # Conflicts: # posthog-rails/README.md

johnnagro requested a review from turnipdabeets June 12, 2026 17:36

dustinbyrne reviewed Jun 12, 2026

View reviewed changes

	# Disable in test environment
	config.test_mode = true if Rails.env.test?

	def capture_exception(exception, distinct_id = nil, additional_properties = {}, flags: nil)
	return false if @disabled

	gem 'opentelemetry-logs-sdk', require: false
	gem 'opentelemetry-logs-sdk', '>= 0.6.0', require: false
	gem 'opentelemetry-exporter-otlp-logs', require: false

Conversation

johnnagro commented Jun 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

💡 Motivation and Context

💚 How did you test it?

📝 Checklist

Uh oh!

greptile-apps Bot commented Jun 4, 2026

Uh oh!

Uh oh!

Uh oh!

turnipdabeets commented Jun 4, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

johnnagro commented Jun 10, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

johnnagro Jun 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

turnipdabeets commented Jun 11, 2026

Uh oh!

johnnagro commented Jun 12, 2026

Uh oh!

Uh oh!

turnipdabeets commented Jun 12, 2026

Uh oh!

johnnagro commented Jun 12, 2026

Uh oh!

dustinbyrne left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

johnnagro commented Jun 4, 2026 •

edited

Loading

johnnagro Jun 12, 2026 •

edited

Loading