Add opt-in stream error log throttling

[He-Pin]

Motivation

When a stream stage fails rapidly and repeatedly (e.g., persistent network failure, bad data in a loop), each failure generates a log message. In high-throughput systems, this can result in thousands of log messages per second, overwhelming log aggregation systems and masking other important messages.

Modification

Added a new configuration option:

pekko.stream.materializer.stage-errors-log-throttle-period = off

When set to a positive duration (e.g. 10s), only the first stage error within each time window is logged at ERROR level. Subsequent errors in the window are counted silently, and a summary warning is emitted when the next window opens or the interpreter finishes.

Implementation details

Aspect	Detail
Scope	Per-interpreter throttle state (not shared across streams)
First error	Uses errorLogInitialized flag to guarantee first error always logs, regardless of System.nanoTime() origin
Config validation	Rejects negative durations with require()
Cleanup	Flushes suppressed count in finish() for best-effort reporting
Default	off — zero behavior change for existing users

Files changed

• stream/src/main/resources/reference.conf — New config key
• stream/.../GraphInterpreter.scala — Throttle state fields + modified reportStageError + finish() flush
• stream-tests/.../StageErrorLogThrottleSpec.scala — 4 tests (enabled throttle with Broadcast fan-out, single error, disabled with fan-out, disabled single error)

Result

• Operators can opt-in to throttle stage error logs in noisy environments
• Zero behavior change by default (off)
• Tests use Broadcast with 5 parallel failing stages to exercise the actual throttle code path (multiple reportStageError calls per interpreter)
• All new tests pass, all existing ActorGraphInterpreterSpec and InterpreterSpec tests pass (no regression)

References

• Complements PR Add fine-grained stream error logging control #2805 (fine-grained stream error log level control)