ams and ahoy integrations, site updates

Author: ndbroadbent

Gemfile.lock

@@ -54,6 +54,11 @@ GEM
       erubi (~> 1.11)
       rails-dom-testing (~> 2.2)
       rails-html-sanitizer (~> 1.6)
+    active_model_serializers (0.10.15)
+      actionpack (>= 4.1)
+      activemodel (>= 4.1)
+      case_transform (>= 0.2)
+      jsonapi-renderer (>= 0.1.1.beta1, < 0.3)
     activejob (7.2.2.1)
       activesupport (= 7.2.2.1)
       globalid (>= 0.3.6)
@@ -83,6 +88,10 @@ GEM
       tzinfo (~> 2.0, >= 2.0.5)
     addressable (2.8.7)
       public_suffix (>= 2.0.2, < 7.0)
+    ahoy_matey (5.4.0)
+      activesupport (>= 7.1)
+      device_detector (>= 1)
+      safely_block (>= 0.4)
     amazing_print (1.7.2)
     ansi (1.5.0)
     ast (2.4.2)
@@ -100,6 +109,8 @@ GEM
       image_processing (~> 1.1)
       marcel (~> 1.0.0)
       ssrf_filter (~> 1.0)
+    case_transform (0.2)
+      activesupport
     climate_control (1.2.0)
     concurrent-ruby (1.3.4)
     connection_pool (2.5.0)
@@ -110,6 +121,7 @@ GEM
     debug (1.10.0)
       irb (~> 1.10)
       reline (>= 0.3.8)
+    device_detector (1.1.3)
     diff-lcs (1.6.0)
     docile (1.4.1)
     down (5.4.2)
@@ -139,6 +151,7 @@ GEM
       reline (>= 0.4.2)
     jaro_winkler (1.6.0)
     json (2.10.1)
+    jsonapi-renderer (0.2.2)
     kramdown (2.5.1)
       rexml (>= 3.3.9)
     kramdown-parser-gfm (1.1.0)
@@ -298,6 +311,7 @@ GEM
     ruby-vips (2.2.3)
       ffi (~> 1.12)
       logger
+    safely_block (0.5.0)
     securerandom (0.4.1)
     semantic_logger (4.17.0)
       concurrent-ruby (~> 1.0)
@@ -413,6 +427,8 @@ PLATFORMS
   x86_64-linux-musl
 
 DEPENDENCIES
+  active_model_serializers (~> 0.10.13)
+  ahoy_matey (~> 5.2)
   amazing_print
   bigdecimal
   bugsnag (~> 6.26)

INTEGRATIONS.md

@@ -0,0 +1,145 @@
+**Purpose**
+
+- Document how to add a new first‑class integration to LogStruct so it’s consistent, type‑safe, well‑tested, and shows up automatically in the docs site with an auto‑generated example log.
+
+**High‑Level Flow**
+
+- Add a typed log structure under `lib/log_struct/log/` (so the docs generator picks it up).
+- Add a configuration toggle in `ConfigStruct::Integrations` and wire it into `Integrations.setup_integrations`.
+- Implement the integration under `lib/log_struct/integrations/…` to produce that log type.
+- Add the dev dependency for the third‑party gem and generate RBIs with Tapioca.
+- Add tests (unit + behavior) under `test/log_struct/integrations` and (if needed) `test/log_struct/log`.
+- Add a short entry in the docs metadata (`site/lib/integration-helpers.ts`). The Integrations page will render it automatically via `AllLogTypes`.
+- Run type export to update the docs’ TypeScript types.
+
+**Conventions**
+
+- Files and naming:
+  - Log type: `lib/log_struct/log/<Name>.rb` (class `LogStruct::Log::<Name>`)
+  - Integration: `lib/log_struct/integrations/<name>.rb` (module `LogStruct::Integrations::<Name>`)
+  - Optional submodules (e.g., `logger.rb`, `log_subscriber.rb`) live below a folder `lib/log_struct/integrations/<name>/`.
+  - Tests mirror structure under `test/log_struct/log` and `test/log_struct/integrations`.
+- Type safety:
+  - Every Ruby file must be `# typed: strict` and use `T::Sig`.
+  - For integration setup signatures: `sig { params(config: LogStruct::Configuration).returns(T.nilable(TrueClass)) }`.
+  - Prefer real constants (the gem is a development dependency), but guard runtime with `defined?(::GemModule)` to be safe in user apps.
+- Error handling:
+  - Never raise from the integration path; use `LogStruct.handle_exception(error, source: <Source>, context: {integration: :name})`.
+- Logging:
+  - Produce a dedicated typed log struct (do NOT emit a generic/plain log).
+  - Message naming: concise and stable, e.g., `"ams.render"`, `"ahoy.track"`.
+  - Choose the correct `Source` (Rails/App/Job/Storage/…) and a suitable `Event` (`Event::Log` unless a more specific event applies).
+
+**Step‑by‑Step Checklist**
+
+1. Create the typed log struct
+   - File: `lib/log_struct/log/<name>.rb`
+   - Include: `Interfaces::CommonFields`, `Interfaces::AdditionalDataField`, `SerializeCommon`, `MergeAdditionalDataFields`.
+   - Define required fields and defaults (e.g., `message`, specific properties for the integration), and implement `serialize` to add them to the output.
+   - Example skeleton:
+
+     class LogStruct::Log::Example < T::Struct
+     extend T::Sig
+     include Interfaces::CommonFields
+     include Interfaces::AdditionalDataField
+     include SerializeCommon
+     include MergeAdditionalDataFields
+
+     ExampleEvent = T.type_alias { Event::Log }
+     const :source, Source::Rails, default: T.let(Source::Rails, Source::Rails)
+     const :event, ExampleEvent, default: T.let(Event::Log, ExampleEvent)
+     const :level, Level, default: T.let(Level::Info, Level)
+     const :timestamp, Time, factory: -> { Time.now }
+
+     const :message, String, default: "example.event"
+     const :detail, T.nilable(String), default: nil
+     const :additional_data, T::Hash[Symbol, T.untyped], default: {}
+
+     sig { override.params(strict: T::Boolean).returns(T::Hash[Symbol, T.untyped]) }
+     def serialize(strict = true)
+     h = serialize_common(strict)
+     merge_additional_data_fields(h)
+     h[LOG_KEYS.fetch(:message)] = message
+     h[:detail] = detail if detail
+     h
+     end
+     end
+
+2. Register the log type
+   - In `lib/log_struct/log.rb`:
+     - `require_relative "log/<name>"`
+     - Add `T.class_of(LogStruct::Log::<Name>)` to `LogClassType`.
+
+3. Add a config toggle
+   - In `lib/log_struct/config_struct/integrations.rb`:
+     - `prop :enable_<name>, T::Boolean, default: true`
+   - In `lib/log_struct/integrations.rb`:
+     - `require_relative "integrations/<name>"`
+     - Call `Integrations::<Name>.setup(config)` inside `setup_integrations` behind the toggle.
+
+4. Implement the integration
+   - File: `lib/log_struct/integrations/<name>.rb`
+   - Guard on presence of the third‑party gem (`return nil unless defined?(::ThirdParty)`), subscribe/hook into events, build your typed log, and log it with `LogStruct.info(log)`.
+   - Use `handle_exception` on rescue.
+
+5. Add development dependency + RBIs
+   - In `logstruct.gemspec`, add the gem as a development dependency with a supported version:
+     - `spec.add_development_dependency "third_party_gem", "~> X.Y"`
+   - Run:
+     - `bundle install`
+     - `bundle exec tapioca gems` (commits RBIs under `sorbet/rbi/gems/...`).
+
+6. Tests
+   - Unit/behavior tests under `test/log_struct/integrations/<name>_test.rb`.
+   - If the integration exposes a new log struct surface, add a focused test in `test/log_struct/log/<name>_test.rb` when it adds non‑trivial serialization.
+   - Prefer real gem objects with small fakes only where necessary; the gem is available as a dev dependency.
+   - Assertions should inspect `as_json` and verify:
+     - `src`, `evt`, `lvl`, `ts` exist
+     - `msg` matches the agreed name
+     - Integration‑specific fields are present and correct
+
+7. Docs
+   - No custom sections in the Integrations page.
+   - The Integrations page lists all `AllLogTypes` with titles/descriptions from `site/lib/integration-helpers.ts`.
+   - Add an entry to `getLogTypeInfo` for your new log type (title, concise description, optional `configuration_code: 'integrations_configuration'`).
+   - Run the type export to regenerate the docs’ TypeScript assets so example logs render:
+     - `ruby scripts/export_typescript_types.rb`
+
+8. Sorbet + CI
+   - Run `scripts/typecheck.sh` (must be clean).
+   - Run `scripts/test.rb` and `scripts/rails_tests.sh` (must be green).
+   - CI will enforce Tapioca verification and coverage threshold (80%+ merged).
+
+**Patterns to Follow (Examples)**
+
+- GoodJob:
+  - Log type: `lib/log_struct/log/good_job.rb`
+  - Integration: `lib/log_struct/integrations/good_job.rb` (+ `logger.rb`, `log_subscriber.rb`)
+  - Toggle: `enable_goodjob`
+- SQL (ActiveRecord):
+  - Log type: `lib/log_struct/log/sql.rb`
+  - Integration: `lib/log_struct/integrations/active_record.rb`
+  - Toggle: `enable_sql_logging`
+- ActiveModelSerializers:
+  - Log type: `lib/log_struct/log/active_model_serializers.rb` (msg: "ams.render")
+  - Integration: `lib/log_struct/integrations/active_model_serializers.rb`
+  - Toggle: `enable_active_model_serializers`
+- Ahoy:
+  - Log type: `lib/log_struct/log/ahoy.rb` (msg: "ahoy.track")
+  - Integration: `lib/log_struct/integrations/ahoy.rb`
+  - Toggle: `enable_ahoy`
+
+**Gotchas**
+
+- Don’t emit generic/plain logs for integrations that deserve a first‑class type.
+- Keep message names short and stable; avoid dumping raw payloads into `msg`.
+- Don’t raise in integration hooks; always call `handle_exception` with the correct `Source`.
+- Docs auto‑generation depends on the log type being included in `LogClassType` and the TypeScript export.
+
+**One‑Time Commands (after adding or changing log types)**
+
+- `bundle install`
+- `bundle exec tapioca gems`
+- `ruby scripts/export_typescript_types.rb`
+- `scripts/typecheck.sh`
+- `scripts/test.rb` and (optionally) `scripts/rails_tests.sh`

lib/log_struct/config_struct/integrations.rb

@@ -84,6 +84,14 @@ class Integrations < T::Struct
       # Include bind parameters in SQL logs (disable in production for security)
       # Default: true in development/test, false in production
       prop :sql_log_bind_params, T::Boolean, factory: -> { !defined?(::Rails) || !::Rails.respond_to?(:env) || !::Rails.env.production? }
+
+      # Enable Ahoy (analytics events) integration
+      # Default: true (safe no-op unless Ahoy is defined)
+      prop :enable_ahoy, T::Boolean, default: true
+
+      # Enable ActiveModelSerializers integration
+      # Default: true (safe no-op unless ActiveModelSerializers is defined)
+      prop :enable_active_model_serializers, T::Boolean, default: true
     end
   end
 end

lib/log_struct/integrations.rb

@@ -14,6 +14,8 @@
 require_relative "integrations/active_storage"
 require_relative "integrations/carrierwave"
 require_relative "integrations/sorbet"
+require_relative "integrations/ahoy"
+require_relative "integrations/active_model_serializers"
 
 module LogStruct
   module Integrations
@@ -30,6 +32,8 @@ def self.setup_integrations
       Integrations::ActiveRecord.setup(config) if config.integrations.enable_sql_logging
       Integrations::Sidekiq.setup(config) if config.integrations.enable_sidekiq
       Integrations::GoodJob.setup(config) if config.integrations.enable_goodjob
+      Integrations::Ahoy.setup(config) if config.integrations.enable_ahoy
+      Integrations::ActiveModelSerializers.setup(config) if config.integrations.enable_active_model_serializers
       Integrations::HostAuthorization.setup(config) if config.integrations.enable_host_authorization
       Integrations::RackErrorHandler.setup(config) if config.integrations.enable_rack_error_handler
       Integrations::Shrine.setup(config) if config.integrations.enable_shrine

lib/log_struct/integrations/active_model_serializers.rb

@@ -0,0 +1,55 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "active_support/notifications"
+
+module LogStruct
+  module Integrations
+    # ActiveModelSerializers integration. Subscribes to AMS notifications and
+    # emits structured logs with serializer/adapter/duration details.
+    module ActiveModelSerializers
+      extend T::Sig
+
+      sig { params(config: LogStruct::Configuration).returns(T.nilable(TrueClass)) }
+      def self.setup(config)
+        return nil unless defined?(::ActiveSupport::Notifications)
+
+        # Only activate if AMS appears to be present
+        return nil unless defined?(::ActiveModelSerializers)
+
+        # Subscribe to common AMS notification names; keep broad but specific
+        pattern = /\.active_model_serializers\z/
+
+        ::ActiveSupport::Notifications.subscribe(pattern) do |_name, started, finished, _unique_id, payload|
+          duration_ms = ((finished - started) * 1000.0)
+
+          data = {
+            duration_ms: duration_ms
+          }
+
+          serializer = payload[:serializer] || payload[:serializer_class]
+          adapter = payload[:adapter]
+          resource = payload[:resource] || payload[:object]
+
+          data[:serializer] = serializer.to_s if serializer
+          data[:adapter] = adapter.to_s if adapter
+          data[:resource_class] = resource.class.name if resource
+
+          LogStruct.info(
+            LogStruct::Log::ActiveModelSerializers.new(
+              serializer: data[:serializer]&.to_s,
+              adapter: data[:adapter]&.to_s,
+              resource_class: data[:resource_class]&.to_s,
+              duration_ms: T.cast(data[:duration_ms], T.nilable(Float)),
+              additional_data: {}
+            )
+          )
+        rescue => e
+          LogStruct.handle_exception(e, source: LogStruct::Source::Rails, context: {integration: :active_model_serializers})
+        end
+
+        true
+      end
+    end
+  end
+end

lib/log_struct/integrations/ahoy.rb

@@ -0,0 +1,53 @@
+# typed: strict
+# frozen_string_literal: true
+
+module LogStruct
+  module Integrations
+    # Ahoy analytics integration. If Ahoy is present, prepend a small hook to
+    # Ahoy::Tracker#track to emit a structured log for analytics events.
+    module Ahoy
+      extend T::Sig
+
+      sig { params(config: LogStruct::Configuration).returns(T.nilable(TrueClass)) }
+      def self.setup(config)
+        return nil unless defined?(::Ahoy)
+
+        if defined?(::Ahoy::Tracker)
+          mod = Module.new do
+            extend T::Sig
+
+            sig { params(name: T.untyped, properties: T.nilable(T::Hash[T.untyped, T.untyped]), options: T.untyped).returns(T.untyped) }
+            def track(name, properties = nil, options = nil)
+              result = super
+              begin
+                # Emit a lightweight structured log about the analytics event
+                data = {
+                  ahoy_event: T.let(name, T.untyped)
+                }
+                data[:properties] = properties if properties
+                LogStruct.info(
+                  LogStruct::Log::Ahoy.new(
+                    ahoy_event: T.let(name, T.nilable(String)),
+                    properties: T.let(
+                      properties && properties.transform_keys { |k| k.to_sym },
+                      T.nilable(T::Hash[Symbol, T.untyped])
+                    ),
+                    additional_data: {}
+                  )
+                )
+              rescue => e
+                # Never raise from logging; rely on global error handling policies
+                LogStruct.handle_exception(e, source: LogStruct::Source::App, context: {integration: :ahoy})
+              end
+              result
+            end
+          end
+
+          T.unsafe(::Ahoy::Tracker).prepend(mod)
+        end
+
+        true
+      end
+    end
+  end
+end

lib/log_struct/log.rb

@@ -19,6 +19,8 @@
 require_relative "log/shrine"
 require_relative "log/sidekiq"
 require_relative "log/sql"
+require_relative "log/ahoy"
+require_relative "log/active_model_serializers"
 
 module LogStruct
   # Type aliases for all possible log types
@@ -37,7 +39,9 @@ module LogStruct
       T.class_of(LogStruct::Log::Security),
       T.class_of(LogStruct::Log::Shrine),
       T.class_of(LogStruct::Log::Sidekiq),
-      T.class_of(LogStruct::Log::SQL)
+      T.class_of(LogStruct::Log::SQL),
+      T.class_of(LogStruct::Log::Ahoy),
+      T.class_of(LogStruct::Log::ActiveModelSerializers)
     )
   end
 end