Skip to content

Commit bd3dbbd

Browse files
wangxiyu191wangxiyu191
committed
[manager/service/client] add cache meta detail API
1 parent b33eea5 commit bd3dbbd

32 files changed

Lines changed: 620 additions & 8 deletions

‎docs/api/meta_service.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -227,3 +227,76 @@ curl -g -vvv -X POST http://localhost:6382/api/getCacheMeta \
227227
"detail_level": 1
228228
}'
229229
```
230+
231+
## Get Cache Meta Detail
232+
```bash
233+
curl -g -vvv -X POST http://localhost:6382/api/getCacheMetaDetail \
234+
-H "Content-Type: application/json" \
235+
-H "Accept: application/json" \
236+
-d '{
237+
"trace_id": "trace_id_131",
238+
"instance_id": "test_instance",
239+
"block_keys": [123, 456],
240+
"block_mask": {
241+
"offset": 0
242+
},
243+
"detail_level": 1
244+
}'
245+
```
246+
247+
Example response:
248+
```json
249+
{
250+
"header": {
251+
"status": {
252+
"code": "OK",
253+
"message": "Cache metadata detail retrieved successfully"
254+
},
255+
"request_id": "request_id"
256+
},
257+
"items": [
258+
{
259+
"request_index": 0,
260+
"block_key": 123,
261+
"prev_block_key": "",
262+
"properties": {
263+
"BP#prev_key": ""
264+
},
265+
"locations": [
266+
{
267+
"location_id": "loc_a",
268+
"status": "CLS_SERVING",
269+
"type": "ST_3FS",
270+
"spec_size": 2,
271+
"create_time": 1710000000000000,
272+
"location_specs": [
273+
{"name": "tp0", "uri": "3fs://cluster/root/key_123_tp0?offset=0&size=1024"},
274+
{"name": "tp1", "uri": "3fs://cluster/root/key_123_tp1?offset=0&size=1024"}
275+
]
276+
},
277+
{
278+
"location_id": "loc_b",
279+
"status": "CLS_WRITING",
280+
"type": "ST_NFS",
281+
"spec_size": 1,
282+
"create_time": 1710000001000000,
283+
"location_specs": [
284+
{"name": "tp0", "uri": "file://nfs/root/key_123_tp0?offset=0&size=1024"}
285+
]
286+
}
287+
]
288+
},
289+
{
290+
"request_index": 1,
291+
"block_key": 456,
292+
"locations": [
293+
{
294+
"status": "CLS_NOT_FOUND"
295+
}
296+
]
297+
}
298+
]
299+
}
300+
```
301+
302+
This diagnostic API returns raw metadata for every unmasked requested key. It does not apply location selection, data-file existence filtering, or lazy prune.

‎integration_test/meta_service/grpc_interface_test.py‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77
RegisterInstanceRequest,
88
GetInstanceInfoRequest,
99
GetCacheLocationRequest,
10+
GetCacheMetaDetailRequest,
1011
StartWriteCacheRequest,
1112
FinishWriteCacheRequest,
1213
RemoveCacheRequest,
@@ -76,6 +77,18 @@ def get_cache_location(self, data, check_response=True):
7677
f"Request to get_cache_location failed with error: {response_dict['header']['status']['message']}")
7778
return response_dict
7879

80+
def get_cache_meta_detail(self, data, check_response=True):
81+
"""Get full raw metadata detail for specified block keys"""
82+
request = self._convert_dict_to_proto(GetCacheMetaDetailRequest, data)
83+
response = self._stub.GetCacheMetaDetail(request, timeout=self._timeout)
84+
response_dict = self._convert_proto_to_dict(response)
85+
if check_response:
86+
if response_dict['header']['status']['code'] != "OK":
87+
raise AssertionError(
88+
f"Request to get_cache_meta_detail failed with error: "
89+
f"{response_dict['header']['status']['message']}")
90+
return response_dict
91+
7992
def start_write_cache(self, data, check_response=True):
8093
"""Start writing cache data"""
8194
request = self._convert_dict_to_proto(StartWriteCacheRequest, data)

‎integration_test/meta_service/http_interface_test.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,10 @@ def get_cache_location(self, data, check_response=True):
5252
"""Get cache location for specified block keys"""
5353
return self._make_api_request('/api/getCacheLocation', data, check_response)
5454

55+
def get_cache_meta_detail(self, data, check_response=True):
56+
"""Get full raw metadata detail for specified block keys"""
57+
return self._make_api_request('/api/getCacheMetaDetail', data, check_response)
58+
5559
def start_write_cache(self, data, check_response=True):
5660
"""Start writing cache data"""
5761
return self._make_api_request('/api/startWriteCache', data, check_response)

‎integration_test/meta_service/meta_interface_cases.py‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,11 @@ def get_cache_location(self, data, check_response=True) -> Dict:
4141
"""Get cache location for specified block keys"""
4242
return {}
4343

44+
@abc.abstractmethod
45+
def get_cache_meta_detail(self, data, check_response=True) -> Dict:
46+
"""Get full raw metadata detail for specified block keys"""
47+
return {}
48+
4449
@abc.abstractmethod
4550
def start_write_cache(self, data, check_response=True) -> Dict:
4651
"""Start writing cache data"""

‎kv_cache_manager/client/include/common.h‎

Lines changed: 29 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
#pragma once
22

3+
#include <cstdint>
34
#include <map>
45
#include <memory>
56
#include <string>
@@ -83,6 +84,33 @@ struct Metas {
8384
std::vector<std::string> metas;
8485
};
8586

87+
enum class CacheMetaLocationStatus : int32_t {
88+
CLS_NOT_FOUND = 0,
89+
CLS_NEW = 1,
90+
CLS_WRITING = 2,
91+
CLS_SERVING = 3,
92+
CLS_DELETING = 4,
93+
};
94+
95+
struct CacheMetaLocationDetail {
96+
std::string location_id;
97+
CacheMetaLocationStatus status{CacheMetaLocationStatus::CLS_NOT_FOUND};
98+
int32_t storage_type{0};
99+
int32_t spec_size{0};
100+
int64_t create_time{0};
101+
Location location_specs;
102+
};
103+
104+
struct CacheMetaDetailItem {
105+
int32_t request_index{0};
106+
int64_t block_key{0};
107+
std::string prev_block_key;
108+
std::map<std::string, std::string> properties;
109+
std::vector<CacheMetaLocationDetail> locations;
110+
};
111+
112+
using CacheMetaDetails = std::vector<CacheMetaDetailItem>;
113+
86114
using BlockMaskVector = std::vector<bool>;
87115
using BlockMaskOffset = size_t;
88116
using BlockMask = std::variant<BlockMaskVector, BlockMaskOffset>;
@@ -189,4 +217,4 @@ struct TransferTraceInfo {
189217
std::vector<std::string> block_ids; // block_ids.size() must be equal to block_buffer.size()
190218
};
191219

192-
} // namespace kv_cache_manager
220+
} // namespace kv_cache_manager

‎kv_cache_manager/client/include/manager_client.h‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,12 @@ class ManagerClient {
4343
const BlockMask &block_mask,
4444
int32_t detail_level) = 0;
4545

46+
virtual std::pair<ClientErrorCode, CacheMetaDetails> MatchMetaDetail(const std::string &trace_id,
47+
const std::vector<int64_t> &keys,
48+
const std::vector<int64_t> &tokens,
49+
const BlockMask &block_mask,
50+
int32_t detail_level) = 0;
51+
4652
virtual ClientErrorCode RemoveCache(const std::string &trace_id,
4753
const std::vector<int64_t> &keys,
4854
const std::vector<int64_t> &tokens,
@@ -59,4 +65,4 @@ class ManagerClient {
5965
virtual void Shutdown() = 0;
6066
};
6167

62-
} // namespace kv_cache_manager
68+
} // namespace kv_cache_manager

‎kv_cache_manager/client/include/meta_client.h‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,12 @@ class MetaClient {
4242
const BlockMask &block_mask,
4343
int32_t detail_level) = 0;
4444

45+
virtual std::pair<ClientErrorCode, CacheMetaDetails> MatchMetaDetail(const std::string &trace_id,
46+
const std::vector<int64_t> &keys,
47+
const std::vector<int64_t> &tokens,
48+
const BlockMask &block_mask,
49+
int32_t detail_level) = 0;
50+
4551
virtual std::pair<ClientErrorCode, int64_t> MatchLocationLen(const std::string &trace_id,
4652
QueryType query_type,
4753
const std::vector<int64_t> &keys,
@@ -60,4 +66,4 @@ class MetaClient {
6066
virtual ClientErrorCode Init(const std::string &config, const InitParams &init_params) = 0;
6167
virtual void Shutdown() = 0;
6268
};
63-
} // namespace kv_cache_manager
69+
} // namespace kv_cache_manager

‎kv_cache_manager/client/src/internal/stub/grpc_stub.cc‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@
55
#include <chrono>
66
#include <grpcpp/grpcpp.h>
77
#include <type_traits>
8+
#include <unordered_map>
9+
#include <utility>
810

911
#include "kv_cache_manager/client/src/internal/util/debug_string_util.h"
1012
#include "kv_cache_manager/common/logger.h"
@@ -78,6 +80,39 @@ kv_cache_manager::Locations GenLocations(
7880
return locations;
7981
}
8082

83+
kv_cache_manager::CacheMetaDetails GenCacheMetaDetails(
84+
const google::protobuf::RepeatedPtrField<::kv_cache_manager::proto::meta::CacheMetaDetailItem>
85+
&proto_cache_meta_details) {
86+
kv_cache_manager::CacheMetaDetails cache_meta_details;
87+
cache_meta_details.reserve(proto_cache_meta_details.size());
88+
for (const auto &proto_item : proto_cache_meta_details) {
89+
kv_cache_manager::CacheMetaDetailItem item;
90+
item.request_index = proto_item.request_index();
91+
item.block_key = proto_item.block_key();
92+
item.prev_block_key = proto_item.prev_block_key();
93+
for (const auto &[property_name, property_value] : proto_item.properties()) {
94+
item.properties[property_name] = property_value;
95+
}
96+
item.locations.reserve(proto_item.locations_size());
97+
for (const auto &proto_location : proto_item.locations()) {
98+
kv_cache_manager::CacheMetaLocationDetail location;
99+
location.location_id = proto_location.location_id();
100+
location.status =
101+
static_cast<kv_cache_manager::CacheMetaLocationStatus>(proto_location.status());
102+
location.storage_type = static_cast<int32_t>(proto_location.type());
103+
location.spec_size = proto_location.spec_size();
104+
location.create_time = proto_location.create_time();
105+
location.location_specs.reserve(proto_location.location_specs_size());
106+
for (const auto &proto_spec : proto_location.location_specs()) {
107+
location.location_specs.push_back({proto_spec.name(), proto_spec.uri()});
108+
}
109+
item.locations.push_back(std::move(location));
110+
}
111+
cache_meta_details.push_back(std::move(item));
112+
}
113+
return cache_meta_details;
114+
}
115+
81116
kv_cache_manager::ClientErrorCode
82117
GenCacheLocation(const kv_cache_manager::Locations &locations,
83118
google::protobuf::RepeatedPtrField<::kv_cache_manager::proto::meta::CacheLocation> *proto_locations) {
@@ -322,6 +357,27 @@ std::pair<ClientErrorCode, Metas> GrpcStub::GetCacheMeta(const std::string &trac
322357
return {ER_OK, {locations, metas}};
323358
}
324359

360+
std::pair<ClientErrorCode, CacheMetaDetails> GrpcStub::GetCacheMetaDetail(const std::string &trace_id,
361+
const std::string &instance_id,
362+
const KeyVector &keys,
363+
const TokenIdsVector &tokens,
364+
const BlockMask &block_mask,
365+
int32_t detail_level) {
366+
auto stub = GET_AND_CHECK_STUB_WITH_TYPE();
367+
proto::meta::GetCacheMetaDetailRequest request;
368+
SetKeysAndTokens(request, trace_id, instance_id, keys, tokens);
369+
ProtoConvert::BlockMaskToProto(block_mask, request.mutable_block_mask());
370+
request.set_detail_level(detail_level);
371+
grpc::ClientContext context;
372+
proto::meta::GetCacheMetaDetailResponse response;
373+
auto grpc_status = stub->GetCacheMetaDetail(&context, request, &response);
374+
CHECK_GRPC_STATUS_WITH_TYPE(grpc_status);
375+
CHECK_COMMON_HEADER_WITH_TYPE(response);
376+
auto cache_meta_details = GenCacheMetaDetails(response.items());
377+
KVCM_LOG_DEBUG("get cache meta detail success, items: %lu", cache_meta_details.size());
378+
return {ER_OK, cache_meta_details};
379+
}
380+
325381
std::pair<ClientErrorCode, Locations> GrpcStub::GetCacheLocation(const std::string &trace_id,
326382
const std::string &instance_id,
327383
QueryType query_type,

‎kv_cache_manager/client/src/internal/stub/grpc_stub.h‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,13 @@ class GrpcStub : public Stub {
3636
const BlockMask &block_mask,
3737
int32_t detail_level) override;
3838

39+
std::pair<ClientErrorCode, CacheMetaDetails> GetCacheMetaDetail(const std::string &trace_id,
40+
const std::string &instance_id,
41+
const KeyVector &keys,
42+
const TokenIdsVector &tokens,
43+
const BlockMask &block_mask,
44+
int32_t detail_level) override;
45+
3946
std::pair<ClientErrorCode, Locations>
4047
GetCacheLocation(const std::string &trace_id,
4148
const std::string &instance_id,

‎kv_cache_manager/client/src/internal/stub/stub.h‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,13 @@ class Stub {
4040
const BlockMask &block_mask,
4141
int32_t detail_level) = 0;
4242

43+
virtual std::pair<ClientErrorCode, CacheMetaDetails> GetCacheMetaDetail(const std::string &trace_id,
44+
const std::string &instance_id,
45+
const KeyVector &keys,
46+
const TokenIdsVector &tokens,
47+
const BlockMask &block_mask,
48+
int32_t detail_level) = 0;
49+
4350
virtual std::pair<ClientErrorCode, Locations>
4451
GetCacheLocation(const std::string &trace_id,
4552
const std::string &instance_id,

0 commit comments

Comments
 (0)