cogworker 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1eb0a27dc233c6009a4a78103adb88ddc76aa813dd53e1f5905e419f028f4d11
-  data.tar.gz: 511c286faf085250e00bf5fb7ce4f45bfaac44731a60d1a1c92779095e758147
+  metadata.gz: ef260933f908739609343cb6b72e5fbbe75a01d0c93dd8fba5d1c4983e807f26
+  data.tar.gz: 22b576f3c302378c1ca2e8075893c3c4b9404329f6dacc22c281ad4b7c31f688
 SHA512:
-  metadata.gz: 1663b0475259d7bd30b5dd5718dbccc38bd53e1b4494a6574d4159229943f9a789754549171bee406134def631524733f4bb9e01e901ff552f3ad778f15f5599
-  data.tar.gz: 8a32c328155045a7c19049bba52478dbd2b806b6cf875af3d83cf7a05dfc63d1eda59ae36d66dcd19a4d5494ca8613b13a62620bddbf13fd57d08f6d297927d3
+  metadata.gz: a48c5530445af6a80846ef5313202f88a3638ecdb33614e7f86baba87c33c4e214add29febf257e025cdf1921ad76bc35140cd91828101aa556a4fb0a461e662
+  data.tar.gz: f6b2cdaef9cf94adb3823d29cffca99d50697a7553dc6178357fb6cf435ba8fb82320be291e1b04bd5075ab05ad2cf86cb5b2ed67a4f6420e20283360ec399f0

data/lib/cogworker/history/storage.rb

@@ -6,8 +6,14 @@ module Cogworker
   module History
     # Three parallel ZSETs (score = finished_at), so any of the three
     # filters (all/success/failed) is a plain `ZREVRANGE` — no per-request
-    # `ZUNIONSTORE`/scan needed. Each is trimmed to `History.max_entries`
-    # independently on every write, oldest first.
+    # `ZUNIONSTORE`/scan needed. Each is trimmed independently on every
+    # write, oldest first, by age (`History.retention_days`, the primary,
+    # expected limit) and then by count (`History.max_entries`, a safety
+    # ceiling only — see both constants' own comments in `history.rb`) —
+    # see `write_and_trim`. Alongside those, `record` also maintains one
+    # small per-UTC-day Hash counter (`daily_counts` reads these back) —
+    # kept deliberately separate from, and unaffected by, either trim above
+    # (see `daily_counts`' own comment).
     module Storage
       LIST_KEYS = {
         'all' => 'cogworker:history:all',
@@ -29,13 +35,21 @@ module Cogworker
         end
 
         raw = JSON.generate(entry)
-        max = Cogworker::History.max_entries
         Cogworker.config.redis do |c|
-          write_and_trim(c, LIST_KEYS.fetch('all'), raw, finished_at, max)
-          write_and_trim(c, LIST_KEYS.fetch(status), raw, finished_at, max)
+          write_and_trim(c, LIST_KEYS.fetch('all'), raw, finished_at)
+          write_and_trim(c, LIST_KEYS.fetch(status), raw, finished_at)
+          # Independent of the two trims above — see `daily_counts`' own
+          # comment for why "Runs per day" can't just read the `all` list.
+          bump_daily_count(c, finished_at, status)
         end
       end
 
+      def bump_daily_count(conn, finished_at, status)
+        daily_key = RedisKeys.history_daily_bucket(Time.at(finished_at).utc.strftime('%Y-%m-%d'))
+        conn.hincrby(daily_key, status, 1)
+        conn.expire(daily_key, Cogworker::History.daily_stats_retention_days * 86_400)
+      end
+
       # Newest-first page of `count`/`status` entries: `[entries, total]`.
       def page(status, page_number, per_page)
         key = LIST_KEYS.fetch(status, LIST_KEYS.fetch('all'))
@@ -49,33 +63,55 @@ module Cogworker
         end
       end
 
-      def write_and_trim(conn, key, raw, score, max)
+      def write_and_trim(conn, key, raw, score)
         conn.zadd(key, score, raw)
-        conn.zremrangebyrank(key, 0, -(max + 1))
+        # Age first — the primary, expected trim in normal operation: gone
+        # once older than `History.retention_days`, regardless of how few
+        # entries that leaves. Count second, as a safety ceiling only — see
+        # `History::DEFAULT_MAX_ENTRIES`'s own comment for why both run on
+        # every write rather than just one. Both read fresh from
+        # `Cogworker::History` here (rather than being passed in) so a
+        # config change takes effect on the very next write, same as
+        # `max_entries` always has.
+        cutoff = Time.now.to_f - (Cogworker::History.retention_days * 86_400)
+        conn.zremrangebyscore(key, '-inf', cutoff)
+        conn.zremrangebyrank(key, 0, -(Cogworker::History.max_entries + 1))
       end
 
       # Success/failed counts per UTC calendar day, for the last `days` days
       # (today included) — `{ 'YYYY-MM-DD' => { 'success' => n, 'failed' => n } }`,
-      # a day with no entries simply absent from the Hash. Reads the shared
-      # "all" list once (rather than "success" and "failed" separately) since
-      # every entry already carries its own `status`. Bucketing uses UTC,
-      # not the viewer's browser timezone (unlike `Layout.time_tag`
+      # a day with no entries simply absent from the Hash. Bucketing uses
+      # UTC, not the viewer's browser timezone (unlike `Layout.time_tag`
       # elsewhere) — this is a server-rendered daily aggregate, not a single
       # instant, so there's no one "browser day" to convert into.
-      # Same caveat as any other read of this list: only entries still
-      # within `History.max_entries` are counted, so a very busy queue's
-      # oldest requested days may already have been trimmed away.
+      #
+      # Reads `RedisKeys.history_daily_bucket(day)` (one small Hash per day,
+      # `record` above keeps them updated) rather than scanning the `all`
+      # list and bucketing entries by hand — deliberately: even now that the
+      # `all`/`success`/`failed` lists are trimmed by age (`History.
+      # retention_days`) rather than purely by count, that's still a
+      # *different*, independently configured window than the daily
+      # buckets' own (`History.daily_stats_retention_days`, TTL-based, same
+      # idea as `Cogworker::Throughput`'s hourly buckets) — a "6 months"
+      # chart request would find nothing if it depended on `all` still
+      # holding 6 months of entries, since `retention_days` defaults to
+      # far less than that. The daily buckets are sized (and meant) to
+      # outlive the raw per-entry lists, so "Runs per day" stays accurate
+      # regardless of how short `retention_days` is configured.
       def daily_counts(days)
-        since = Time.now.to_f - (days * 86_400)
-        Cogworker.config.redis do |c|
-          c.zrangebyscore(LIST_KEYS.fetch('all'), since, '+inf').each_with_object({}) do |raw, counts|
-            entry = JSON.parse(raw)
-            day = Time.at(entry['finished_at']).utc.strftime('%Y-%m-%d')
-            bucket = (counts[day] ||= { 'success' => 0, 'failed' => 0 })
-            bucket[entry['status']] += 1 if bucket.key?(entry['status'])
-          end
+        now = Time.now.utc
+        day_strings = (days - 1).downto(0).map { |offset| (now - (offset * 86_400)).strftime('%Y-%m-%d') }
+        raw = Cogworker.config.redis { |c| c.pipelined { |pipe| day_strings.each { |d| daily_hmget(pipe, d) } } }
+        day_strings.zip(raw).each_with_object({}) do |(day, (success, failed)), counts|
+          next if success.nil? && failed.nil?
+
+          counts[day] = { 'success' => success.to_i, 'failed' => failed.to_i }
         end
       end
+
+      def daily_hmget(pipe, day)
+        pipe.hmget(RedisKeys.history_daily_bucket(day), 'success', 'failed')
+      end
     end
   end
 end

data/lib/cogworker/history.rb

@@ -4,29 +4,79 @@ module Cogworker
   # Execution history: every job run (success and failure alike) is recorded
   # with its full args, timing, and — on failure — error class/message/
   # backtrace. Distinct from the Status layer (`Cogworker::Status`), which
-  # tracks *current* per-jid state with a TTL; History is an append-only,
-  # length-capped log meant for browsing/auditing past runs.
+  # tracks *current* per-jid state with a TTL; History is an append-only log
+  # meant for browsing/auditing past runs, trimmed by age first.
   module History
-    DEFAULT_MAX_ENTRIES = 1000
+    # The primary, expected trim for the "all"/"success"/"failed" lists —
+    # anything older than this many days is gone on the next write,
+    # regardless of how few (or many) entries that leaves. See `Storage.
+    # write_and_trim`.
+    DEFAULT_RETENTION_DAYS = 30
+    # A safety ceiling, not the everyday trim mechanism — `retention_days`
+    # above is. Each entry in the lists it bounds carries its full args and,
+    # on failure, up to 200 backtrace lines, so a burst of traffic under a
+    # purely time-based trim could otherwise grow Redis memory unboundedly
+    # until those entries finally age out; this caps that. Sized well above
+    # what `retention_days`' default window is expected to hold in normal
+    # operation specifically so it stays a rare safety net rather than the
+    # thing actually doing the trimming day to day — if it's the one
+    # regularly cutting entries short of `retention_days`, raise it (or
+    # lower `retention_days`) to match this queue's real volume.
+    DEFAULT_MAX_ENTRIES = 50_000
+    # "Runs per day" (`Storage.daily_counts`) reads a separate, per-UTC-day
+    # counter (`RedisKeys.history_daily_bucket`) rather than the capped
+    # `all`/`success`/`failed` lists above, specifically so those lists'
+    # own trim (age- or count-based) doesn't also blow away the daily
+    # chart's older days — see `Storage`'s own comment. Each day's counter
+    # self-expires via `EXPIRE`, the same TTL-based cleanup `Cogworker::
+    # Throughput` already uses for its hourly buckets, rather than a
+    # count-based trim: 400 days comfortably covers the widest period the
+    # built-in chart offers (6 months / 182 days) with real margin, so a
+    # viewer opening that period on day 1 of a new retention window still
+    # sees its oldest days.
+    DEFAULT_DAILY_STATS_RETENTION_DAYS = 400
 
     class << self
-      # How many entries are retained (oldest trimmed first), independently
-      # for the "all", "success", and "failed" lists — read fresh on every
+      # How many days an entry survives in the "all"/"success"/"failed"
+      # lists before `write_and_trim` removes it — read fresh on every
       # write, so changing it takes effect immediately, no need to rebuild
       # the middleware chain. Configurable via
+      # `configure_server_middleware(config, retention_days: N)`, or
+      # directly: `Cogworker::History.retention_days = 90`.
+      attr_writer :retention_days
+      # The count-based safety ceiling alongside `retention_days` above —
+      # see `DEFAULT_MAX_ENTRIES`. Configurable via
       # `configure_server_middleware(config, max_entries: N)`, or directly:
-      # `Cogworker::History.max_entries = 5000`.
+      # `Cogworker::History.max_entries = 50_000`.
       attr_writer :max_entries
+      # How many days a "Runs per day" daily counter survives before
+      # self-expiring — independent of `retention_days`/`max_entries` above
+      # (see `DEFAULT_DAILY_STATS_RETENTION_DAYS`). Configurable via
+      # `configure_server_middleware(config, daily_stats_retention_days: N)`,
+      # or directly: `Cogworker::History.daily_stats_retention_days = 800`.
+      attr_writer :daily_stats_retention_days
+
+      def retention_days
+        @retention_days ||= DEFAULT_RETENTION_DAYS
+      end
 
       def max_entries
         @max_entries ||= DEFAULT_MAX_ENTRIES
       end
+
+      def daily_stats_retention_days
+        @daily_stats_retention_days ||= DEFAULT_DAILY_STATS_RETENTION_DAYS
+      end
     end
 
     module_function
 
-    def configure_server_middleware(config, max_entries: DEFAULT_MAX_ENTRIES)
+    def configure_server_middleware(config, retention_days: DEFAULT_RETENTION_DAYS,
+                                    max_entries: DEFAULT_MAX_ENTRIES,
+                                    daily_stats_retention_days: DEFAULT_DAILY_STATS_RETENTION_DAYS)
+      self.retention_days = retention_days
       self.max_entries = max_entries
+      self.daily_stats_retention_days = daily_stats_retention_days
       config.server_middleware { |chain| chain.add(Middleware) }
     end
   end

data/lib/cogworker/redis_keys.rb

@@ -32,5 +32,6 @@ module Cogworker
     def periodic_lock(pjid, slot) = "periodic:lock:#{pjid}:#{slot}"
     def unique_lock(digest) = "cogworker:unique:#{digest}"
     def throughput_bucket(hour) = "cogworker:throughput:#{hour}"
+    def history_daily_bucket(day) = "cogworker:history:daily:#{day}"
   end
 end

data/lib/cogworker/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Cogworker
-  VERSION = '0.2.0'
+  VERSION = '0.2.1'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cogworker
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - vdonec