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

Ratecounter

WARNING: The Edge Rate Limiting product must be enabled on your account by a Fastly employee in order to use the primitives described on this page.

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 occured 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 POP and, once that limit is reached, each new entry will evict the least recently incremented entry.

All the cache nodes within the POP 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 POP. Once synchronization is complete, the ratecounter will converge to an accurate value across the POP.

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:

The following variables provide current counts for ratecounter instances: