julewire-semantic_logger 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e701488ff85db0998210de87726f8fe7aeb5d8aacefcf6721b86e8d60b5df01b
+  data.tar.gz: e461c66f174f9d83105cbac6e6fa0a457e5387c8ea293ae91bf5599b2d7305d8
+SHA512:
+  metadata.gz: ada163b0d2af3819d88a210193063d7188151a1f298508816bc82ecd4e131790450e7c646c91414db22711fee7c434f5ed2d7d9d5649e2e0dc502b090c6e3d3a
+  data.tar.gz: 98d7f0cb14e358b81164a5f131d7d7e99602554668fa302d7c3e9466747b6f674b2ece1bbae01fb24e0bdc637bd81987f6b9b6b60217ad509f4804503452e885

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+## Unreleased
+
+## 1.0.0 - 2026-06-21
+
+- Initial release: Semantic Logger transport destination with exact payload
+  output, async/file appender support, lifecycle hooks, and health.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Alexander Grebennik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,46 @@
+# Julewire Semantic Logger
+
+`julewire-semantic_logger` is a Semantic Logger transport destination for
+Julewire.
+
+Julewire keeps its own record shape. Semantic Logger owns appender plumbing,
+file/stdout output, optional async queues, flush, close, and reopen.
+
+## Install
+
+```ruby
+gem "julewire-semantic_logger"
+```
+
+## Quickstart
+
+```ruby
+Julewire.configure do |config|
+  config.destinations.use(
+    :semantic_logger,
+    formatter: Julewire::RecordFormatter.new,
+    io: $stdout
+  )
+end
+```
+
+The adapter is synchronous by default. Enable async explicitly:
+
+```ruby
+Julewire.configure do |config|
+  config.destinations.use(
+    :semantic_logger,
+    formatter: Julewire::RecordFormatter.new,
+    io: $stdout,
+    async: true,
+    max_queue_size: 10_000
+  )
+end
+```
+
+## Docs
+
+- [Configuration](docs/configuration.md)
+- [Advanced Configuration](docs/advanced-configuration.md)
+- [Transport](docs/transport.md)
+- [Health](docs/health.md)

data/docs/advanced-configuration.md

@@ -0,0 +1,54 @@
+# Advanced Configuration
+
+## Prebuilt Transport
+
+Pass `transport:` when construction needs to happen outside the destination:
+
+```ruby
+transport = Julewire::SemanticLogger::Transport.new(io: $stdout)
+
+config.destinations.use(
+  :semantic_logger,
+  formatter: Julewire::RecordFormatter.new,
+  transport: transport
+)
+```
+
+## Prebuilt Appenders
+
+Pass an existing Semantic Logger appender with `appender:`:
+
+```ruby
+config.destinations.use(
+  :semantic_logger,
+  formatter: Julewire::RecordFormatter.new,
+  appender: my_appender
+)
+```
+
+## Async Lag Options
+
+These options are passed to `SemanticLogger::Appender::Async` when
+`async: true`:
+
+| Option | Default |
+| --- | --- |
+| `lag_check_interval:` | `1_000` |
+| `lag_threshold_s:` | `30` |
+
+## Appender Defaults
+
+Unknown transport options are merged into each appender spec. This is useful for
+Semantic Logger appender-specific options:
+
+```ruby
+config.destinations.use(
+  :semantic_logger,
+  formatter: Julewire::RecordFormatter.new,
+  appenders: [
+    { io: $stdout },
+    { file_name: "log/julewire.log" }
+  ],
+  level: :debug
+)
+```

data/docs/configuration.md

@@ -0,0 +1,87 @@
+# Configuration
+
+`julewire-semantic_logger` registers the `:semantic_logger` destination kind.
+
+```ruby
+Julewire.configure do |config|
+  config.destinations.use(
+    :semantic_logger,
+    formatter: Julewire::RecordFormatter.new,
+    io: $stdout
+  )
+end
+```
+
+## Destination Options
+
+| Option | Meaning |
+| --- | --- |
+| `name:` | Destination name. Required. |
+| `formatter:` | Julewire formatter object. Required. |
+| `encoder:` | Julewire encoder object. Defaults to core JSON without a trailing newline. |
+| `transport:` | Prebuilt `Julewire::SemanticLogger::Transport`. |
+| `**transport_options` | Passed to `Transport.new` when `transport:` is omitted. |
+
+The destination passes the immutable Julewire record to `formatter`, then hands
+the formatter result through `encoder`. The transport receives the encoded
+string. String formatter results are treated as already encoded and lose one
+trailing newline when present.
+
+## Transport Options
+
+At least one appender target is required.
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `io:` | none | IO appender target such as `$stdout`. |
+| `file_name:` | none | File appender target. |
+| `appender:` | none | Existing Semantic Logger appender. |
+| `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. |
+
+Unknown transport options are passed to Semantic Logger appender construction.
+
+## Appender Specs
+
+Single stdout appender:
+
+```ruby
+config.destinations.use(
+  :semantic_logger,
+  formatter: Julewire::RecordFormatter.new,
+  io: $stdout
+)
+```
+
+Multiple appenders:
+
+```ruby
+config.destinations.use(
+  :semantic_logger,
+  formatter: Julewire::RecordFormatter.new,
+  appenders: [
+    { io: $stdout },
+    { file_name: "log/julewire.log" }
+  ]
+)
+```
+
+Async output:
+
+```ruby
+config.destinations.use(
+  :semantic_logger,
+  formatter: Julewire::RecordFormatter.new,
+  io: $stdout,
+  async: true,
+  max_queue_size: 10_000
+)
+```
+
+Async moves blocking and drop behavior into Semantic Logger's queue. Keep
+`max_queue_size` explicit and call `Julewire.flush` before shutdown when queued
+records matter.
+
+For multi-appender output, async lag options, and prebuilt appenders, see
+[Advanced Configuration](advanced-configuration.md).

data/docs/health.md

@@ -0,0 +1,43 @@
+# Health
+
+The destination health surface is transport-shaped.
+
+```ruby
+Julewire.health
+```
+
+Destination health includes:
+
+- destination `status`
+- destination write/failure counts
+- transport write/failure counts
+- async queue state
+- file appender metadata
+- child appender shape for multi-appender output
+- lifecycle warnings
+
+Lifecycle warnings currently include:
+
+- `:async_queue_blocks_when_full`
+- `:async_queue_unbounded`
+- `:sync_multi_appender_blocks_emitters`
+
+The adapter does not recreate transport-level drop taxonomy. Semantic Logger
+owns async worker behavior; Julewire reports the transport state it can observe.
+
+## Metric Mapping
+
+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}` |
+
+Treat core health paths as inputs, not as a global metrics schema.

data/docs/transport.md

@@ -0,0 +1,108 @@
+# Semantic Logger Transport
+
+The adapter uses Semantic Logger as transport only.
+
+It does not use Semantic Logger's JSON formatter for Julewire records because
+that formatter emits Semantic Logger's schema. Julewire formatters already own
+the output shape.
+
+## Destination Path
+
+```text
+Julewire formatter -> Julewire encoder -> Semantic Logger exact formatter -> IO
+```
+
+This uses the adapter destination. The destination maps the record with the
+configured formatter, encodes the formatter result with Julewire's encoder, then
+hands the encoded payload string to Semantic Logger. The exact formatter
+preserves that string shape for appenders.
+
+```ruby
+class LogShape
+  def call(record)
+    {
+      level: record.fetch(:severity),
+      message: record.fetch(:message),
+      labels: record.fetch(:labels),
+      payload: record.fetch(:payload)
+    }
+  end
+end
+
+Julewire.configure do |config|
+  config.destinations.use(
+    :semantic_logger,
+    formatter: LogShape.new,
+    io: $stdout,
+    async: true
+  )
+end
+```
+
+Core passes a frozen, normalized, symbol-key record to the destination
+formatter. The adapter formatter returns the output object; the destination
+encoder turns that object into the final JSON payload.
+
+## Design
+
+Semantic Logger fits as transport if Julewire owns record mapping.
+
+Semantic Logger does not fit as the default formatter unless Julewire accepts
+Semantic Logger's log schema.
+
+## Verified Paths
+
+Verified paths:
+
+- custom destination object formatter -> Julewire-encoded JSON line through Semantic Logger
+- async Semantic Logger appender -> flush drains queued entries
+- file appender -> writes exact Julewire payload JSON lines
+- multiple appenders -> multi-appender output without Julewire owning transport code
+- health -> appender type, async queue state, file metadata, child appenders,
+  transport warnings
+
+## 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.
+
+Observed behavior:
+
+- Semantic Logger's IO appender appends the final newline, so this adapter strips
+  one trailing newline when it receives an already encoded string.
+- Output-shaped severity values such as `"INFO"` should not be treated as
+  Semantic Logger levels. The transport maps only known levels and otherwise
+  uses `:info`. Julewire `:unknown` maps to Semantic Logger `:fatal`.
+- bounded Semantic Logger async queues block producers when full; the adapter
+  reports this as a lifecycle warning.
+- `max_queue_size: -1` is unbounded queueing; the adapter reports that as a
+  lifecycle warning.
+- sync multi-appender output writes through all child appenders on the caller
+  thread; the adapter reports that as a lifecycle warning when more than one
+  appender is configured and `async: false`.
+- `flush(timeout:)`, `close(timeout:)`, and `reopen(timeout:)` accept Julewire's
+  lifecycle keyword for the destination contract, but Semantic Logger appenders
+  own the actual blocking behavior. The timeout is advisory for this adapter.
+- `after_fork!` delegates to `reopen`, matching Semantic Logger's fork contract:
+  async appender queues and worker threads are recreated in the child process.
+
+Architecture implication:
+
+- using Semantic Logger as a destination transport is clean
+- using Semantic Logger as the record schema is not
+- core formatters should return objects; encoders own final serialization
+- core should not grow async/file/multi-appender transport primitives

data/julewire-semantic_logger.gemspec

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "lib/julewire/semantic_logger/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "julewire-semantic_logger"
+  spec.version = Julewire::SemanticLogger::VERSION
+  spec.authors = ["Alexander Grebennik"]
+  spec.email = ["slbug@users.noreply.github.com", "sl.bug.sl@gmail.com"]
+
+  spec.summary = "Semantic Logger transport adapter for Julewire."
+  spec.description = "Semantic Logger transport adapter for Julewire destination output."
+  spec.homepage = "https://github.com/slbug/julewire"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.4"
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/slbug/julewire/tree/main/gems/semantic_logger"
+  spec.metadata["changelog_uri"] = "https://github.com/slbug/julewire/blob/main/gems/semantic_logger/CHANGELOG.md"
+
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = Dir.chdir(__dir__) do
+    Dir[
+      "CHANGELOG.md",
+      "LICENSE.txt",
+      "README.md",
+      "docs/**/*.md",
+      "julewire-semantic_logger.gemspec",
+      "lib/**/*.rb"
+    ]
+  end
+  spec.executables = []
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "julewire-core", ">= 1.0"
+  spec.add_dependency "logger", ">= 1.7"
+  spec.add_dependency "semantic_logger", ">= 4.18"
+  spec.add_dependency "zeitwerk", ">= 2.8.1"
+end

data/lib/julewire/semantic_logger/appender_health.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Julewire
+  module SemanticLogger
+    module AppenderHealth
+      class << self
+        def call(value, index: nil)
+          {
+            appender_class: value.class.name,
+            index: index,
+            type: appender_type(value)
+          }.compact
+            .merge(async_health(value))
+            .merge(file_health(value))
+            .merge(collection_health(value))
+        end
+
+        def appender_type(value)
+          case value
+          when ::SemanticLogger::Appender::Async
+            "async"
+          when ::SemanticLogger::Appenders
+            "multi_appender"
+          when ::SemanticLogger::Appender::File
+            "file"
+          when ::SemanticLogger::Appender::IO
+            "io"
+          else
+            "appender"
+          end
+        end
+
+        def async_health(value)
+          return {} unless value.is_a?(::SemanticLogger::Appender::Async)
+
+          {
+            active: value.active?,
+            capped: value.capped?,
+            max_queue_size: value.max_queue_size,
+            queue_size: value.queue.size,
+            wrapped: call(value.appender)
+          }
+        end
+
+        def file_health(value)
+          return {} unless value.is_a?(::SemanticLogger::Appender::File)
+
+          {
+            current_file_name: value.current_file_name,
+            file_name: value.file_name,
+            log_count: value.log_count,
+            log_size: value.log_size,
+            reopen_at: value.reopen_at&.utc&.iso8601
+          }
+        end
+
+        def collection_health(value)
+          return {} unless value.is_a?(::SemanticLogger::Appenders)
+
+          {
+            appender_count: value.length,
+            appenders: value.each_with_index.map { |child, index| call(child, index: index) }
+          }
+        end
+      end
+    end
+  end
+end

data/lib/julewire/semantic_logger/destination.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Julewire
+  module SemanticLogger
+    class Destination
+      attr_reader :name
+
+      def initialize(name:, formatter:, encoder: ENCODER, transport: nil, on_drop: nil, on_failure: nil,
+                     **transport_options)
+        @name = Core::Destinations.normalize_name(name)
+        @formatter = formatter
+        @encoder = encoder
+        @on_drop = validate_optional_callback(on_drop, name: :on_drop)
+        @on_failure = validate_optional_callback(on_failure, name: :on_failure)
+        @transport = transport || Transport.new(**transport_options)
+        @health = Core::Integration::DestinationHealth.new(
+          counter_keys: %i[received formatted written failed],
+          failure_counter: :failed
+        )
+      end
+
+      def emit(record)
+        formatted = false
+        increment(:received)
+        payload = @formatter.call(record)
+        formatted = true
+        @transport.write(encoded_payload(payload), severity: record.fetch(:severity))
+        record_written
+        nil
+      rescue StandardError => e
+        record_failure(e, formatted: formatted, record: record)
+        nil
+      end
+
+      def flush(*) = call_lifecycle(:flush) { @transport.flush }
+
+      def close(*) = call_lifecycle(:close) { @transport.close }
+
+      def reopen(*) = call_lifecycle(:reopen) { @transport.reopen }
+
+      def after_fork! = call_lifecycle(:after_fork) { @transport.after_fork! }
+
+      def resource_identity = @transport
+
+      def health
+        transport = @transport.health
+        @health.snapshot(
+          status: status(@health.degraded?, transport),
+          type: "semantic_logger_destination",
+          transport: transport
+        )
+      end
+
+      private
+
+      def validate_optional_callback(callback, name:)
+        return unless callback
+        return callback if callback.respond_to?(:call)
+
+        raise ArgumentError, "#{name} must respond to #call"
+      end
+
+      def encoded_payload(payload)
+        return payload if payload.is_a?(String)
+
+        @encoder.call(payload)
+      end
+
+      def increment(name)
+        @health.increment(name)
+      end
+
+      def record_written
+        @health.increment(:formatted)
+        @health.increment(:written)
+        @health.clear_degraded!
+      end
+
+      def record_failure(error, formatted: false, record: nil)
+        @health.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)
+      end
+
+      def record_lifecycle_failure(error, action:)
+        @health.record_failure(error, destination: name, action: action, phase: :destination_lifecycle)
+        notify_failure(error, action: action, phase: :destination_lifecycle)
+      end
+
+      def call_lifecycle(action)
+        yield
+        clear_degraded
+        true
+      rescue StandardError => e
+        record_lifecycle_failure(e, action: action)
+        false
+      end
+
+      def notify_failure(error, **metadata)
+        Core::Diagnostics::CallbackNotifier.call(@on_failure, error, { destination: name }.merge(metadata))
+      end
+
+      def record_drop(reason, record)
+        Core::Diagnostics::CallbackNotifier.call(
+          @on_drop,
+          reason,
+          {
+            destination: name,
+            phase: :destination,
+            reason: reason,
+            record_metadata: record_metadata(record)
+          }
+        )
+      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!
+      end
+    end
+  end
+end

data/lib/julewire/semantic_logger/exact_formatter.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Julewire
+  module SemanticLogger
+    class ExactFormatter
+      PAYLOAD_KEY = :julewire_value
+
+      def call(log, _logger = nil)
+        value = log.payload.fetch(PAYLOAD_KEY)
+        return string_value(value) if value.is_a?(String)
+
+        ENCODER.call(value)
+      end
+
+      private
+
+      def string_value(value)
+        return value.delete_suffix("\n") if value.end_with?("\n")
+        return value.dup if value.frozen?
+
+        value
+      end
+    end
+  end
+end

data/lib/julewire/semantic_logger/lifecycle_warnings.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Julewire
+  module SemanticLogger
+    module LifecycleWarnings
+      class << self
+        def call(async:, appender_count:, max_queue_size:)
+          if async && max_queue_size == -1
+            [{ reason: :async_queue_unbounded }]
+          elsif async
+            [{ reason: :async_queue_blocks_when_full, max_queue_size: max_queue_size }]
+          elsif appender_count > 1
+            [{ reason: :sync_multi_appender_blocks_emitters, appender_count: appender_count }]
+          else
+            []
+          end
+        end
+      end
+    end
+  end
+end

data/lib/julewire/semantic_logger/transport.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Julewire
+  module SemanticLogger
+    class Transport
+      LOGGER_NAME = "julewire"
+      DEFAULT_MAX_QUEUE_SIZE = 10_000
+      LEVEL_MAP = {
+        # SemanticLogger has no unknown level; fatal keeps unknown core records visible.
+        unknown: :fatal
+      }.freeze
+      LEVEL_SET = ::SemanticLogger::LEVELS.to_h { [it, true] }.freeze
+
+      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
+        @appenders = build_appenders(
+          appenders: options.delete(:appenders),
+          appender: options.delete(:appender),
+          file_name: options.delete(:file_name),
+          io: options.delete(:io),
+          options: options
+        )
+        @sink = build_sink(@appenders)
+        @appender = build_transport_appender(@sink)
+      end
+
+      def write(value, severity:)
+        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
+        appender.log(log) if @async
+        clear_degraded
+        nil
+      rescue StandardError
+        @mutex.synchronize do
+          @failure_count += 1
+          @degraded = true
+        end
+        raise
+      end
+
+      def flush
+        appender.flush if appender.respond_to?(:flush)
+        clear_degraded
+        nil
+      end
+
+      def close
+        appender.close if appender.respond_to?(:close)
+        @mutex.synchronize { @closed = true }
+        nil
+      end
+
+      def reopen
+        appender.reopen if appender.respond_to?(:reopen)
+        @mutex.synchronize do
+          @closed = false
+          @degraded = false
+        end
+        nil
+      end
+
+      def after_fork! = reopen
+
+      def health
+        counts = @mutex.synchronize do
+          {
+            closed: @closed,
+            degraded: @degraded,
+            failures: @failure_count,
+            writes: @write_count
+          }
+        end
+
+        {
+          type: "semantic_logger",
+          status: status(counts),
+          async: @async,
+          warnings: lifecycle_warnings,
+          counts: {
+            writes: counts.fetch(:writes),
+            failures: counts.fetch(:failures)
+          },
+          appender: appender_health(appender),
+          appenders: @appenders.each_with_index.map { |child, index| appender_health(child, index: index) }
+        }
+      end
+
+      private
+
+      attr_reader :appender
+
+      def build_appenders(appenders:, appender:, file_name:, io:, options:)
+        specs = appenders.is_a?(Hash) ? [appenders] : Array(appenders).dup
+        specs << { appender: appender } if appender
+        specs << { file_name: file_name } if file_name
+        specs << { io: io } if io
+        raise ArgumentError, "semantic logger transport requires io, file_name, appender, or appenders" if specs.empty?
+
+        specs.map { build_appender(it, defaults: options) }
+      end
+
+      def build_appender(spec, defaults:)
+        options = normalize_appender_spec(spec, defaults: defaults)
+        options[:formatter] ||= ExactFormatter.new
+        ::SemanticLogger::Appender.factory(**options, async: false, batch: false)
+      end
+
+      def normalize_appender_spec(spec, defaults:)
+        case spec
+        when Hash
+          defaults.merge(spec)
+        else
+          defaults.merge(appender: spec)
+        end
+      end
+
+      def build_sink(appenders)
+        return appenders.first if appenders.one?
+
+        ::SemanticLogger::Appenders.new.tap do |collection|
+          appenders.each { collection << it }
+        end
+      end
+
+      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
+        )
+      end
+
+      def log_for(value, severity:)
+        log = ::SemanticLogger::Log.new(LOGGER_NAME, level_for(severity))
+        log.assign(payload: { ExactFormatter::PAYLOAD_KEY => value })
+        log
+      end
+
+      def level_for(severity)
+        semantic_level(severity)
+      end
+
+      def semantic_level(value)
+        level = value.is_a?(Symbol) ? value : value.to_s.downcase.to_sym
+        level = LEVEL_MAP.fetch(level, level)
+        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)
+
+        :ok
+      end
+
+      def clear_degraded
+        @mutex.synchronize { @degraded = false }
+      end
+
+      def lifecycle_warnings
+        LifecycleWarnings.call(async: @async, appender_count: @appenders.length, max_queue_size: @max_queue_size)
+      end
+
+      def appender_health(value, index: nil)
+        AppenderHealth.call(value, index: index)
+      end
+    end
+  end
+end

data/lib/julewire/semantic_logger/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Julewire
+  module SemanticLogger
+    VERSION = "1.0.0"
+  end
+end

data/lib/julewire/semantic_logger.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "zeitwerk"
+require "julewire/core"
+require "semantic_logger"
+
+module Julewire
+  module SemanticLogger
+    ENCODER = Julewire::JsonEncoder.new(append_newline: false).freeze
+    private_constant :ENCODER
+  end
+
+  loader = Zeitwerk::Loader.for_gem_extension(self)
+  loader.setup
+  Core::Destinations.register(:semantic_logger) do |name:, **options|
+    Julewire::SemanticLogger::Destination.new(name: name, **options)
+  end
+end

data/lib/julewire-semantic_logger.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "julewire/semantic_logger"

metadata

@@ -0,0 +1,117 @@
+--- !ruby/object:Gem::Specification
+name: julewire-semantic_logger
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Alexander Grebennik
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: julewire-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: semantic_logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.18'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.18'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.8.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.8.1
+description: Semantic Logger transport adapter for Julewire destination output.
+email:
+- slbug@users.noreply.github.com
+- sl.bug.sl@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- docs/advanced-configuration.md
+- docs/configuration.md
+- docs/health.md
+- docs/transport.md
+- julewire-semantic_logger.gemspec
+- lib/julewire-semantic_logger.rb
+- lib/julewire/semantic_logger.rb
+- lib/julewire/semantic_logger/appender_health.rb
+- lib/julewire/semantic_logger/destination.rb
+- lib/julewire/semantic_logger/exact_formatter.rb
+- lib/julewire/semantic_logger/lifecycle_warnings.rb
+- lib/julewire/semantic_logger/transport.rb
+- lib/julewire/semantic_logger/version.rb
+homepage: https://github.com/slbug/julewire
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/slbug/julewire
+  source_code_uri: https://github.com/slbug/julewire/tree/main/gems/semantic_logger
+  changelog_uri: https://github.com/slbug/julewire/blob/main/gems/semantic_logger/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.14
+specification_version: 4
+summary: Semantic Logger transport adapter for Julewire.
+test_files: []