QoS Token Bucket & Shaper Rate Calculator

1. Traffic Policing vs. Traffic Shaping: The Architectural Divide

In carrier transport networks and enterprise WAN boundaries, rate-limiting is essential to enforce contracted Service Level Agreements (SLAs) and prevent upstream access traffic from oversubscribing downstream links. Rate limiting is executed via two fundamentally different mechanisms:

• Traffic Policing (Rate Limiting): A traffic policer measures incoming or outgoing packet arrival rates against configured thresholds (CIR/PIR). Packets that arrive when sufficient tokens reside in the bucket are marked as conforming and forwarded immediately. When a burst exceeds token depth, excess packets are immediately dropped or remarked to a lower QoS priority (e.g., dropping DSCP from EF or AF41 down to Best Effort). Policing introduces zero additional queuing latency or jitter. However, because TCP interprets dropped segments as severe congestion, policing causes aggressive TCP sliding window collapse, frequently cutting effective throughput to a fraction of the contracted CIR.
• Traffic Shaping (Rate Smoothing): Rather than discarding non-conforming packets, a traffic shaper holds excess traffic in an egress queue (typically Class-Based Weighted Fair Queuing, CBWFQ, or a dedicated FIFO buffer). Packets are then clocked out onto the physical wire at a smooth, steady rate equal to the CIR. While shaping preserves TCP window scalability and eliminates packet drops, it introduces queuing latency and packet jitter that can degrade interactive traffic like VoIP and real-time video if buffers are misconfigured.

2. Single-Rate (srTCM RFC 2697) vs. Two-Rate (trTCM RFC 2698) Metering

To classify traffic into differentiated forwarding tiers, the IETF standardized two formal three-color token bucket models:

• Single-Rate Three-Color Marker (srTCM - RFC 2697): Employs a single token generator that replenishes tokens at the Committed Information Rate (CIR). It meters traffic into three colors using two token buckets: the Committed Bucket (C) with size CBS, and the Excess Bucket (E) with size EBS. Tokens fill bucket C first; only when bucket C is full do excess tokens spill over into bucket E. When a packet of size B arrives:
  • If B ≤ C, the packet is Green (conforming), and B tokens are decremented from C.
  • If B > C but B ≤ E, the packet is Yellow (exceeding), and B tokens are decremented from E.
  • If B > E, the packet is Red (violating), and no tokens are decremented.
• Two-Rate Three-Color Marker (trTCM - RFC 2698): Designed for scenarios where a customer is permitted to burst up to an absolute ceiling known as the Peak Information Rate (PIR). Employs two independent token generators running at different rates: PIR replenishes the Peak Bucket (P, size PBS), while CIR replenishes the Committed Bucket (C, size CBS). When packet of size B arrives:
  • If B > P, the packet is Red.
  • If B ≤ P but B > C, the packet is Yellow, and B tokens are deducted from P.
  • If B ≤ C, the packet is Green, and B tokens are deducted from both C and P.

3. The Mathematics of Token Replenishment & Time Interval (T_c)

The operation of a token bucket is governed by the time interval (T_c) over which tokens are added:

Choosing the correct value of T_c requires balancing hardware constraints and traffic dynamics:

• Too Small (T_c < 4 ms): On network silicon with coarse timer ticks (e.g., 10 ms hardware clocks), the bucket cannot refill fast enough. Furthermore, if the calculated CBS is smaller than the path MTU (e.g., 1500 Bytes), a single full-sized Ethernet frame will fail to find enough tokens upon arrival, resulting in catastrophic packet drop rates ("policer starvation").
• Too Large (T_c > 50 ms to 125 ms): While legacy routers traditionally defaulted to T_c = 125 ms (1/8 of a second), this allows senders to dump immense bursts at full physical interface wire-speed. A 1 Gbps port configured with a 125 ms T_c allows an unbroken 125 Mb burst before policing engages, overwhelming downstream switch buffers and inducing severe packet loss and jitter for concurrent flows.
• The Carrier Standard: Modern telecommunications operators and cloud interconnect providers standardize on T_c = 10 ms (0.010 seconds), achieving optimal balance between smooth packet transmission and low-latency absorption.

4. Buffer Sizing in Shapers: Avoiding Bufferbloat vs. Preventing Packet Drops

A traffic shaper requires buffer memory to temporarily hold packets during bursts. The required memory footprint is mathematically expressed as:

However, allocating excessively large queues creates the phenomenon known as bufferbloat. When a shaping queue holds several megabytes of data, TCP senders do not experience packet loss, prompting them to continuously expand their congestion windows until the entire buffer is full. Packets remain queued for hundreds of milliseconds, turning an otherwise fast fiber connection into a high-latency link. For real-time applications, shapers should be paired with Active Queue Management (AQM) algorithms like FQ-CoDel or PIE to drop or ECN-mark packets before latency thresholds are exceeded.