> ## Documentation Index
> Fetch the complete documentation index at: https://docs.curator.interworks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Log Rate Limiter

> How Curator prevents the Event Log from being flooded by repeated identical messages, and what to expect when rate limiting is active.

Curator automatically prevents the Event Log from being flooded by repeated identical errors or warnings.
When the same message occurs many times in a short period, Curator begins suppressing duplicates and
periodically logs a summary entry instead. This keeps the Event Log readable and performant without
losing visibility into ongoing issues.

## How it works

1. **First 20 occurrences are always logged** — every unique message is allowed through at least 20 times.
   A full page of identical entries in the Event Log is a clear signal that something is actively failing.
2. **Suppression begins after the 20th occurrence** — if the same message keeps appearing, Curator starts
   holding back duplicates.
3. **Periodic summary entries** — rather than silently discarding messages, Curator logs a summary at
   increasing intervals. Each summary entry is prefixed with `[Rate Limited]` and includes a count of
   how many occurrences were suppressed and when they started.
4. **Intervals double over time** — summaries appear at 2 minutes, then 4, 8, 16, 32, and cap at every
   60 minutes for as long as the issue persists.

Rate limiting state resets after 24 hours of inactivity per message type.

## What a rate-limited entry looks like

A normal Event Log entry:

```
[error] Connection to upstream API failed
```

Once rate limiting is active, subsequent entries look like this:

```
[error] [Rate Limited] Connection to upstream API failed
        _rate_limited: "Suppressed 239 identical messages since 2026-03-11 09:00:10"
```

The `[Rate Limited]` prefix is searchable in the Event Log. Use it to quickly find any messages
that have been suppressed.

## Examples

### Runaway error

Without rate limiting, a continuous error at 2 per second would produce 7,200 Event Log entries per hour.
Here is what you would actually see:

| Elapsed            | What appears in the Event Log                                                                                      |
| ------------------ | ------------------------------------------------------------------------------------------------------------------ |
| 0 – 10 s           | Occurrences 1–20 logged normally. A full page of identical entries signals a problem.                              |
| 10 s               | First `[Rate Limited]` entry logged. Suppression window: **2 min**.                                                |
| 10 – 130 s         | \~239 occurrences suppressed.                                                                                      |
| 130 s              | Summary logged: "Suppressed 239 identical messages since 09:00:10". Window: **4 min**.                             |
| 370 s              | Summary logged. Window: **8 min**.                                                                                 |
| 850 s              | Summary logged. Window: **16 min**.                                                                                |
| 1,810 s            | Summary logged. Window: **32 min**.                                                                                |
| 3,730 s            | Summary logged. Window caps at **60 min**.                                                                         |
| Every 60 min after | One summary per window; the count grows each window — it is the cumulative total since the message first appeared. |

**Result:** 7,200 entries/hour reduced to \~26, with each summary carrying the full suppression details.

### Intermittent error

If the same message appears only occasionally — say, 10 times over 10 minutes — it will never hit the
suppression threshold. All 10 occurrences are logged normally and the `[Rate Limited]` prefix will never appear.

| Error frequency | Threshold reached  | Rate limiting active?              |
| --------------- | ------------------ | ---------------------------------- |
| 2 / second      | After \~10 seconds | Yes                                |
| 1 / minute      | After \~20 minutes | Yes, if it continues               |
| 1 / hour        | After \~20 hours   | Yes, just before the 24-hour reset |
| 1 / day         | Never              | No                                 |

## Limitations and caveats

* **The Event Log is not a complete audit trail** — because suppressed occurrences are not stored, the
  Event Log should not be used to count how many times something happened or as an authoritative record
  of security-related events. Use Curator's Usage Log or an external audit system for that purpose.
* **Some messages are never rate-limited** — errors that include dynamic information (such as a user
  name, record ID, or timestamp) in the message text are treated as distinct messages and are each
  logged individually, regardless of frequency. This is expected behavior.