wehub/lmcache--lmcache
1
0
Fork 0
Code Issues Pull Requests Actions Deployments Models Agent Notes Packages Projects Releases Wiki Activity

chore: import upstream snapshot with attribution

Browse Source
This commit is contained in:
wehub-resource-sync
2026-07-13 12:24:33 +08:00
commit f213ec8976
2101 changed files with 494002 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/source/internal_api_server/controller_apis.rst
+201
View File
@@ -0,0 +1,201 @@
.. _controller_apis:
Controller APIs
===============
.. warning::
This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance. For the MP mode equivalent of this page, see :doc:`/mp/http_api`.
These APIs are specific to the LMCache Controller component. They provide
visibility into registered instances, workers, and key statistics.
.. contents:: Endpoints
:local:
:depth: 2
``GET /controller/key-stats`` — Key Statistics
------------------------------------------------
Get key statistics across all instances and workers.
- **Method**: ``GET``
- **Path**: ``/controller/key-stats``
- **Parameters**: None
- **Response**: ``application/json``
.. code-block:: bash
curl http://localhost:6999/controller/key-stats
**Example Response** (HTTP 200):
.. code-block:: json
{
"total_key_count": 1500,
"total_instance_count": 2,
"total_worker_count": 4,
"instances": [
{
"instance_id": "instance_001",
"key_count": 800,
"worker_count": 2
},
{
"instance_id": "instance_002",
"key_count": 700,
"worker_count": 2
}
]
}
**Error Response** (controller not available, HTTP 503):
.. code-block:: json
{
"detail": "Controller manager not available"
}
**Response Schema**:
========================= ======= =============================================
Field Type Description
========================= ======= =============================================
``total_key_count`` int Total number of KV keys across all instances
``total_instance_count`` int Total number of registered instances
``total_worker_count`` int Total number of workers across all instances
``instances`` list Per-instance breakdown (see below)
========================= ======= =============================================
**Instance Schema**:
================= ======= =============================================
Field Type Description
================= ======= =============================================
``instance_id`` str Unique identifier of the instance
``key_count`` int Number of KV keys held by this instance
``worker_count`` int Number of workers in this instance
================= ======= =============================================
``GET /controller/workers`` — Worker Information
--------------------------------------------------
Get worker information with flexible query parameters. Behavior depends
on the combination of parameters:
- **No parameters**: List all registered workers across all instances.
- **``instance_id`` only**: List all workers for a specific instance.
- **``instance_id`` and ``worker_id``**: Get detailed info about a specific worker.
- **Method**: ``GET``
- **Path**: ``/controller/workers``
- **Parameters**:
================ ======= =============================================
Name Type Description
================ ======= =============================================
``instance_id`` str (Optional) Instance ID to filter workers
``worker_id`` int (Optional) Worker ID for specific worker details (requires ``instance_id``)
================ ======= =============================================
- **Response**: ``application/json``
.. code-block:: bash
# List all workers
curl http://localhost:6999/controller/workers
# List workers for a specific instance
curl "http://localhost:6999/controller/workers?instance_id=instance_001"
# Get a specific worker
curl "http://localhost:6999/controller/workers?instance_id=instance_001&worker_id=0"
**Example Response** (list workers):
.. code-block:: json
{
"workers": [
{
"instance_id": "instance_001",
"worker_id": 0,
"ip": "10.0.0.1",
"port": 8000,
"peer_init_url": "http://10.0.0.1:8000/init",
"registration_time": 1706745600.0,
"last_heartbeat_time": 1706745660.0,
"key_count": 400
},
{
"instance_id": "instance_001",
"worker_id": 1,
"ip": "10.0.0.2",
"port": 8001,
"peer_init_url": "http://10.0.0.2:8001/init",
"registration_time": 1706745600.0,
"last_heartbeat_time": 1706745660.0,
"key_count": 400
}
],
"total_count": 2
}
**Example Response** (single worker):
.. code-block:: json
{
"instance_id": "instance_001",
"worker_id": 0,
"ip": "10.0.0.1",
"port": 8000,
"peer_init_url": "http://10.0.0.1:8000/init",
"registration_time": 1706745600.0,
"last_heartbeat_time": 1706745660.0,
"key_count": 400
}
**Error Response** (worker not found, HTTP 404):
.. code-block:: json
{
"detail": "Worker (instance_001, 99) not found"
}
**Error Response** (instance not found, HTTP 404):
.. code-block:: json
{
"detail": "No workers found for instance unknown_instance"
}
**Error Response** (controller not available, HTTP 503):
.. code-block:: json
{
"detail": "Controller manager not available"
}
**Worker Response Schema**:
========================== ======= =============================================
Field Type Description
========================== ======= =============================================
``instance_id`` str Instance this worker belongs to
``worker_id`` int Worker index within the instance
``ip`` str Worker IP address
``port`` int Worker port number
``peer_init_url`` str (Optional) Peer initialization URL
``registration_time`` float Unix timestamp of worker registration
``last_heartbeat_time`` float Unix timestamp of last heartbeat
``key_count`` int Number of KV keys held by this worker
========================== ======= =============================================