logstruct 0.0.2 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 22a9091af167d668b3470dfc55ea0d02de4809b66dd51db5531fe60e138c5452
-  data.tar.gz: 75f1e277bc6dafa3666ebd1be7e1c64c5e783065520fe5261eb734c3011ade3f
+  metadata.gz: 2a68693a793bd472926424e34f602e5f81a677e0bac2b0b8da189e7bc5adb10a
+  data.tar.gz: 8d5dd33db82a1b4eda1b8f1b0631af0cb3b04eba1e9d034e275192a49d8b9285
 SHA512:
-  metadata.gz: 6202a87818cb4ba803df9b5a516291fd7513ad58c0d94e2a42bd5f341f9bc3f5e04e777bdaa82f843d09b78a4ddbd823f87e64777ff91f9d4b07606deb554291
-  data.tar.gz: 886387655858e495eb9cb36f0d4d727f17719161771b7bdd52b67328cea78c975af3e40d8689e66e9b1cfacc8e2339867286303245770ed2680d37890d5d8e08
+  metadata.gz: 2c8afb5d952a2ec1ead718b5655cd6af260978cd001502cd2dde3f8fb66e15720a5fca9f1646b8e132cad03ab48c51507b6a5d9948080019ca17ec4011b3b347
+  data.tar.gz: af94c2f9805ec7f121df828e25b1214395450acec0ed475a5b98ca26bef564c537c2bb522f3494152fb2df5d9b0b4850d7c158a3df794fad635a60613796fd51

data/CHANGELOG.md

@@ -5,28 +5,6 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.0.1] - 2025-03-04
+## [0.1.0] - 2025-09-07
 
-### Added
-
-- Pushed empty gem to RubyGems to secure the name
-
-## [0.0.2-rc1] - 2025-09-05
-
-### Added
-
-- Unified GitHub Actions workflow to release RubyGem and sync/tag the Terraform provider; dry-run support for safe validation
-- Provider catalog export script and automated provider CI (build/vet/test)
-- Terraform docs page with quickstart, recipes, and provider README link
-- API design doc (typed vs. untyped) planned; initial philosophy captured
-- Coverage threshold gate (>= 80%) in CI; additional tests to lift coverage
-- Release helper: scripts/create_release_tag.sh (creates annotated tag from version.rb)
-
-### Changed
-
-- ActionMailer callbacks patched for Rails 7.0; event logging + metadata collection tested
-- Provider CloudWatch filter builder refactored for testability; key lookups aligned with exported catalog (event/source)
-
-### Fixed
-
-- Pre-commit hooks reporting; cspell dictionary updated; TypeScript import fixes in site
+Initial release.

data/README.md

@@ -62,6 +62,16 @@ Once initialized, the gem automatically includes its modules into the appropriat
 
 Please see the [documentation](https://logstruct.com/docs) for more details. (All code examples are type-checked and tested, and it's harder to keep a README up to date.)
 
+### Custom Typed Logs
+
+In addition to the built‑in, strictly typed log structures (Request, Error, SQL, etc.), you can define your own app‑specific typed logs while still using the public `LogStruct.info/error/...` methods.
+
+- Compose the public interfaces: include `LogStruct::Log::Interfaces::PublicCommonFields` and the helpers `SerializeCommonPublic` + `MergeAdditionalDataFields` in your `T::Struct`.
+- Fix your `source` to a constant (e.g., return the string `"payments"`), and restrict `event` with a `T::Enum` (e.g., `processed|failed|refunded`).
+- The `LogStruct.info` signature accepts either the internal `CommonFields` (for built‑ins) or your public custom type, so you keep type safety at the call site.
+
+See the docs page for a complete example: [Sorbet Types → Custom Typed Logs](https://logstruct.com/docs/sorbet-types#custom-log-classes).
+
 ## License
 
 This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

data/lib/log_struct/concerns/logging.rb

@@ -11,31 +11,31 @@ module LogStruct
         extend T::Sig
 
         # Log a log struct at debug level
-        sig { params(log: Log::Interfaces::CommonFields).void }
+        sig { params(log: T.any(Log::Interfaces::CommonFields, Log::Interfaces::PublicCommonFields)).void }
         def debug(log)
           Rails.logger.debug(log)
         end
 
         # Log a log struct at info level
-        sig { params(log: Log::Interfaces::CommonFields).void }
+        sig { params(log: T.any(Log::Interfaces::CommonFields, Log::Interfaces::PublicCommonFields)).void }
         def info(log)
           Rails.logger.info(log)
         end
 
         # Log a log struct at warn level
-        sig { params(log: Log::Interfaces::CommonFields).void }
+        sig { params(log: T.any(Log::Interfaces::CommonFields, Log::Interfaces::PublicCommonFields)).void }
         def warn(log)
           Rails.logger.warn(log)
         end
 
         # Log a log struct at error level
-        sig { params(log: Log::Interfaces::CommonFields).void }
+        sig { params(log: T.any(Log::Interfaces::CommonFields, Log::Interfaces::PublicCommonFields)).void }
         def error(log)
           Rails.logger.error(log)
         end
 
         # Log a log struct at fatal level
-        sig { params(log: Log::Interfaces::CommonFields).void }
+        sig { params(log: T.any(Log::Interfaces::CommonFields, Log::Interfaces::PublicCommonFields)).void }
         def fatal(log)
           Rails.logger.fatal(log)
         end

data/lib/log_struct/config_struct/integrations.rb

@@ -84,6 +84,14 @@ module LogStruct
       # 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

data/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

data/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

data/lib/log_struct/integrations.rb

@@ -14,6 +14,8 @@ require_relative "integrations/good_job"
 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 @@ module LogStruct
       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

data/lib/log_struct/log/active_model_serializers.rb

@@ -0,0 +1,55 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "interfaces/common_fields"
+require_relative "interfaces/additional_data_field"
+require_relative "shared/serialize_common"
+require_relative "shared/merge_additional_data_fields"
+require_relative "../enums/source"
+require_relative "../enums/event"
+require_relative "../enums/level"
+require_relative "../log_keys"
+
+module LogStruct
+  module Log
+    # ActiveModelSerializers render log entry for structured logging
+    class ActiveModelSerializers < T::Struct
+      extend T::Sig
+
+      include Interfaces::CommonFields
+      include Interfaces::AdditionalDataField
+      include SerializeCommon
+      include MergeAdditionalDataFields
+
+      AMSEvent = T.type_alias { Event::Log }
+
+      # Common fields
+      const :source, Source::Rails, default: T.let(Source::Rails, Source::Rails)
+      const :event, AMSEvent, default: T.let(Event::Log, AMSEvent)
+      const :level, Level, default: T.let(Level::Info, Level)
+      const :timestamp, Time, factory: -> { Time.now }
+
+      # AMS specifics
+      const :message, String, default: "ams.render"
+      const :serializer, T.nilable(String), default: nil
+      const :adapter, T.nilable(String), default: nil
+      const :resource_class, T.nilable(String), default: nil
+      const :duration_ms, T.nilable(Float), default: nil
+
+      # Extra data
+      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)
+        hash = serialize_common(strict)
+        merge_additional_data_fields(hash)
+        hash[LOG_KEYS.fetch(:message)] = message
+        hash[:serializer] = serializer if serializer
+        hash[:adapter] = adapter if adapter
+        hash[:resource_class] = resource_class if resource_class
+        hash[:duration_ms] = duration_ms if duration_ms
+        hash
+      end
+    end
+  end
+end

data/lib/log_struct/log/ahoy.rb

@@ -0,0 +1,54 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "interfaces/common_fields"
+require_relative "interfaces/additional_data_field"
+require_relative "shared/serialize_common"
+require_relative "shared/merge_additional_data_fields"
+require_relative "../enums/source"
+require_relative "../enums/event"
+require_relative "../enums/level"
+require_relative "../log_keys"
+
+module LogStruct
+  module Log
+    # Ahoy analytics log entry for structured logging
+    class Ahoy < T::Struct
+      extend T::Sig
+
+      include Interfaces::CommonFields
+      include Interfaces::AdditionalDataField
+      include SerializeCommon
+      include MergeAdditionalDataFields
+
+      # Events are generic logs for tracking
+      AhoyEvent = T.type_alias {
+        Event::Log
+      }
+
+      # Common fields
+      const :source, Source, default: T.let(Source::App, Source)
+      const :event, AhoyEvent, default: T.let(Event::Log, AhoyEvent)
+      const :level, Level, default: T.let(Level::Info, Level)
+      const :timestamp, Time, factory: -> { Time.now }
+
+      # Ahoy specifics
+      const :message, String, default: "ahoy.track"
+      const :ahoy_event, T.nilable(String), default: nil
+      const :properties, T.nilable(T::Hash[Symbol, T.untyped]), default: nil
+
+      # Extra data
+      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)
+        hash = serialize_common(strict)
+        merge_additional_data_fields(hash)
+        hash[LOG_KEYS.fetch(:message)] = message
+        hash[:ahoy_event] = ahoy_event if ahoy_event
+        hash[:properties] = properties if properties
+        hash
+      end
+    end
+  end
+end

data/lib/log_struct/log/error.rb

@@ -20,6 +20,7 @@ module LogStruct
       include Interfaces::CommonFields
       include Interfaces::AdditionalDataField
       include Interfaces::MessageField
+      include SerializeCommon
       include MergeAdditionalDataFields
 
       ErrorEvent = T.type_alias {

data/lib/log_struct/log/interfaces/public_common_fields.rb

@@ -0,0 +1,31 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../../enums/level"
+
+module LogStruct
+  module Log
+    module Interfaces
+      # Public interface for custom app log types.
+      # Allows String/Symbol for source and event so apps can define their own domains.
+      module PublicCommonFields
+        extend T::Sig
+        extend T::Helpers
+
+        interface!
+
+        # Log level (defaults to Info in most structs)
+        sig { abstract.returns(Level) }
+        def level; end
+
+        # Timestamp for the entry
+        sig { abstract.returns(Time) }
+        def timestamp; end
+
+        # Custom serialize method returning symbol-keyed hash
+        sig { abstract.params(strict: T::Boolean).returns(T::Hash[Symbol, T.untyped]) }
+        def serialize(strict = true); end
+      end
+    end
+  end
+end

data/lib/log_struct/log/shared/merge_additional_data_fields.rb

@@ -3,7 +3,6 @@
 
 require_relative "../../log_keys"
 require_relative "../interfaces/additional_data_field"
-require_relative "serialize_common"
 
 module LogStruct
   module Log
@@ -12,8 +11,6 @@ module LogStruct
       extend T::Sig
       extend T::Helpers
 
-      include SerializeCommon
-
       requires_ancestor { T::Struct }
       requires_ancestor { Interfaces::AdditionalDataField }
 

data/lib/log_struct/log/shared/serialize_common_public.rb

@@ -0,0 +1,44 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../../log_keys"
+require_relative "../interfaces/public_common_fields"
+
+module LogStruct
+  module Log
+    # Common serialization for public custom log structs with string/symbol source/event
+    module SerializeCommonPublic
+      extend T::Sig
+      extend T::Helpers
+
+      requires_ancestor { Interfaces::PublicCommonFields }
+      requires_ancestor { Kernel }
+
+      sig { params(strict: T::Boolean).returns(T::Hash[Symbol, T.untyped]) }
+      def serialize_common_public(strict = true)
+        unless respond_to?(:source) && respond_to?(:event)
+          raise ArgumentError, "Public log struct must define #source and #event"
+        end
+
+        src_val = T.unsafe(self).source
+        evt_val = T.unsafe(self).event
+        src = src_val.respond_to?(:serialize) ? T.unsafe(src_val).serialize.to_s : src_val.to_s
+        evt = evt_val.respond_to?(:serialize) ? T.unsafe(evt_val).serialize.to_s : evt_val.to_s
+        lvl = level.serialize.to_s
+        ts = timestamp.iso8601(3)
+
+        {
+          LOG_KEYS.fetch(:source) => src,
+          LOG_KEYS.fetch(:event) => evt,
+          LOG_KEYS.fetch(:level) => lvl,
+          LOG_KEYS.fetch(:timestamp) => ts
+        }
+      end
+
+      sig { params(options: T.untyped).returns(T::Hash[String, T.untyped]) }
+      def as_json(options = nil)
+        serialize.transform_keys(&:to_s)
+      end
+    end
+  end
+end

data/lib/log_struct/log.rb

@@ -5,6 +5,8 @@
 require_relative "enums/source"
 require_relative "enums/event"
 require_relative "enums/level"
+require_relative "log/interfaces/public_common_fields"
+require_relative "log/shared/serialize_common_public"
 
 # Log Structs
 require_relative "log/carrierwave"
@@ -19,6 +21,8 @@ require_relative "log/security"
 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 +41,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

data/lib/log_struct/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 module LogStruct
-  VERSION = "0.0.2"
+  VERSION = "0.1.0"
 end

data/logstruct.gemspec

@@ -47,6 +47,8 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "shrine", "~> 3.5"
   spec.add_development_dependency "sidekiq", "~> 7.2"
   spec.add_development_dependency "sorbet", "~> 0.5"
+  spec.add_development_dependency "ahoy_matey", "~> 5.2"
+  spec.add_development_dependency "active_model_serializers", "~> 0.10.13"
 
   spec.metadata["rubygems_mfa_required"] = "true"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: logstruct
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.1.0
 platform: ruby
 authors:
 - DocSpring
 bindir: exe
 cert_chain: []
-date: 2025-09-05 00:00:00.000000000 Z
+date: 2025-09-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: lograge
@@ -177,6 +177,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.5'
+- !ruby/object:Gem::Dependency
+  name: ahoy_matey
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.2'
+- !ruby/object:Gem::Dependency
+  name: active_model_serializers
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.10.13
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.10.13
 description: An opinionated and type-safe structured logging solution. Configures
   any Rails app to log JSON to stdout. Structured logging is automatically configured
   for many gems, including Sidekiq, Carrierwave, Shrine, etc. Log messages, params,
@@ -215,8 +243,10 @@ files:
 - lib/log_struct/integrations/action_mailer/metadata_collection.rb
 - lib/log_struct/integrations/active_job.rb
 - lib/log_struct/integrations/active_job/log_subscriber.rb
+- lib/log_struct/integrations/active_model_serializers.rb
 - lib/log_struct/integrations/active_record.rb
 - lib/log_struct/integrations/active_storage.rb
+- lib/log_struct/integrations/ahoy.rb
 - lib/log_struct/integrations/carrierwave.rb
 - lib/log_struct/integrations/good_job.rb
 - lib/log_struct/integrations/good_job/log_subscriber.rb
@@ -234,13 +264,16 @@ files:
 - lib/log_struct/log.rb
 - lib/log_struct/log/action_mailer.rb
 - lib/log_struct/log/active_job.rb
+- lib/log_struct/log/active_model_serializers.rb
 - lib/log_struct/log/active_storage.rb
+- lib/log_struct/log/ahoy.rb
 - lib/log_struct/log/carrierwave.rb
 - lib/log_struct/log/error.rb
 - lib/log_struct/log/good_job.rb
 - lib/log_struct/log/interfaces/additional_data_field.rb
 - lib/log_struct/log/interfaces/common_fields.rb
 - lib/log_struct/log/interfaces/message_field.rb
+- lib/log_struct/log/interfaces/public_common_fields.rb
 - lib/log_struct/log/interfaces/request_fields.rb
 - lib/log_struct/log/plain.rb
 - lib/log_struct/log/request.rb
@@ -248,6 +281,7 @@ files:
 - lib/log_struct/log/shared/add_request_fields.rb
 - lib/log_struct/log/shared/merge_additional_data_fields.rb
 - lib/log_struct/log/shared/serialize_common.rb
+- lib/log_struct/log/shared/serialize_common_public.rb
 - lib/log_struct/log/shrine.rb
 - lib/log_struct/log/sidekiq.rb
 - lib/log_struct/log/sql.rb