FDN-4523: Add time-based throttling to RollbarLogger via atMostEvery

[gheine]

Summary

• Add atMostEvery(d: FiniteDuration) to RollbarLogger for time-based log throttling (e.g. logger.atMostEvery(1.minute).warn("msg"))
• Uses a shared AtomicLong timestamp with CAS for thread-safe throttling that survives .copy() / builder chains
• Add Guice binding for the new field so DI continues to work
• Add RollbarLoggerSpec with tests for throttle behavior, state sharing across copies, and combination with withFrequency
• Add CLAUDE.md for Claude Code guidance

Test plan

• All 17 tests pass (sbt test)
• New RollbarLoggerSpec covers: default no-throttle, first call allowed, suppression within interval, allow after interval, shared state across builder calls, combination with withFrequency
• Existing RollbarModuleSpec Guice injection test passes with new field
• Code formatted with sbt scalafmtAll

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added time-based throttling via atMostEvery(duration) so specific log messages can be limited by interval; works alongside existing frequency controls.

• Tests

  • Added tests covering interval throttling, first-call/ suppression behavior, shared throttle state, and interaction with frequency settings.

• Documentation

  • Added comprehensive library guidance and usage documentation.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds interval-based throttling to RollbarLogger, a new atMostEvery builder, a new Guice binding for Option[(FiniteDuration, AtomicLong)], updated shouldLog logic to combine frequency and time-based throttling, tests validating the new behavior, and a new CLAUDE.md guidance document.

Changes

Cohort / File(s)	Summary
Documentation CLAUDE.md	Adds a new guidance document for the lib-log Play 2.9 Scala logging library covering purpose, build, coverage, style, architecture, components, testing, CI/CD, and publishing.
Dependency Injection src/main/scala/io/flow/log/Rollbar.scala	Adds imports AtomicLong and FiniteDuration and a new Guice binding for Option[(FiniteDuration, AtomicLong)] (bound to None), exposing an optional shared interval state for injection; no runtime logic changes to Rollbar initialization.
Core Logger src/main/scala/io/flow/log/RollbarLogger.scala	Introduces interval-based throttling: new constructor parameter interval: Option[(FiniteDuration, AtomicLong)] = None, new public builder atMostEvery(d: FiniteDuration): RollbarLogger, and updated private[log] def shouldLog combining frequency sampling with optional atomic time-based throttle. Added relevant imports.
Tests src/test/scala/io/flow/log/RollbarLoggerSpec.scala	Adds ScalaTest spec covering atMostEvery behavior: default interval state, first-call allowance, suppression within interval, resumption after interval, shared throttle state across builder chains, and interplay with withFrequency.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically summarizes the main change: adding time-based throttling to RollbarLogger via a new atMostEvery method, which aligns with the core functionality introduced across modified files.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[flow-tech]

Click here for code coverage report: https://jenkins.flo.pub/job/flowcommerce/job/lib-log/job/PR-379/1/scoverage-report/

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@src/main/scala/io/flow/log/RollbarLogger.scala`:
- Around line 179-189: The current shouldLog lets timeThrottleCheck run even
when frequencyCheck is false, causing lastLoggedAt to advance on skipped
samples; change shouldLog so frequencyCheck is evaluated first and the interval
check (the match on interval/lastLoggedAt and the compareAndSet call) only runs
when frequencyCheck is true, e.g. compute frequencyCheck then if false return
false else execute the interval/time throttle logic (using lastLoggedAt only
when emitting) so lastLoggedAt is updated only for actually emitted logs in
shouldLog.

[flow-tech]

Click here for code coverage report: https://jenkins.flo.pub/job/flowcommerce/job/lib-log/job/PR-379/2/scoverage-report/

[coderabbitai]

♻️ Duplicate comments (1)

src/main/scala/io/flow/log/RollbarLogger.scala (1)

179-189: The fix correctly addresses the previous review concern.

The pattern-match on (interval, frequencyCheck) ensures the CAS operation only executes when frequencyCheck is true, preventing skipped frequency samples from advancing lastLoggedAt. The implementation now properly gates the time check behind the frequency check.
,

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/main/scala/io/flow/log/RollbarLogger.scala` around lines 179 - 189, The
shouldLog method previously allowed the interval CAS
(lastLoggedAt.compareAndSet) to run even when frequency sampling was skipped;
update shouldLog (function shouldLog) so that frequencyCheck is evaluated first
and the time throttle CAS only runs when frequencyCheck is true—accomplish this
as shown by computing frequencyCheck, then pattern-matching (interval,
frequencyCheck) to run the CAS inside the case that matches (Some((minInterval,
lastLoggedAt)), true), using now/last and compareAndSet on lastLoggedAt to
update the timestamp; keep the final return as frequencyCheck &&
timeThrottleCheck.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Duplicate comments:
In `@src/main/scala/io/flow/log/RollbarLogger.scala`:
- Around line 179-189: The shouldLog method previously allowed the interval CAS
(lastLoggedAt.compareAndSet) to run even when frequency sampling was skipped;
update shouldLog (function shouldLog) so that frequencyCheck is evaluated first
and the time throttle CAS only runs when frequencyCheck is true—accomplish this
as shown by computing frequencyCheck, then pattern-matching (interval,
frequencyCheck) to run the CAS inside the case that matches (Some((minInterval,
lastLoggedAt)), true), using now/last and compareAndSet on lastLoggedAt to
update the timestamp; keep the final return as frequencyCheck &&
timeThrottleCheck.

ℹ️ Review info

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 3676e99 and 78f65fc.

📒 Files selected for processing (1)

• src/main/scala/io/flow/log/RollbarLogger.scala