1. Home
2. Reference documentation
3. VCL Reference
4. Declarations

Ratecounter

A ratecounter stores entries that count increments against keys and uses these to estimate the rate at which each key is being incremented. Increments are collected into keyed buckets that represent overlapping and progressively longer periods of time. The ratecounter.{NAME}.bucket.60s reflects all increments in a 60s window that includes the current time, while ratecounter.{NAME}.bucket.10s only counts those that have occurred in the 10 second window that includes the current time. When an entry has received zero increments for the just-completed minute, and therefore all its buckets have a value of zero, they are deleted from the ratecounter.

Time windows are fixed and always incomplete. For example, if the current time is 12:01:03, then ratecounter.{NAME}.bucket.10s represents increments received between 12:01:00 and 12:01:03 (because we are 3 seconds into the 10 second window), not between 12:00:53 and 12:01:03. In each minute at the ten second mark (e.g., :00, :10, :20) the window represented by each bucket will shift to the next interval.

Rate counters are a primitive that is used primarily in constructing rate limiting solutions.

Each ratecounter can contain up to 200,000 entries per site and, once that limit is reached, each new entry will evict the least recently incremented entry.

All the cache nodes within the site communicate with each other, sharing information about the counts in order to converge on a single value. Because of synchronization delays, the first time a ratecounter is used on a given cache node it will appear to have zero counts because it is not yet synchronized with the rest of the cache nodes in the site. Once synchronization is complete, the ratecounter will converge to an accurate value across the site.

Rate counters do not have any properties and should be declared as an empty block:

ratecounter requests_rate {
  # no properties
}

Operations

The following functions operate on ratecounter instances:

• ratelimit.check_rate
• ratelimit.check_rates
• ratelimit.ratecounter_increment

The following variables provide current counts for ratecounter instances:

• ratecounter.{NAME}.bucket.10s
• ratecounter.{NAME}.bucket.20s
• ratecounter.{NAME}.bucket.30s
• ratecounter.{NAME}.bucket.40s
• ratecounter.{NAME}.bucket.50s
• ratecounter.{NAME}.bucket.60s