pinqloq 1.1.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b34593f2d1e32afe9a03124e36c7b3b824eb8155ba7a16156f113928e605cddf
+  data.tar.gz: f0ac5ed9f372d187d8d15be83e4a8832bc1637e190c18773fbf36925bd8b9b60
+SHA512:
+  metadata.gz: bcfb49cb5f6c33f5aa27c1f52e94e3d42f53efad2aee1808bb4c866fc36517e386bf12875257c2abf2e190a21d1b685e8d82d5c8fdf988b9ba8da424c089c0a6
+  data.tar.gz: 976f6719d2d3ffddc12c54f9ac98f50676b1c948fd5dad6ccd516afd16d78d1c451f12eac8cae271b733626e1fa36cdd9cd28afc57bdb39903e0b3f1d0777e2e

data/CHANGELOG.md

@@ -0,0 +1,68 @@
+# Changelog
+
+All notable changes to the `pinqloq` gem are documented here. This gem follows
+[Semantic Versioning](https://semver.org). Its version numbers are independent of the .NET
+`pinqloq` NuGet package and the `pinqloq` npm package — all three ship on separate cadences for
+the same platform, and mirror each other's feature set rather than their version numbers.
+
+## 1.1.2 — 2026-09-08
+
+**Fixed:**
+
+- Every batch failed to send, silently from the app's perspective (only a throttled warning in
+  the application log), whenever nothing else in the host process had already `require`d Ruby's
+  `time` standard library. `IngestApiClient` called `Time#iso8601` — a method the `time` library
+  monkey-patches onto `Time`, not one Ruby's core `Time` class defines — without ever requiring
+  it itself. It worked by accident in this gem's own test suite (`webmock` pulls in `time`
+  transitively) and in apps that happened to load another gem which requires `time`, and failed
+  silently in a plain Sinatra app that doesn't. `ingest_api_client.rb` now requires `time`
+  directly.
+
+## 1.1.1 — 2026-09-08
+
+**Fixed:**
+
+- The request-logging middleware raised `NoMethodError` on the first request whenever
+  `rack.input` did not respond to `rewind` — notably `Rack::Lint::Wrapper::InputWrapper`, which
+  Sinatra (and many Rack apps) enable by default in the development environment. The middleware
+  now falls back to buffering the full body and replacing `rack.input` with a rewindable
+  `StringIO` when the original input can't be rewound in place, so downstream handlers still see
+  the complete request body either way.
+
+## 1.1.0 — 2026-09-08
+
+**Added:**
+
+- `LogEntry#path` — a fixed, indexed field for the request path, matching the .NET SDK's 4.3.0
+  wire contract change ([pinqponq/pinqloq#108](https://github.com/pinqponq/pinqloq/issues/108)).
+  The request-logging middleware fills it automatically; on a manual `enqueue` it stays `nil`
+  unless set explicitly.
+
+**Changed:**
+
+- `event` and `path` are no longer duplicated into `metadata`. The request-logging middleware
+  used to also write `metadata["event"]`, `metadata["path"]`, and `metadata["RequestPath"]` —
+  those keys are gone from newly-sent logs now that `event` and `path` travel as their own
+  fixed, indexed fields. A `metadata: { "event" => ... }` enricher still overrides the event
+  title; it just no longer leaves a copy behind in `metadata`.
+
+If you built a saved filter or dashboard on `metadata.event`, `metadata.path`, or
+`metadata.RequestPath`, switch it to the `Event` / `Path` fields directly. No other consumer
+action is needed — existing code compiles unchanged.
+
+## 1.0.0 — 2026-09-08
+
+**Added:**
+
+- Initial release: feature parity with the .NET and Node.js SDKs' core surface.
+- `Pinqloq.create(...)` — buffered, batched manual structured logging (`logger.enqueue` /
+  `logger.enqueue_many`), delivered to the same `/bulk` ingest endpoint the other SDKs use.
+- `Pinqloq::Rack::RequestLogging` — a Rack middleware (works with Rails, Sinatra, Hanami, Grape,
+  or any Rack app) for automatic HTTP request/response logging: captures method/path/status/
+  duration, request/response bodies (32KB cap) and headers, resolves `device_identifier`
+  (resolver → `device-identifier` header → global fallback, HTTP 400 if none resolve) and
+  `correlation_id` (`correlation-id` header → generated UUID).
+- Redaction: a built-in, unconditional credential-name floor (password, token, Authorization,
+  ...) plus `redact_fields` (name-based, any nesting depth) and `redact_paths` (whole-body/header
+  masking, the `[PinqloqRedactEndpoint]` equivalent). Fails closed on a sensitive body that can't
+  be parsed as JSON, matching the .NET and Node SDKs' behavior.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pinqponq
+
+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,177 @@
+# Pinqloq (Ruby / Rack)
+
+[![Gem](https://img.shields.io/gem/v/pinqloq)](https://rubygems.org/gems/pinqloq)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+Pinqloq is a structured logging and log shipping SDK for centralized application logs. It
+captures HTTP request/response logs through a Rack middleware and sends manual application events
+to the Pinqloq log management platform using in-memory buffering, batching, and HTTPS delivery.
+This is the Ruby counterpart of the [.NET](https://www.nuget.org/packages/pinqloq) and
+[Node.js](https://www.npmjs.com/package/pinqloq) `pinqloq` SDKs — same platform, same wire
+protocol, idiomatic API on each side.
+
+Because the middleware targets [Rack](https://github.com/rack/rack) rather than one framework, it
+works unmodified with Rails, Sinatra, Hanami, Grape, or a bare Rack app.
+
+## Features
+
+- Automatic Rack request/response logging — works with any Rack-based framework
+- Correlation id read from the caller's header, falling back to a generated UUID
+- Name-based redaction of sensitive fields, headers, and whole endpoints
+- Manual structured application events
+- Buffered and batched HTTPS delivery, backed by a single background thread
+- Graceful shutdown flush
+
+## Requirements
+
+- Ruby 3.1 or later
+- A Pinqloq project and secret key
+
+## Installation
+
+```bash
+gem install pinqloq
+```
+
+Or in a `Gemfile`:
+
+```ruby
+gem "pinqloq"
+```
+
+## Quick Start
+
+Store your secret key in an environment variable or a secret manager. Do not hardcode production
+credentials.
+
+```ruby
+require "pinqloq"
+
+pinqloq = Pinqloq.create(
+  secret_key: ENV.fetch("PINQLOQ_SECRET_KEY"),
+  api_logs_collection_name: "myapp_api_logs",
+  device_identifier: "myapp-instance-1"
+)
+
+# Rack app / Rails config/application.rb / config.ru
+use Pinqloq::Rack::RequestLogging,
+    logger: pinqloq.logger,
+    pinqloq_options: pinqloq.options,
+    exclude_paths: ["/health"]
+
+at_exit { pinqloq.shutdown }
+```
+
+The middleware captures the HTTP method, path, and status code as searchable metadata. The
+request body, response body, request headers, and response headers go to the log detail as
+`InputJson`, `OutputJson`, `RequestHeaders`, and `ResponseHeaders`. Bodies are truncated at 32 KB.
+
+## Manual Logging
+
+Use `pinqloq.logger` to send structured application events:
+
+```ruby
+pinqloq.logger.enqueue(
+  Pinqloq::LogEntry.new(
+    event: "order.created",
+    device_identifier: order.customer_id,
+    log_level: Pinqloq::LogLevel::INFORMATION,
+    log_source_type: Pinqloq::LogSourceType::BACKEND,
+    metadata: { "orderId" => order.id }
+  )
+)
+```
+
+`event` and `device_identifier` are required on every entry. Leave `device_identifier` unset on
+an entry to inherit the global `device_identifier` option. `enqueue` raises if an entry has no
+`device_identifier` and no global fallback is set — a missing required field fails loudly rather
+than being silently dropped.
+
+## Add Request Metadata
+
+By default the middleware reads the required `device_identifier` from the `device-identifier`
+request header automatically. Override how it is resolved with `resolve_device_identifier`; the
+override wins, and if it returns nil/blank the middleware falls back to the `device-identifier`
+header, then to the global `device_identifier` option. If none of these resolve a value, the
+middleware rejects the request with **HTTP 400** before it runs.
+
+```ruby
+use Pinqloq::Rack::RequestLogging,
+    logger: pinqloq.logger,
+    pinqloq_options: pinqloq.options,
+    exclude_paths: ["/health"],
+    resolve_device_identifier: ->(request) { request.session[:user_id] },
+    resolve_app_version_name: ->(request) { request.get_header("HTTP_X_APP_VERSION") },
+    metadata: {
+      "userId" => ->(request, _status, _headers) { request.session[:user_id] }
+    }
+```
+
+Use `metadata` for searchable values such as user and tenant IDs. Use `detail` for additional
+drill-down information. The `event` key (the panel title) defaults to `"{method} {path}"` and can
+be overridden via `metadata["event"]`.
+
+## Correlation ID
+
+Every log carries a `correlation_id` that ties together the records of a single request or flow.
+The request-logging middleware fills it with no configuration: the caller's `correlation-id`
+request header when present, otherwise a generated UUID.
+
+```ruby
+pinqloq.logger.enqueue(
+  Pinqloq::LogEntry.new(
+    event: "order.created",
+    device_identifier: order.customer_id,
+    correlation_id: current_correlation_id
+  )
+)
+```
+
+## Redacting Sensitive Values
+
+Request and response bodies and headers may contain credentials, tokens, or personal information.
+Unlike the .NET SDK's attribute-based redaction (which relies on C# reflection over typed DTOs —
+not available the same way in Ruby's dynamically-typed request/response objects), this SDK
+redacts by **name**, exactly like the Node.js SDK:
+
+- `redact_fields` — case-insensitive field/header names masked with `*****REDACTED*****` wherever
+  they appear in a captured body or header, at any nesting depth.
+- `redact_paths` — path prefixes (matched the same way as `exclude_paths`) where every value in
+  `InputJson`, `OutputJson`, `RequestHeaders`, and `ResponseHeaders` is masked, keeping the JSON
+  structure and header names intact.
+
+```ruby
+use Pinqloq::Rack::RequestLogging,
+    logger: pinqloq.logger,
+    pinqloq_options: pinqloq.options,
+    redact_fields: ["ssn_last_four"],
+    redact_paths: ["/payment"]
+```
+
+A built-in, unconditional floor of common credential names (password, token, `Authorization`,
+card numbers, ...) is always masked, even with no configuration — see
+[`lib/pinqloq/redaction/redaction_plan.rb`](lib/pinqloq/redaction/redaction_plan.rb) for the full
+list.
+
+## Security and Reliability
+
+Logs are buffered in memory and sent in batches by a single background thread. Buffered logs may
+be lost if the process is terminated without a graceful shutdown — call `pinqloq.shutdown` on
+exit (`at_exit`, a `Rails.application.config.after_initialize` shutdown hook, or your process
+manager's stop signal handler).
+
+Delivery failures are reported through `on_failed` callbacks and, even without callbacks, as
+throttled warnings via Ruby's `Kernel#warn` — never silently discarded, but also never blocking.
+If your secret key is authorized for more than one collection, set `api_logs_collection_name` (or
+a per-entry `collection_name`); otherwise the batch is rejected.
+
+## Documentation
+
+- [.NET SDK](https://www.nuget.org/packages/pinqloq), [Node.js SDK](https://www.npmjs.com/package/pinqloq),
+  [Go SDK](https://pkg.go.dev/github.com/pinqponq/pinqloq-go-sdk) — the other implementations of
+  this platform's wire protocol and feature set.
+- [Full documentation](https://pinqloq.pinqponq.io/documentation.html)
+
+## License
+
+MIT

data/lib/pinqloq/buffering/callback.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Pinqloq
+  module Buffering
+    module Callback
+      module_function
+
+      def raise_sent(on_sent, entry)
+        return unless on_sent
+
+        begin
+          on_sent.call(entry)
+        rescue StandardError => e
+          warn "Pinqloq: the on_sent callback raised an exception; swallowed. #{e.class}: #{e.message}"
+        end
+      end
+
+      def raise_failed(on_failed, entry, error)
+        return unless on_failed
+
+        begin
+          on_failed.call(entry, error)
+        rescue StandardError => e
+          warn "Pinqloq: the on_failed callback raised an exception; swallowed. #{e.class}: #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/pinqloq/buffering/log_buffer.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative "../log_failure_reason"
+require_relative "queued_log"
+require_relative "callback"
+
+module Pinqloq
+  module Buffering
+    class LogBuffer
+      def initialize(capacity)
+        @capacity = capacity
+        @queue = []
+        @dropped_count = 0
+        @closed = false
+        @mutex = Mutex.new
+      end
+
+      def size
+        @mutex.synchronize { @queue.size }
+      end
+
+      def enqueue(entry, on_sent: nil, on_failed: nil)
+        raise "Pinqloq: the log queue is closed." if @closed
+        return false if entry.nil?
+
+        entry.date ||= Time.now.utc
+
+        dropped = false
+        @mutex.synchronize do
+          if @queue.size >= @capacity
+            @dropped_count += 1
+            dropped = true
+          else
+            @queue.push(QueuedLog.new(entry: entry, on_sent: on_sent, on_failed: on_failed))
+          end
+        end
+
+        return true unless dropped
+
+        warn "Pinqloq: log queue is full; #{@dropped_count} logs dropped so far." if @dropped_count == 1 || (@dropped_count % 1000).zero?
+
+        Callback.raise_failed(
+          on_failed,
+          entry,
+          LogError.new(
+            reason: LogFailureReason::QUEUE_FULL,
+            message: "Log queue is full; the log was dropped. Increase queue_capacity or lower flush_interval."
+          )
+        )
+
+        false
+      end
+
+      def enqueue_many(entries, on_sent: nil, on_failed: nil)
+        return 0 if entries.nil?
+
+        entries.count { |entry| enqueue(entry, on_sent: on_sent, on_failed: on_failed) }
+      end
+
+      def close!
+        @mutex.synchronize { @closed = true }
+      end
+
+      def closed?
+        @mutex.synchronize { @closed }
+      end
+
+      def drain(max)
+        @mutex.synchronize { @queue.shift(max) }
+      end
+    end
+  end
+end

data/lib/pinqloq/buffering/log_dispatcher.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Pinqloq
+  module Buffering
+    class LogDispatcher
+      def initialize(buffer, api_client, options)
+        @buffer = buffer
+        @api_client = api_client
+        @options = options
+        @mutex = Mutex.new
+        @condition = ConditionVariable.new
+        @stopping = false
+        @thread = nil
+      end
+
+      def start
+        return if @thread
+
+        @thread = Thread.new { run }
+      end
+
+      def notify_enqueued
+        @mutex.synchronize { @condition.signal }
+      end
+
+      def shutdown
+        @mutex.synchronize do
+          @stopping = true
+          @condition.signal
+        end
+        @thread&.join
+        @thread = nil
+      end
+
+      private
+
+      def run
+        loop do
+          wait_for_first_entry
+          return if finished?
+
+          batch_window
+        end
+      end
+
+      def wait_for_first_entry
+        @mutex.synchronize do
+          @condition.wait(@mutex) while @buffer.size.zero? && !@stopping
+        end
+      end
+
+      def finished?
+        @buffer.size.zero? && @stopping
+      end
+
+      def batch_window
+        deadline = monotonic_now + @options.flush_interval
+
+        @mutex.synchronize do
+          while @buffer.size < @options.batch_size && !@stopping
+            remaining = deadline - monotonic_now
+            break if remaining <= 0
+
+            @condition.wait(@mutex, remaining)
+          end
+        end
+
+        send_batch(@buffer.drain(@options.batch_size))
+
+        send_batch(@buffer.drain(@options.batch_size)) while @stopping && @buffer.size.positive?
+      end
+
+      def send_batch(batch)
+        return if batch.empty?
+
+        @api_client.send_batch(batch)
+      rescue StandardError => e
+        warn "Pinqloq: batch of #{batch.length} logs could not be sent; dropped. #{e.class}: #{e.message}"
+      end
+
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/pinqloq/buffering/queued_log.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Pinqloq
+  module Buffering
+    QueuedLog = Struct.new(:entry, :on_sent, :on_failed, keyword_init: true)
+  end
+end

data/lib/pinqloq/client.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "options"
+require_relative "logger"
+require_relative "buffering/log_buffer"
+require_relative "buffering/log_dispatcher"
+require_relative "http/ingest_api_client"
+require_relative "rack/request_logging"
+
+module Pinqloq
+  class Client
+    attr_reader :logger, :options
+
+    def initialize(options)
+      @options = options
+      @buffer = Buffering::LogBuffer.new(options.queue_capacity)
+      api_client = Http::IngestApiClient.new(options)
+      @dispatcher = Buffering::LogDispatcher.new(@buffer, api_client, options)
+      @logger = Logger.new(@buffer, @dispatcher, options)
+
+      @dispatcher.start
+    end
+
+    def shutdown
+      @dispatcher.shutdown
+    end
+  end
+end

data/lib/pinqloq/http/ingest_api_client.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+require "time"
+require_relative "../options"
+require_relative "../log_failure_reason"
+require_relative "../log_source_type"
+require_relative "../buffering/callback"
+
+module Pinqloq
+  module Http
+    class IngestApiClient
+      SECRET_KEY_HEADER = "X-Secret-Key"
+      HTTP_WARNING_THROTTLE_SECONDS = 60
+      MAX_ERROR_BODY_CHARACTERS = 512
+
+      def initialize(options)
+        @options = options
+        @uri = URI.join("#{INGEST_BASE_ADDRESS}/", options.bulk_path.sub(%r{\A/+}, ""))
+        @next_http_warning_at = Time.at(0)
+        @warning_mutex = Mutex.new
+      end
+
+      def send_batch(items)
+        return if items.empty?
+
+        items.group_by { |item| resolve_collection_name(item.entry) }.each do |collection_name, group_items|
+          send_group(collection_name, group_items)
+        end
+      end
+
+      private
+
+      def send_group(collection_name, group_items)
+        payload = {
+          collectionName: collection_name,
+          logs: group_items.map { |item| to_wire_item(item.entry) }
+        }
+
+        request = Net::HTTP::Post.new(@uri)
+        request[SECRET_KEY_HEADER] = @options.secret_key
+        request["Content-Type"] = "application/json"
+        request.body = JSON.generate(payload)
+
+        response = Net::HTTP.start(@uri.host, @uri.port, use_ssl: @uri.scheme == "https", read_timeout: @options.http_timeout, open_timeout: @options.http_timeout) do |http|
+          http.request(request)
+        end
+
+        if response.is_a?(Net::HTTPSuccess)
+          group_items.each { |item| Buffering::Callback.raise_sent(item.on_sent, item.entry) }
+          return
+        end
+
+        error = build_http_error(response, collection_name)
+        group_items.each { |item| Buffering::Callback.raise_failed(item.on_failed, item.entry, error) }
+      rescue StandardError => e
+        error = build_exception_error(e)
+        warn "Pinqloq: group of #{group_items.length} logs could not be sent (#{format_collection_name(collection_name)}). #{e.class}: #{e.message}"
+        group_items.each { |item| Buffering::Callback.raise_failed(item.on_failed, item.entry, error) }
+      end
+
+      def build_http_error(response, collection_name)
+        status = response.code.to_i
+        reason =
+          case status
+          when 401 then LogFailureReason::UNAUTHORIZED
+          when 403 then LogFailureReason::FORBIDDEN
+          else LogFailureReason::HTTP_ERROR
+          end
+
+        message =
+          case reason
+          when LogFailureReason::UNAUTHORIZED
+            "Unauthorized (HTTP 401): the secret key is invalid or missing."
+          when LogFailureReason::FORBIDDEN
+            "Forbidden (HTTP 403): the secret key is not authorized for the '#{format_collection_name(collection_name)}' collection."
+          else
+            if status == 400
+              "The server rejected the request (HTTP 400, '#{format_collection_name(collection_name)}'): " \
+                "check the collection_name (required for keys allowed on multiple collections) or event fields."
+            else
+              "The server returned an error (HTTP #{status})."
+            end
+          end
+
+        error_body = read_error_body(response)
+        message += " Server response: #{error_body}" unless error_body.empty?
+
+        if should_log_http_failure?
+          warn "Pinqloq: batch send rejected (HTTP #{status}, collection '#{format_collection_name(collection_name)}'); logs in this group were dropped. #{message}"
+        end
+
+        LogError.new(reason: reason, status_code: status, message: message)
+      end
+
+      def build_exception_error(exception)
+        timeout = exception.is_a?(Net::OpenTimeout) || exception.is_a?(Net::ReadTimeout) || exception.is_a?(Timeout::Error)
+
+        if timeout
+          LogError.new(reason: LogFailureReason::TIMEOUT, message: "The request timed out.", cause: exception)
+        else
+          LogError.new(reason: LogFailureReason::NETWORK, message: "Network error: #{exception.message}", cause: exception)
+        end
+      end
+
+      def read_error_body(response)
+        body = (response.body || "").strip
+        body.length <= MAX_ERROR_BODY_CHARACTERS ? body : body[0, MAX_ERROR_BODY_CHARACTERS]
+      rescue StandardError => e
+        warn "Pinqloq: could not read the error response body; continuing without it. #{e.class}: #{e.message}"
+        ""
+      end
+
+      def resolve_collection_name(entry)
+        name = entry.collection_name&.strip
+        (name && !name.empty?) ? name : @options.api_logs_collection_name
+      end
+
+      def should_log_http_failure?
+        @warning_mutex.synchronize do
+          now = Time.now
+          return false if now < @next_http_warning_at
+
+          @next_http_warning_at = now + HTTP_WARNING_THROTTLE_SECONDS
+          true
+        end
+      end
+
+      def format_collection_name(collection_name)
+        (collection_name && !collection_name.strip.empty?) ? collection_name : "(not resolved server-side)"
+      end
+
+      def to_wire_item(entry)
+        app_version_name = entry.app_version_name&.strip
+        app_version_name = (app_version_name && !app_version_name.empty?) ? entry.app_version_name : @options.app_version_name
+
+        device_identifier = entry.device_identifier&.strip
+        device_identifier = (device_identifier && !device_identifier.empty?) ? entry.device_identifier : (@options.device_identifier || "")
+
+        {
+          logLevel: entry.log_level,
+          event: entry.event,
+          date: entry.date&.iso8601(3),
+          appVersionName: app_version_name,
+          deviceIdentifier: device_identifier,
+          logSourceType: LogSourceType::NAMES.fetch(entry.log_source_type, "Backend"),
+          correlationId: entry.correlation_id,
+          path: entry.path,
+          metadata: entry.metadata,
+          detail: entry.detail
+        }
+      end
+    end
+  end
+end

data/lib/pinqloq/internal/throttled_warn.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Pinqloq
+  module Internal
+    module ThrottledWarn
+      @next_allowed_at = {}
+      @mutex = Mutex.new
+
+      class << self
+        def warn_throttled(key, interval_seconds, message)
+          should_warn = @mutex.synchronize do
+            now = Time.now
+            next false if now < @next_allowed_at.fetch(key, Time.at(0))
+
+            @next_allowed_at[key] = now + interval_seconds
+            true
+          end
+
+          warn message if should_warn
+        end
+      end
+    end
+  end
+end