wehub-resource-sync
302 lines
6.8 KiB
ReStructuredText
302 lines
6.8 KiB
ReStructuredText
lmcache quota
|
|
=============
|
|
|
|
The ``lmcache quota`` command manages per-salt cache quotas on a running
|
|
LMCache server. Quotas are soft limits: exceeding a quota triggers eviction
|
|
on the next cycle (~1 s) rather than rejecting writes.
|
|
|
|
.. code-block:: bash
|
|
|
|
lmcache quota <sub-command> [options]
|
|
|
|
.. code-block:: text
|
|
|
|
$ lmcache quota -h
|
|
usage: lmcache quota [-h] {set,get,list,delete} ...
|
|
|
|
Manage per-salt cache quotas on the LMCache server.
|
|
|
|
subcommands:
|
|
set Create or update a quota for a cache_salt
|
|
get Show the quota and current usage for a cache_salt
|
|
list List all registered quotas and their usage
|
|
delete Remove a quota for a cache_salt
|
|
|
|
options:
|
|
-h, --help show this help message and exit
|
|
|
|
set
|
|
---
|
|
|
|
Create or update a quota for a given ``cache_salt``.
|
|
|
|
.. code-block:: bash
|
|
|
|
lmcache quota set <salt> --limit-gb <GB> [--url <URL>]
|
|
|
|
**Example:**
|
|
|
|
.. code-block:: bash
|
|
|
|
$ lmcache quota set tenant1 --limit-gb 10.5
|
|
|
|
================ Quota Set =================
|
|
Cache salt: tenant1
|
|
Limit (GB): 10.5
|
|
Status: ok
|
|
=============================================
|
|
|
|
**Options:**
|
|
|
|
.. list-table::
|
|
:header-rows: 1
|
|
:widths: 25 10 65
|
|
|
|
* - Flag
|
|
- Required
|
|
- Description
|
|
* - ``<salt>``
|
|
- Yes
|
|
- The ``cache_salt`` identifier. Use ``_default`` for anonymous
|
|
(un-salted) traffic.
|
|
* - ``--limit-gb``
|
|
- Yes
|
|
- Quota limit in gigabytes (non-negative float).
|
|
* - ``--url``
|
|
- No
|
|
- LMCache HTTP server URL (default: ``http://localhost:8080``).
|
|
* - ``--format``
|
|
- No
|
|
- Output format: ``terminal`` (default) or ``json``.
|
|
* - ``--output``
|
|
- No
|
|
- Save output to a file (uses the format chosen by ``--format``).
|
|
* - ``-q`` / ``--quiet``
|
|
- No
|
|
- Suppress stdout output. Exit code only.
|
|
|
|
get
|
|
---
|
|
|
|
Show the current quota limit and live usage for a specific ``cache_salt``.
|
|
|
|
.. code-block:: bash
|
|
|
|
lmcache quota get <salt> [--url <URL>]
|
|
|
|
**Example:**
|
|
|
|
.. code-block:: bash
|
|
|
|
$ lmcache quota get tenant1
|
|
|
|
================ Quota Info ================
|
|
Cache salt: tenant1
|
|
Limit (GB): 10.5
|
|
Current usage (GB): 3.27
|
|
Exists: True
|
|
=============================================
|
|
|
|
**Options:**
|
|
|
|
.. list-table::
|
|
:header-rows: 1
|
|
:widths: 25 10 65
|
|
|
|
* - Flag
|
|
- Required
|
|
- Description
|
|
* - ``<salt>``
|
|
- Yes
|
|
- The ``cache_salt`` identifier.
|
|
* - ``--url``
|
|
- No
|
|
- LMCache HTTP server URL (default: ``http://localhost:8080``).
|
|
* - ``--format``
|
|
- No
|
|
- Output format: ``terminal`` (default) or ``json``.
|
|
* - ``--output``
|
|
- No
|
|
- Save output to a file.
|
|
* - ``-q`` / ``--quiet``
|
|
- No
|
|
- Suppress stdout output.
|
|
|
|
list
|
|
----
|
|
|
|
List all registered quotas along with their current usage.
|
|
|
|
.. code-block:: bash
|
|
|
|
lmcache quota list [--url <URL>]
|
|
|
|
**Example:**
|
|
|
|
.. code-block:: bash
|
|
|
|
$ lmcache quota list
|
|
|
|
=================== Quota List ====================
|
|
--- Salt: tenant1 ---
|
|
Cache salt: tenant1
|
|
Limit (GB): 10.5
|
|
Current usage (GB): 3.27
|
|
--- Salt: _default ---
|
|
Cache salt: _default
|
|
Limit (GB): 5.0
|
|
Current usage (GB): 1.82
|
|
===================================================
|
|
|
|
**JSON output:**
|
|
|
|
.. code-block:: bash
|
|
|
|
$ lmcache quota list --format json
|
|
{
|
|
"title": "Quota List",
|
|
"sections": {
|
|
"quota_0": {
|
|
"label": "Salt: tenant1",
|
|
"metrics": {
|
|
"cache_salt": "tenant1",
|
|
"limit_gb": 10.5,
|
|
"current_usage_gb": 3.27
|
|
}
|
|
},
|
|
"quota_1": {
|
|
"label": "Salt: _default",
|
|
"metrics": {
|
|
"cache_salt": "_default",
|
|
"limit_gb": 5.0,
|
|
"current_usage_gb": 1.82
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
**Options:**
|
|
|
|
.. list-table::
|
|
:header-rows: 1
|
|
:widths: 25 10 65
|
|
|
|
* - Flag
|
|
- Required
|
|
- Description
|
|
* - ``--url``
|
|
- No
|
|
- LMCache HTTP server URL (default: ``http://localhost:8080``).
|
|
* - ``--format``
|
|
- No
|
|
- Output format: ``terminal`` (default) or ``json``.
|
|
* - ``--output``
|
|
- No
|
|
- Save output to a file.
|
|
* - ``-q`` / ``--quiet``
|
|
- No
|
|
- Suppress stdout output.
|
|
|
|
delete
|
|
------
|
|
|
|
Remove a quota entry for a given ``cache_salt``. Any bytes still cached
|
|
under this salt become over-budget on the next eviction cycle and will be
|
|
evicted (effective limit drops to 0).
|
|
|
|
.. code-block:: bash
|
|
|
|
lmcache quota delete <salt> [--url <URL>]
|
|
|
|
**Example:**
|
|
|
|
.. code-block:: bash
|
|
|
|
$ lmcache quota delete tenant1
|
|
|
|
============== Quota Delete ===============
|
|
Cache salt: tenant1
|
|
Status: removed
|
|
===========================================
|
|
|
|
**Options:**
|
|
|
|
.. list-table::
|
|
:header-rows: 1
|
|
:widths: 25 10 65
|
|
|
|
* - Flag
|
|
- Required
|
|
- Description
|
|
* - ``<salt>``
|
|
- Yes
|
|
- The ``cache_salt`` identifier.
|
|
* - ``--url``
|
|
- No
|
|
- LMCache HTTP server URL (default: ``http://localhost:8080``).
|
|
* - ``--format``
|
|
- No
|
|
- Output format: ``terminal`` (default) or ``json``.
|
|
* - ``--output``
|
|
- No
|
|
- Save output to a file.
|
|
* - ``-q`` / ``--quiet``
|
|
- No
|
|
- Suppress stdout output.
|
|
|
|
Exit Codes
|
|
----------
|
|
|
|
.. list-table::
|
|
:header-rows: 1
|
|
:widths: 15 85
|
|
|
|
* - Code
|
|
- Meaning
|
|
* - ``0``
|
|
- Success.
|
|
* - ``1``
|
|
- Error (connection failure, server error, bad arguments).
|
|
|
|
The ``_default`` Salt
|
|
---------------------
|
|
|
|
The LMCache server uses an empty string (``""``) as the ``cache_salt`` for
|
|
anonymous / un-salted traffic. Since empty strings cannot appear in URL path
|
|
parameters, the HTTP API (and this CLI) uses the sentinel ``_default`` in
|
|
its place.
|
|
|
|
.. code-block:: bash
|
|
|
|
# Set a 5 GB quota for anonymous traffic
|
|
lmcache quota set _default --limit-gb 5.0
|
|
|
|
# Check usage
|
|
lmcache quota get _default
|
|
|
|
Common Patterns
|
|
---------------
|
|
|
|
**Provision quotas for multiple tenants:**
|
|
|
|
.. code-block:: bash
|
|
|
|
for tenant in tenant_a tenant_b tenant_c; do
|
|
lmcache quota set "$tenant" --limit-gb 8.0
|
|
done
|
|
|
|
**Monitor usage in a script:**
|
|
|
|
.. code-block:: bash
|
|
|
|
USAGE=$(lmcache quota get tenant1 --format json | jq '.metrics.current_usage_gb')
|
|
LIMIT=$(lmcache quota get tenant1 --format json | jq '.metrics.limit_gb')
|
|
echo "tenant1: ${USAGE} / ${LIMIT} GB"
|
|
|
|
**Revoke access (evict all cached data for a salt):**
|
|
|
|
.. code-block:: bash
|
|
|
|
# Deleting the quota causes all data under this salt to be evicted
|
|
lmcache quota delete tenant1
|