Make Sentry logs opt-in and update deployment docs

Author: gildesmarais

README.md

@@ -48,9 +48,10 @@ This trial run is intentionally minimal. Use Docker Compose for Browserless, aut
 ## Deploy (Docker Compose)
 
 1. Generate a key: `openssl rand -hex 32`.
-2. Export `HTML2RSS_SECRET_KEY`, `HEALTH_CHECK_TOKEN`, `BROWSERLESS_IO_API_TOKEN`, `BUILD_TAG`, and `GIT_SHA` in your shell or `.env`.
-3. Optionally export `SENTRY_DSN` to send application errors and structured logs to Sentry.
-4. Start: `docker-compose up`.
+2. Export `HTML2RSS_SECRET_KEY`, `HEALTH_CHECK_TOKEN`, and `BROWSERLESS_IO_API_TOKEN` in your shell or `.env`.
+3. Optionally export `SENTRY_DSN` to send application errors to Sentry.
+4. Optionally export `SENTRY_ENABLE_LOGS=true` to forward structured application logs to Sentry.
+5. Start: `docker-compose up`.
 
 UI + API run on `http://localhost:4000`. The app exits if the secret key is missing.
 

app/web/boot/sentry.rb

@@ -35,7 +35,7 @@ def initialize_sentry!
           def apply_settings(config)
             config.dsn = RuntimeEnv.sentry_dsn
             config.environment = RuntimeEnv.rack_env
-            config.enable_logs = true
+            config.enable_logs = RuntimeEnv.sentry_logs_enabled?
             config.send_default_pii = false
             config.release = release_name
           end

app/web/config/runtime_env.rb

@@ -7,7 +7,7 @@ module Web
     # from the process environment after validation.
     module RuntimeEnv
       SENSITIVE_KEYS = %w[HTML2RSS_SECRET_KEY HEALTH_CHECK_TOKEN SENTRY_DSN].freeze
-      BOOT_METADATA_KEYS = %w[BUILD_TAG GIT_SHA RACK_ENV].freeze
+      BOOT_METADATA_KEYS = %w[BUILD_TAG GIT_SHA RACK_ENV SENTRY_ENABLE_LOGS].freeze
 
       class << self
         # @return [void]
@@ -42,6 +42,11 @@ def sentry_enabled?
           !sentry_dsn.to_s.strip.empty?
         end
 
+        # @return [Boolean]
+        def sentry_logs_enabled?
+          parse_boolean(fetch('SENTRY_ENABLE_LOGS', 'false'), default: false)
+        end
+
         # @return [String]
         def build_tag
           fetch('BUILD_TAG', 'unknown')
@@ -86,6 +91,18 @@ def scrub_sensitive_env!
           SENSITIVE_KEYS.each { |key| ENV.delete(key) }
           nil
         end
+
+        # @param value [Object]
+        # @param default [Boolean]
+        # @return [Boolean]
+        def parse_boolean(value, default:)
+          normalized = value.to_s.strip.downcase
+          return true if normalized == 'true'
+          return false if normalized == 'false'
+          return default if normalized.empty?
+
+          raise ArgumentError, "Malformed env 'SENTRY_ENABLE_LOGS': expected true/false, got '#{value}'"
+        end
       end
     end
   end

docker-compose.yml

@@ -18,6 +18,7 @@ services:
       HTML2RSS_SECRET_KEY: ${HTML2RSS_SECRET_KEY:?set HTML2RSS_SECRET_KEY}
       HEALTH_CHECK_TOKEN: ${HEALTH_CHECK_TOKEN:?set HEALTH_CHECK_TOKEN}
       SENTRY_DSN: ${SENTRY_DSN:-}
+      SENTRY_ENABLE_LOGS: ${SENTRY_ENABLE_LOGS:-false}
       BROWSERLESS_IO_WEBSOCKET_URL: ws://browserless:4002
       BROWSERLESS_IO_API_TOKEN: ${BROWSERLESS_IO_API_TOKEN:?set BROWSERLESS_IO_API_TOKEN}
     # Trial runs use the image's bundled config/feeds.yml.

docs/README.md

@@ -171,6 +171,7 @@ Managed flags and environment keys:
 | `build_tag`                       | `BUILD_TAG`                       | string         | `unknown` outside production             |
 | `git_sha`                         | `GIT_SHA`                         | string         | `unknown` outside production             |
 | `sentry_dsn`                      | `SENTRY_DSN`                      | string         | `nil`                                    |
+| `sentry_enable_logs`              | `SENTRY_ENABLE_LOGS`              | boolean        | `false`                                  |
 
 Rules:
 

spec/html2rss/web/boot/setup_spec.rb

@@ -13,7 +13,8 @@
       'RACK_ENV' => 'development',
       'HTML2RSS_SECRET_KEY' => boot_secret_key,
       'BUILD_TAG' => '2026-03-27',
-      'GIT_SHA' => 'abc1234'
+      'GIT_SHA' => 'abc1234',
+      'SENTRY_ENABLE_LOGS' => nil
     }
   end
 
@@ -56,7 +57,7 @@
       end
     end
 
-    it 'configures Sentry for errors and logs when a DSN is present', :aggregate_failures do
+    it 'configures Sentry for error reporting when a DSN is present', :aggregate_failures do
       stub_environment_validation
       allow(Html2rss::Web::Boot::Sentry).to receive(:configure!).and_call_original
       allow(Html2rss::Web::Boot::Sentry).to receive(:require).with('sentry-ruby').and_return(true)
@@ -71,6 +72,36 @@
       expect_sentry_to_be_configured
     end
 
+    it 'enables Sentry logs when SENTRY_ENABLE_LOGS is true', :aggregate_failures do
+      stub_environment_validation
+      allow(Html2rss::Web::Boot::Sentry).to receive(:configure!).and_call_original
+      allow(Html2rss::Web::Boot::Sentry).to receive(:require).with('sentry-ruby').and_return(true)
+      allow(Bundler).to receive(:require)
+      fake_sentry = build_fake_sentry
+      stub_const('Sentry', fake_sentry)
+
+      ClimateControl.modify(boot_env.merge('SENTRY_DSN' => sentry_dsn, 'SENTRY_ENABLE_LOGS' => 'true')) do
+        described_class.call!
+      end
+
+      expect_sentry_config(:enable_logs, true)
+    end
+
+    it 'fails fast when SENTRY_ENABLE_LOGS is malformed' do
+      stub_environment_validation
+      allow(Html2rss::Web::Boot::Sentry).to receive(:configure!).and_call_original
+      allow(Html2rss::Web::Boot::Sentry).to receive(:require).with('sentry-ruby').and_return(true)
+      allow(Bundler).to receive(:require)
+      fake_sentry = build_fake_sentry
+      stub_const('Sentry', fake_sentry)
+
+      expect do
+        ClimateControl.modify(boot_env.merge('SENTRY_DSN' => sentry_dsn, 'SENTRY_ENABLE_LOGS' => '1')) do
+          described_class.call!
+        end
+      end.to raise_error(ArgumentError, /SENTRY_ENABLE_LOGS/)
+    end
+
     it 'logs build metadata on startup' do
       stub_environment_validation
       logger = instance_double(Logger, info: nil)
@@ -113,7 +144,7 @@ def expect_sensitive_env_to_be_scrubbed
   def expect_sentry_to_be_configured
     expect(Bundler).to have_received(:require).with(:sentry)
     expect_sentry_config(:dsn, sentry_dsn)
-    expect_sentry_config(:enable_logs, true)
+    expect_sentry_config(:enable_logs, false)
     expect_sentry_config(:release, '2026-03-27+abc1234')
   end
 

spec/support/runtime_env_helpers.rb

@@ -14,7 +14,7 @@ def capture_scrubbed_runtime_env(env_overrides)
   private
 
   def preserved_runtime_env
-    %w[HTML2RSS_SECRET_KEY HEALTH_CHECK_TOKEN SENTRY_DSN].each_with_object({}) do |key, env|
+    %w[HTML2RSS_SECRET_KEY HEALTH_CHECK_TOKEN SENTRY_DSN SENTRY_ENABLE_LOGS].each_with_object({}) do |key, env|
       value = ENV.fetch(key, nil)
       env[key] = value unless value.nil?
     end