julewire-semantic_logger 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 56e9c8fb67e4c5a896837a1dfd5f1a81c14aa27a3167dd9e140c7cca706f65d9
-  data.tar.gz: 3f4ded10ad8caedf602ad81fa88e4587461ddaef3ca5befab5e25eff710a4314
+  metadata.gz: beb5d40e08c5450bacaf2612a33be872a901a65720e7f45ca3e1ef6f3c5ba079
+  data.tar.gz: 732c33f8c3084b1910e2811bf46b22e4eb830251e03603d08f220d7806ed7e49
 SHA512:
-  metadata.gz: 60eda983c6c3acd4983ae38d76493a0cbf0a915079abb26ae793880ce12090eec5a16ed82f24ebf724f684fc0dd860d64f7f92c847ca0094845bd9b937faa482
-  data.tar.gz: 9facbc31acb5355bb8b65abc37fc4e83d3e15e3706efb4749797a02d28ea6d3ddc2972b8a09673eadfad3c75a41c81956305f0cc6ab2584ada30028def9f9187
+  metadata.gz: bf6b5a29645f9c18c6a7b7b50a752835679e1d70c4b9832ba5150568a3ecd0ecee1e9b48a61eb5b92ab44238c8685f99e511cd7ee43c7df7b54f05416e449412
+  data.tar.gz: c5622b13c0ffebf510ecd7a11192ea4083d5f94fb0b8a0ae9ccc8ff79283794dbd390d6ee22d09e16c44d53458c82252f59a230debc365554e4ab60e75253f0d

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## Unreleased
 
+## 1.1.0 - 2026-07-20
+
+- Support Semantic Logger 4 and 5 async option shapes.
+- Keep destination health and callback failure reporting aligned with core.
+- Require julewire-core 1.1.0.
+
 ## 1.0.1 - 2026-06-25
 
 - Report destination callback failures in health, matching core destinations.

data/docs/advanced-configuration.md

@@ -36,6 +36,18 @@ These options are passed to `SemanticLogger::Appender::Async` when
 | `lag_check_interval:` | `1_000` |
 | `lag_threshold_s:` | `30` |
 
+## Async Queue Options
+
+Transport-level async options are passed to the Semantic Logger async proxy
+when the installed Semantic Logger version supports them. Semantic Logger 4.18
+supports queue size and lag options. Semantic Logger 5 also supports
+`non_blocking:`, `dropped_message_report_seconds:`, and `async_max_retries:`.
+Setting a non-default unsupported async option raises a configuration error.
+
+`batch: true` uses `SemanticLogger::Appender::AsyncBatch` on Semantic Logger 4
+and `SemanticLogger::Appender::Async` batch mode on Semantic Logger 5. Batch
+mode implies async output.
+
 ## Appender Defaults
 
 Unknown transport options are merged into each appender spec. This is useful for

data/docs/configuration.md

@@ -39,6 +39,12 @@ At least one appender target is required.
 | `appenders:` | none | Array of appender specs. |
 | `async:` | `false` | Wrap the sink in `SemanticLogger::Appender::Async`. |
 | `max_queue_size:` | `10_000` | Async queue size. `-1` means unbounded in Semantic Logger. |
+| `batch:` | `nil` | Use Semantic Logger batch async processing when supported by the appender. `true` implies async output. |
+| `batch_size:` | `300` | Batch size for batch-capable async appenders. |
+| `batch_seconds:` | `5` | Maximum seconds between batch writes. |
+| `non_blocking:` | `false` | Semantic Logger 5+ async drop mode. Raises on older Semantic Logger when set to a non-default value. |
+| `dropped_message_report_seconds:` | `30` | Semantic Logger 5+ dropped-message report interval. Raises on older Semantic Logger when set to a non-default value. |
+| `async_max_retries:` | `100` | Semantic Logger 5+ async worker retry limit. Raises on older Semantic Logger when set to a non-default value. |
 
 Unknown transport options are passed to Semantic Logger appender construction.
 

data/docs/health.md

@@ -11,7 +11,7 @@ Destination health includes:
 - destination `status`
 - destination write/failure counts
 - transport write/failure counts
-- async queue state
+- async queue state and lag settings
 - file appender metadata
 - child appender shape for multi-appender output
 - lifecycle warnings
@@ -38,6 +38,8 @@ One practical mapping is:
 | `destinations.*.transport.counts.*` | `julewire_semantic_logger_transport_total{destination,event}` |
 | `destinations.*.transport.appender.queue_size` | `julewire_semantic_logger_queue_size{destination}` |
 | `destinations.*.transport.appender.max_queue_size` | `julewire_semantic_logger_queue_capacity{destination}` |
+| `destinations.*.transport.appender.lag_check_interval` | `julewire_semantic_logger_lag_check_interval{destination}` |
+| `destinations.*.transport.appender.lag_threshold_s` | `julewire_semantic_logger_lag_threshold_seconds{destination}` |
 | `destinations.*.transport.warnings.*` | `julewire_semantic_logger_warning{destination,reason}` |
 
 Treat core health paths as inputs, not as a global metrics schema.

data/docs/transport.md

@@ -64,21 +64,9 @@ Verified paths:
 ## Metric Mapping
 
 The adapter owns metric names because queue, file, and appender behavior is
-transport-specific. One practical mapping is:
-
-| Health path | Metric name |
-| --- | --- |
-| `counts.*` | `julewire_runtime_total{event}` |
-| `pipeline.counts.*` | `julewire_pipeline_total{event}` |
-| `destinations.*.counts.*` | `julewire_destination_total{destination,event}` |
-| `destinations.*.last_loss.reason` | `julewire_destination_last_loss{destination,reason}` |
-| `destinations.*.transport.counts.*` | `julewire_semantic_logger_transport_total{destination,event}` |
-| `destinations.*.transport.appender.queue_size` | `julewire_semantic_logger_queue_size{destination}` |
-| `destinations.*.transport.appender.max_queue_size` | `julewire_semantic_logger_queue_capacity{destination}` |
-| `destinations.*.transport.warnings.*` | `julewire_semantic_logger_warning{destination,reason}` |
-
-Extensions should treat core health paths as inputs, not as a global metrics
-schema.
+transport-specific. The [health guide](health.md#metric-mapping) is the
+canonical mapping; extensions should treat core health paths as inputs, not as
+a global metrics schema.
 
 Observed behavior:
 

data/julewire-semantic_logger.gemspec

@@ -32,7 +32,7 @@ Gem::Specification.new do |spec|
   spec.executables = []
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "julewire-core", ">= 1.0.1"
+  spec.add_dependency "julewire-core", ">= 1.1.0"
   spec.add_dependency "logger", ">= 1.7"
   spec.add_dependency "semantic_logger", ">= 4.18"
   spec.add_dependency "zeitwerk", ">= 2.8.1"

data/lib/julewire/semantic_logger/appender_health.rb

@@ -36,6 +36,8 @@ module Julewire
           {
             active: value.active?,
             capped: value.capped?,
+            lag_check_interval: value.lag_check_interval,
+            lag_threshold_s: value.lag_threshold_s,
             max_queue_size: value.max_queue_size,
             queue_size: value.queue.size,
             wrapped: call(value.appender)

data/lib/julewire/semantic_logger/async_options.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Julewire
+  module SemanticLogger
+    class AsyncOptions
+      DEFAULT_MAX_QUEUE_SIZE = 10_000
+      DEFAULTS = {
+        max_queue_size: DEFAULT_MAX_QUEUE_SIZE,
+        lag_check_interval: 1_000,
+        lag_threshold_s: 30,
+        batch: nil,
+        batch_size: 300,
+        batch_seconds: 5,
+        non_blocking: false,
+        dropped_message_report_seconds: 30,
+        async_max_retries: 100
+      }.freeze
+      BATCH_OPTIONS = { batch_size: true, batch_seconds: true }.freeze
+      KEYWORD_PARAMETER_KINDS = { key: true, keyreq: true }.freeze
+      SUPPORTED_DEFAULTS = DEFAULTS.keys.to_h { [it, true] }.freeze
+      ASYNC_APPENDER = ::SemanticLogger::Appender::Async
+      ASYNC_APPENDER_ACCEPTS_ANY_KEYWORD =
+        ASYNC_APPENDER.instance_method(:initialize).parameters.any? { |kind, _name| kind == :keyrest }
+      ASYNC_BATCH_APPENDER = if ::SemanticLogger::Appender.const_defined?(:AsyncBatch, false)
+                               ::SemanticLogger::Appender.const_get(:AsyncBatch, false)
+                             end
+
+      class << self
+        def extract(options)
+          configured = []
+          values = DEFAULTS.to_h do |name, default|
+            if options.key?(name)
+              configured << name
+              [name, options.delete(name)]
+            else
+              [name, default]
+            end
+          end
+
+          new(values: values, configured: configured)
+        end
+      end
+
+      def initialize(values:, configured:)
+        @values = values
+        @configured = configured
+      end
+
+      def async?(base_async)
+        base_async || batch_enabled?
+      end
+
+      def max_queue_size
+        @values.fetch(:max_queue_size)
+      end
+
+      def build_appender(sink)
+        klass = appender_class
+        klass.new(appender: sink, **constructor_options(klass))
+      end
+
+      private
+
+      if ASYNC_APPENDER_ACCEPTS_ANY_KEYWORD
+        def appender_class
+          ASYNC_APPENDER
+        end
+      else
+        def appender_class
+          return ASYNC_APPENDER unless batch_enabled?
+
+          ASYNC_BATCH_APPENDER
+        end
+      end
+
+      def constructor_options(klass)
+        supported = supported_options(klass)
+        unsupported = unsupported_configured_options(supported)
+        unless unsupported.empty?
+          raise ArgumentError, "#{klass} does not support async option(s): #{unsupported.join(", ")}"
+        end
+
+        DEFAULTS.each_with_object({}) do |(name, _default), kwargs|
+          next unless supported.fetch(name, false)
+
+          value = @values.fetch(name)
+          kwargs[name] = value unless value.nil?
+        end
+      end
+
+      def supported_options(klass)
+        parameters = klass.instance_method(:initialize).parameters
+        return SUPPORTED_DEFAULTS if keyrest_constructor?(parameters)
+
+        parameters.each_with_object({}) do |(kind, name), supported|
+          supported[name] = true if KEYWORD_PARAMETER_KINDS.key?(kind)
+        end
+      end
+
+      def keyrest_constructor?(parameters)
+        parameters.any? { |kind, _name| kind == :keyrest }
+      end
+
+      def unsupported_configured_options(supported)
+        @configured.reject do |name|
+          mode_selector?(name) || supported.fetch(name, false) || default_value?(name) || inactive_batch_option?(name)
+        end
+      end
+
+      def mode_selector?(name)
+        name == :batch
+      end
+
+      def default_value?(name)
+        @values.fetch(name) == DEFAULTS.fetch(name)
+      end
+
+      def inactive_batch_option?(name)
+        BATCH_OPTIONS.key?(name) && !batch_enabled?
+      end
+
+      def batch_enabled?
+        @values.fetch(:batch).equal?(true)
+      end
+    end
+  end
+end

data/lib/julewire/semantic_logger/destination.rb

@@ -21,16 +21,16 @@ module Julewire
       end
 
       def emit(record)
+        degradation_marker = @health.degradation_marker
         formatted = false
         increment(:received)
         payload = @formatter.call(record)
         formatted = true
         @transport.write(encoded_payload(payload), severity: record.fetch(:severity))
-        record_written
+        record_written(degradation_marker)
         nil
       rescue StandardError => e
         record_failure(e, formatted: formatted, record: record)
-        nil
       end
 
       def flush(*) = call_lifecycle(:flush) { @transport.flush }
@@ -46,7 +46,7 @@ module Julewire
       def health
         transport = @transport.health
         @health.snapshot(
-          status: status(@health.degraded?, transport),
+          status: status(transport),
           type: "semantic_logger_destination",
           transport: transport
         )
@@ -71,14 +71,14 @@ module Julewire
         @health.increment(name)
       end
 
-      def record_written
-        @health.increment(:formatted)
-        @health.increment(:written)
-        @health.clear_degraded!
+      def record_written(degradation_marker)
+        increment(:formatted)
+        increment(:written)
+        @health.clear_degradation_if_unchanged(degradation_marker)
       end
 
-      def record_failure(error, formatted: false, record: nil)
-        @health.increment(:formatted) if formatted
+      def record_failure(error, formatted:, record:)
+        increment(:formatted) if formatted
         @health.record_failure(error, destination: name, phase: :destination, record_metadata: record_metadata(record))
         notify_failure(error, phase: :destination, record_metadata: record_metadata(record))
         record_drop(:destination_exception, record)
@@ -90,8 +90,9 @@ module Julewire
       end
 
       def call_lifecycle(action)
+        degradation_marker = @health.degradation_marker
         yield
-        clear_degraded
+        @health.clear_degradation_if_unchanged(degradation_marker)
         true
       rescue StandardError => e
         record_lifecycle_failure(e, action: action)
@@ -126,20 +127,18 @@ module Julewire
       end
 
       def record_metadata(record)
-        Core::Records::Metadata.call(record) if record
-      end
-
-      def status(currently_degraded, transport)
-        transport_status = transport[:status]
-        return :closed if transport_status == :closed
-        return :degraded if currently_degraded
-        return :degraded if transport_status && transport_status != :ok
-
-        :ok
-      end
-
-      def clear_degraded
-        @health.clear_degraded!
+        Core::Records::Metadata.call(record)
+      end
+
+      def status(transport)
+        case transport[:status]
+        when :closed
+          :closed
+        when nil, :ok
+          nil
+        else
+          :degraded
+        end
       end
     end
   end

data/lib/julewire/semantic_logger/transport.rb

@@ -6,7 +6,7 @@ module Julewire
   module SemanticLogger
     class Transport
       LOGGER_NAME = "julewire"
-      DEFAULT_MAX_QUEUE_SIZE = 10_000
+      DEFAULT_MAX_QUEUE_SIZE = AsyncOptions::DEFAULT_MAX_QUEUE_SIZE
       LEVEL_MAP = {
         # SemanticLogger has no unknown level; fatal keeps unknown core records visible.
         unknown: :fatal
@@ -15,14 +15,11 @@ module Julewire
 
       def initialize(**options)
         @mutex = Mutex.new
-        @async = options.delete(:async) { false }
-        @max_queue_size = options.delete(:max_queue_size) { DEFAULT_MAX_QUEUE_SIZE }
-        @lag_check_interval = options.delete(:lag_check_interval) { 1_000 }
-        @lag_threshold_s = options.delete(:lag_threshold_s) { 30 }
-        @write_count = 0
-        @failure_count = 0
-        @degraded = false
-        @closed = false
+        @async = options.delete(:async)
+        @async_options = AsyncOptions.extract(options)
+        @async = @async_options.async?(@async)
+        @max_queue_size = @async_options.max_queue_size
+        @health = Core::Integration::DestinationHealth.new(counter_keys: %i[writes])
         @appenders = build_appenders(
           appenders: options.delete(:appenders),
           appender: options.delete(:appender),
@@ -35,62 +32,50 @@ module Julewire
       end
 
       def write(value, severity:)
+        degradation_marker = @health.degradation_marker
         log = log_for(value, severity: severity)
-        @mutex.synchronize do
-          @write_count += 1
-          # Synchronous appenders write under our mutex; async appenders own
-          # queue synchronization and may block on bounded queues.
-          appender.log(log) unless @async
-        end
+        @health.increment(:writes)
+        @mutex.synchronize { appender.log(log) } unless @async
         appender.log(log) if @async
-        clear_degraded
-        nil
-      rescue StandardError
-        @mutex.synchronize do
-          @failure_count += 1
-          @degraded = true
-        end
+        @health.clear_degradation_if_unchanged(degradation_marker)
+      rescue StandardError => e
+        @health.record_failure(e)
         raise
       end
 
       def flush
-        appender.flush if appender.respond_to?(:flush)
-        clear_degraded
+        degradation_marker = @health.degradation_marker
+        appender.flush
+        @health.clear_degradation_if_unchanged(degradation_marker)
         nil
       end
 
       def close
-        appender.close if appender.respond_to?(:close)
-        @mutex.synchronize { @closed = true }
+        appender.close
+        @closed = true
         nil
       end
 
       def reopen
+        degradation_marker = @health.degradation_marker
         appender.reopen if appender.respond_to?(:reopen)
-        @mutex.synchronize do
-          @closed = false
-          @degraded = false
-        end
+        @closed = false
+        @health.clear_degradation_if_unchanged(degradation_marker)
         nil
       end
 
       def after_fork! = reopen
 
       def health
-        counts = @mutex.synchronize do
-          {
-            closed: @closed,
-            degraded: @degraded,
-            failures: @failure_count,
-            writes: @write_count
-          }
-        end
+        snapshot = @health.snapshot(status: status)
+        counts = snapshot.fetch(:counts)
 
         {
           type: "semantic_logger",
-          status: status(counts),
+          status: snapshot.fetch(:status),
           async: @async,
           warnings: lifecycle_warnings,
+          last_failure: snapshot[:last_failure],
           counts: {
             writes: counts.fetch(:writes),
             failures: counts.fetch(:failures)
@@ -140,12 +125,7 @@ module Julewire
       def build_transport_appender(sink)
         return sink unless @async
 
-        ::SemanticLogger::Appender::Async.new(
-          appender: sink,
-          lag_check_interval: @lag_check_interval,
-          lag_threshold_s: @lag_threshold_s,
-          max_queue_size: @max_queue_size
-        )
+        @async_options.build_appender(sink)
       end
 
       def log_for(value, severity:)
@@ -159,23 +139,20 @@ module Julewire
       end
 
       def semantic_level(value)
-        level = value.is_a?(Symbol) ? value : value.to_s.downcase.to_sym
-        level = LEVEL_MAP.fetch(level, level)
+        level = LEVEL_MAP.fetch(value, value)
         return level if LEVEL_SET.key?(level)
 
         :info
       end
 
-      def status(counts)
-        return :closed if counts.fetch(:closed)
-        return :degraded if appender.is_a?(::SemanticLogger::Appender::Async) && !appender.active?
-        return :degraded if counts.fetch(:degraded)
+      def status
+        return :closed if @closed
 
-        :ok
+        :degraded if async_appender_inactive?
       end
 
-      def clear_degraded
-        @mutex.synchronize { @degraded = false }
+      def async_appender_inactive?
+        @async && !appender.active?
       end
 
       def lifecycle_warnings

data/lib/julewire/semantic_logger/version.rb

@@ -2,6 +2,6 @@
 
 module Julewire
   module SemanticLogger
-    VERSION = "1.0.1"
+    VERSION = "1.1.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: julewire-semantic_logger
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
 platform: ruby
 authors:
 - Alexander Grebennik
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.0.1
+        version: 1.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.0.1
+        version: 1.1.0
 - !ruby/object:Gem::Dependency
   name: logger
   requirement: !ruby/object:Gem::Requirement
@@ -84,6 +84,7 @@ files:
 - lib/julewire-semantic_logger.rb
 - lib/julewire/semantic_logger.rb
 - lib/julewire/semantic_logger/appender_health.rb
+- lib/julewire/semantic_logger/async_options.rb
 - lib/julewire/semantic_logger/destination.rb
 - lib/julewire/semantic_logger/exact_formatter.rb
 - lib/julewire/semantic_logger/lifecycle_warnings.rb
@@ -111,7 +112,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.14
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Semantic Logger transport adapter for Julewire.
 test_files: []