{
  "slug": "token-bucket",
  "term": "Token bucket",
  "aliases": [
    "Token-bucket meter"
  ],
  "definition": "A token bucket meters work using credits that refill at a configured rate up to a finite capacity.",
  "note": "Model: credits accumulate at rate R up to capacity B, and each admitted operation consumes its charge. A strict ideal bucket admits at most B + R*t charge units over an interval of t seconds. The unit may be bytes or operations; the initial balance and any additional peak limit matter. [rfc3290]\n\nStorage scope: librbd QoS in Ceph Reef uses token buckets for IOPS and byte-rate limits. Limits apply to one image within one process; separate processes accessing the same image have independent limits. A configured ceiling is not a cluster-wide reservation. [ceph-qos]\n\nWhole-request boundary: in the strict model, an indivisible request costing more than B credits can never conform, because waiting refills only up to B. Loose meters that borrow credits require different reasoning. This is a model distinction, not a claim about Ceph's admission implementation. [rfc3290]",
  "limitations": [
    {
      "text": "The admission envelope alone does not bound outstanding concurrency or completion latency.",
      "citationIds": [
        "rfc3290"
      ]
    }
  ],
  "related": [
    "leaky-bucket-meter",
    "iops",
    "queue-depth",
    "cgroup-v2-io-controller"
  ],
  "citations": [
    {
      "id": "rfc3290",
      "title": "RFC 3290, Appendix A: rate and burst models, metering and shaping",
      "url": "https://www.rfc-editor.org/rfc/rfc3290.html#appendix-A",
      "accessed": "2026-11-12"
    },
    {
      "id": "ceph-qos",
      "title": "Ceph Reef: RBD QoS settings and per-image, per-process scope",
      "url": "https://docs.ceph.com/en/reef/rbd/rbd-config-ref/#qos-settings",
      "accessed": "2026-11-12"
    },
    {
      "id": "hesela-bursts",
      "title": "Hesela: rate limits, burst budgets and shared SSD queues",
      "url": "https://hesela.com/analyses/ssd-fairness-shared-queues/#rate-burst-scope",
      "accessed": "2026-11-12"
    }
  ],
  "provenance": [
    "RFC 3290 is an informational networking model; the charge-unit envelope is applied here as ideal accounting, not a storage benchmark.",
    "Ceph behavior is scoped to the Reef documentation; no device performance or current deployment measurement is claimed."
  ],
  "status": "shipping",
  "advantages": [],
  "supersedes": [],
  "supersededBy": [],
  "firstSeen": null,
  "lastSeen": null,
  "updated": "2026-11-12"
}