fix(observability): harden sentry log bridge and docs

Author: gildesmarais

README.md

@@ -49,9 +49,14 @@ This trial run is intentionally minimal. Use Docker Compose for Browserless, aut
 
 1. Generate a key: `openssl rand -hex 32`.
 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`.
+3. Export build metadata required by `docker-compose.yml`:
+   ```bash
+   export BUILD_TAG=local
+   export GIT_SHA="$(git rev-parse --short HEAD 2>/dev/null || echo dev)"
+   ```
+4. Optionally export `SENTRY_DSN` to send application errors to Sentry.
+5. Optionally export `SENTRY_ENABLE_LOGS=true` to forward structured application logs to Sentry.
+6. Start: `docker-compose up`.
 
 UI + API run on `http://localhost:4000`. The app exits if the secret key is missing.
 

app/web/telemetry/app_logger.rb

@@ -101,10 +101,18 @@ def normalize_logfmt_value(raw_value)
         # @param payload [Hash{Symbol=>Object}]
         # @return [void]
         def emit_to_sentry(payload)
+          return unless sentry_payload?(payload)
+
           SentryLogs.emit(payload)
         rescue StandardError
           nil
         end
+
+        # @param payload [Hash{Symbol=>Object}]
+        # @return [Boolean]
+        def sentry_payload?(payload)
+          payload.key?(:event_name) || payload.key?(:security_event)
+        end
       end
     end
   end

app/web/telemetry/sentry_logs.rb

@@ -7,6 +7,7 @@ module Web
     # enabled for the current runtime.
     module SentryLogs
       OMIT = Object.new.freeze
+      ALLOWED_LEVELS = %i[debug info warn error fatal].freeze
       SENSITIVE_ATTRIBUTE_KEYS = %w[actor email ip remote_ip user_agent username x_forwarded_for].freeze
 
       class << self
@@ -40,7 +41,10 @@ def logger
         # @param payload [Hash{Symbol=>Object}]
         # @return [Symbol]
         def level(payload)
-          payload.fetch(:level, 'INFO').to_s.downcase.to_sym
+          requested_level = payload.fetch(:level, 'INFO').to_s.downcase.to_sym
+          return requested_level if ALLOWED_LEVELS.include?(requested_level)
+
+          :info
         end
 
         # @param payload [Hash{Symbol=>Object}]

public/openapi.yaml

@@ -331,7 +331,7 @@ paths:
                 - success
                 - data
                 type: object
-          description: returns health status after production-style env scrubbing
+          description: returns current health status when a valid bearer token is provided
         '401':
           content:
             application/json:

spec/html2rss/web/app_logger_spec.rb

@@ -35,5 +35,16 @@
       end.not_to raise_error
       expect(io.string).to include('"event_name":"boot.test"')
     end
+
+    it 'does not forward plain string logs to the Sentry bridge' do
+      allow(Logger).to receive(:new).and_return(test_logger)
+      allow(Html2rss::Web::SentryLogs).to receive(:emit)
+
+      described_class.reset_logger!
+      described_class.logger.info('plain-text log line with request details')
+
+      expect(Html2rss::Web::SentryLogs).not_to have_received(:emit)
+      expect(io.string).to include('"message":"plain-text log line with request details"')
+    end
   end
 end

spec/html2rss/web/sentry_logs_spec.rb

@@ -6,6 +6,18 @@
 require_relative '../../../app/web/telemetry/sentry_logs'
 
 RSpec.describe Html2rss::Web::SentryLogs do
+  let(:logger_class) do
+    Struct.new(:captured_call) do
+      %i[debug info warn error fatal].each do |log_level|
+        define_method(log_level) do |message, **attributes|
+          captured_call[:level] = log_level
+          captured_call[:message] = message
+          captured_call[:attributes] = attributes
+        end
+      end
+    end
+  end
+
   let(:captured_call) { {} }
   let(:sentry_logger) { build_sentry_logger }
   let(:fake_sentry) do
@@ -53,14 +65,18 @@
     expect(captured_call).to eq({})
   end
 
-  def build_sentry_logger
-    logger_class = Struct.new(:captured_call) do
-      def info(message, **attributes)
-        captured_call[:message] = message
-        captured_call[:attributes] = attributes
-      end
-    end
+  it 'falls back to info when an unsupported level is requested', :aggregate_failures do
+    stub_const('Sentry', fake_sentry)
+    allow(Html2rss::Web::RuntimeEnv).to receive_messages(sentry_enabled?: true, sentry_logs_enabled?: true)
+    allow(described_class).to receive(:logger).and_return(sentry_logger)
+
+    described_class.emit(raw_payload.merge(level: :unknown_method))
+
+    expect(captured_call).to include(:message, :attributes)
+    expect(captured_call.fetch(:message)).to eq('auth.authenticate')
+  end
 
+  def build_sentry_logger
     logger_class.new(captured_call)
   end
 
@@ -71,6 +87,7 @@ def expect_forwarded_payload
   end
 
   def expect_forwarded_message
+    expect(captured_call.fetch(:level)).to eq(:info)
     expect(captured_call.fetch(:message)).to eq('auth.authenticate')
   end