client-query-cache 0.12.0__tar.gz → 0.13.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (97) hide show
  1. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/PKG-INFO +1 -1
  2. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/pyproject.toml +1 -1
  3. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/__init__.py +12 -0
  4. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/_shared/adapters.py +43 -28
  5. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/_shared/coordinator.py +45 -6
  6. client_query_cache-0.13.0/src/client_query_cache/_shared/diagnostics.py +165 -0
  7. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/asynchronous/__init__.py +16 -0
  8. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/otel.py +36 -13
  9. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/shared.py +22 -3
  10. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/synchronous/__init__.py +16 -0
  11. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/LICENSE +0 -0
  12. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/README.md +0 -0
  13. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/native/shared-index/Cargo.lock +0 -0
  14. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/native/shared-index/Cargo.toml +0 -0
  15. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/native/shared-index/deny.toml +0 -0
  16. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/native/shared-index/src/array/tests.rs +0 -0
  17. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/native/shared-index/src/array.rs +0 -0
  18. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/native/shared-index/src/clock.rs +0 -0
  19. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/native/shared-index/src/echo/tests.rs +0 -0
  20. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/native/shared-index/src/echo.rs +0 -0
  21. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/native/shared-index/src/frames/tests.rs +0 -0
  22. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/native/shared-index/src/frames.rs +0 -0
  23. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/native/shared-index/src/hash/tests.rs +0 -0
  24. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/native/shared-index/src/hash.rs +0 -0
  25. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/native/shared-index/src/index/support_tests.rs +0 -0
  26. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/native/shared-index/src/index/tests.rs +0 -0
  27. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/native/shared-index/src/index.rs +0 -0
  28. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/native/shared-index/src/key_encoder.rs +0 -0
  29. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/native/shared-index/src/keys.rs +0 -0
  30. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/native/shared-index/src/lib.rs +0 -0
  31. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/native/shared-index/src/local_cache/shared.rs +0 -0
  32. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/native/shared-index/src/local_cache.rs +0 -0
  33. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/native/shared-index/src/memory/support_tests.rs +0 -0
  34. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/native/shared-index/src/memory/tests.rs +0 -0
  35. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/native/shared-index/src/memory.rs +0 -0
  36. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/native/shared-index/src/python.rs +0 -0
  37. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/native/shared-index/src/relay/tests.rs +0 -0
  38. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/native/shared-index/src/relay.rs +0 -0
  39. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/native/shared-index/src/ring/tests.rs +0 -0
  40. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/native/shared-index/src/ring.rs +0 -0
  41. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/native/shared-index/src/sync.rs +0 -0
  42. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/rust-toolchain.toml +0 -0
  43. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/_core/__init__.py +0 -0
  44. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/_core/canonical.py +0 -0
  45. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/_core/codec.py +0 -0
  46. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/_core/collation.py +0 -0
  47. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/_core/collection_metadata.py +0 -0
  48. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/_core/contracts.pyi +0 -0
  49. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/_core/count_reads.py +0 -0
  50. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/_core/cursor_capture.py +0 -0
  51. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/_core/entries.py +0 -0
  52. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/_core/errors.py +0 -0
  53. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/_core/find_one_reads.py +0 -0
  54. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/_core/find_reads.py +0 -0
  55. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/_core/identity_reads.py +0 -0
  56. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/_core/keys.py +0 -0
  57. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/_core/lifecycle.py +0 -0
  58. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/_core/locking.py +0 -0
  59. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/_core/lru.py +0 -0
  60. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/_core/manager.py +0 -0
  61. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/_core/namespace.py +0 -0
  62. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/_core/namespace_metadata.py +0 -0
  63. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/_core/native.py +0 -0
  64. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/_core/order_sensitive_keys.py +0 -0
  65. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/_core/projection.py +0 -0
  66. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/_core/query_filters.py +0 -0
  67. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/_core/read_classification.py +0 -0
  68. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/_core/read_validation.py +0 -0
  69. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/_core/retention.py +0 -0
  70. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/_core/snapshots.py +0 -0
  71. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/_core/stream_activation.py +0 -0
  72. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/_core/stream_cost.py +0 -0
  73. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/_core/stream_events.py +0 -0
  74. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/_core/stream_health.py +0 -0
  75. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/_core/stream_options.py +0 -0
  76. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/_core/stream_startup.py +0 -0
  77. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/_core/traversal.py +0 -0
  78. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/_core/unique_keys.py +0 -0
  79. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/_shared/__init__.py +0 -0
  80. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/_shared/attachment.py +0 -0
  81. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/_shared/shared_index.py +0 -0
  82. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/_shared/wire.py +0 -0
  83. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/_shared_index.pyi +0 -0
  84. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/_types.py +0 -0
  85. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/asynchronous/collection.py +0 -0
  86. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/asynchronous/cursors.py +0 -0
  87. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/asynchronous/database.py +0 -0
  88. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/asynchronous/manager.py +0 -0
  89. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/asynchronous/shared.py +0 -0
  90. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/asynchronous/streams.py +0 -0
  91. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/py.typed +0 -0
  92. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/synchronous/collection.py +0 -0
  93. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/synchronous/cursors.py +0 -0
  94. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/synchronous/database.py +0 -0
  95. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/synchronous/manager.py +0 -0
  96. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/synchronous/shared.py +0 -0
  97. {client_query_cache-0.12.0 → client_query_cache-0.13.0}/src/client_query_cache/synchronous/streams.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: client-query-cache
3
- Version: 0.12.0
3
+ Version: 0.13.0
4
4
  Classifier: Framework :: AsyncIO
5
5
  Classifier: Operating System :: POSIX :: Linux
6
6
  Classifier: Programming Language :: Python :: Implementation :: CPython
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "client-query-cache"
3
- version = "0.12.0"
3
+ version = "0.13.0"
4
4
  description = "Sync and asyncio PyMongo query caching with change-stream invalidation and Rust-backed sharing across workers."
5
5
  authors = [
6
6
  { name = "Alessio Locatelli", email = "<software.development@secure.mailbox.org>" },
@@ -5,10 +5,16 @@ from ._core.errors import (
5
5
  UnsupportedCacheRequestError,
6
6
  )
7
7
  from .shared import (
8
+ SharedBypassReason,
9
+ SharedBypassReasonCount,
8
10
  SharedCacheConfig,
9
11
  SharedCacheConnection,
10
12
  SharedCacheServer,
11
13
  SharedCacheStatistics,
14
+ SharedCapacityUsage,
15
+ SharedDatabaseHealth,
16
+ SharedOwnerSnapshot,
17
+ SharedStreamStatus,
12
18
  )
13
19
  from .synchronous import (
14
20
  BypassReason,
@@ -44,12 +50,18 @@ __all__ = [
44
50
  "RetentionDeclineCount",
45
51
  "RetentionDeclineReason",
46
52
  "RetentionRecordKind",
53
+ "SharedBypassReason",
54
+ "SharedBypassReasonCount",
47
55
  "SharedCacheConfig",
48
56
  "SharedCacheConnection",
49
57
  "SharedCacheManager",
50
58
  "SharedCacheServer",
51
59
  "SharedCacheStatistics",
52
60
  "SharedCachedCollection",
61
+ "SharedCapacityUsage",
62
+ "SharedDatabaseHealth",
63
+ "SharedOwnerSnapshot",
64
+ "SharedStreamStatus",
53
65
  "StreamCostSnapshot",
54
66
  "StreamHealthSnapshot",
55
67
  "StreamHealthStatus",
@@ -43,6 +43,14 @@ from client_query_cache._shared.attachment import (
43
43
  LocalIndex,
44
44
  attachment_unavailable,
45
45
  )
46
+ from client_query_cache._shared.diagnostics import (
47
+ REASONS_BY_VALUE,
48
+ SharedBypassReason,
49
+ SharedCacheStatistics,
50
+ SharedOwnerSnapshot,
51
+ owner_snapshot_from_wire,
52
+ reason_counts,
53
+ )
46
54
  from client_query_cache._shared.wire import (
47
55
  KeyCache,
48
56
  ProtocolError,
@@ -86,10 +94,10 @@ if TYPE_CHECKING:
86
94
  type View = SharedCachedCollection[Any] | AsyncSharedCachedCollection[Any]
87
95
 
88
96
  _STALE = CollectionMetadata(checked_epoch=0, bypass_reason=None, default_collation=None)
89
- UNPORTABLE_KEY = "unportable-key"
90
- PROTOTYPE_SCOPE = "shared-scope"
91
- METADATA_REFRESH = "metadata-refresh"
92
- OWNER_UNAVAILABLE = "owner-unavailable"
97
+ UNPORTABLE_KEY = SharedBypassReason.UNPORTABLE_KEY
98
+ PROTOTYPE_SCOPE = SharedBypassReason.SHARED_SCOPE
99
+ METADATA_REFRESH = SharedBypassReason.METADATA_REFRESH
100
+ OWNER_UNAVAILABLE = SharedBypassReason.OWNER_UNAVAILABLE
93
101
  NO_LOCAL_HIT = object()
94
102
  _KEY_CACHE_ENTRIES = 8192
95
103
  _REATTACH_SECONDS = 0.1
@@ -101,26 +109,31 @@ class LocalObservation:
101
109
  max_entries: ClassVar[None] = None
102
110
  hits: NonNegativeInt = 0
103
111
  misses: NonNegativeInt = 0
104
- bypasses: dict[str, NonNegativeInt] = field(default_factory=dict)
112
+ oversized: NonNegativeInt = 0
113
+ bypasses: dict[SharedBypassReason, NonNegativeInt] = field(default_factory=dict)
105
114
 
106
- def record_bypass(self, reason: BypassReason | str) -> None:
107
- key = reason.value if isinstance(reason, BypassReason) else reason
115
+ def record_bypass(self, reason: str) -> None:
116
+ try:
117
+ member = REASONS_BY_VALUE[reason]
118
+ except KeyError:
119
+ member = SharedBypassReason.UNSPECIFIED
108
120
  try:
109
- self.bypasses[key] += 1
121
+ self.bypasses[member] += 1
110
122
  except KeyError:
111
- self.bypasses[key] = 1
123
+ self.bypasses[member] = 1
112
124
 
113
125
  def record_oversized_bypass(self) -> None:
114
- self.record_bypass("oversized")
115
-
126
+ self.oversized += 1
116
127
 
117
- @dataclass(frozen=True, slots=True)
118
- class SharedCacheStatistics:
119
- """Read counts for this worker attachment."""
120
-
121
- hits: NonNegativeInt
122
- misses: NonNegativeInt
123
- bypasses: NonNegativeInt
128
+ def snapshot(self) -> SharedCacheStatistics:
129
+ recorded = self.bypasses.copy()
130
+ return SharedCacheStatistics(
131
+ self.hits,
132
+ self.misses,
133
+ sum(recorded.values()),
134
+ self.oversized,
135
+ reason_counts(recorded),
136
+ )
124
137
 
125
138
 
126
139
  class _RemoteCaptureCore:
@@ -1473,11 +1486,12 @@ class SharedCacheManager[DocumentType: Mapping[str, Any]]:
1473
1486
  raise CacheClosedError("the shared cache manager is closed")
1474
1487
 
1475
1488
  def snapshot(self) -> SharedCacheStatistics:
1476
- return SharedCacheStatistics(
1477
- self.observation.hits,
1478
- self.observation.misses,
1479
- sum(self.observation.bypasses.values()),
1480
- )
1489
+ return self.observation.snapshot()
1490
+
1491
+ def owner_snapshot(self) -> SharedOwnerSnapshot | None:
1492
+ self._check_open()
1493
+ reply = self.endpoint.request({"op": "observe"})
1494
+ return None if reply is None else owner_snapshot_from_wire(reply)
1481
1495
 
1482
1496
  @property
1483
1497
  def client(self) -> MongoClient[DocumentType]:
@@ -1678,11 +1692,12 @@ class AsyncSharedCacheManager[DocumentType: Mapping[str, Any]]:
1678
1692
  raise CacheClosedError("the shared cache manager is closed")
1679
1693
 
1680
1694
  def snapshot(self) -> SharedCacheStatistics:
1681
- return SharedCacheStatistics(
1682
- self.observation.hits,
1683
- self.observation.misses,
1684
- sum(self.observation.bypasses.values()),
1685
- )
1695
+ return self.observation.snapshot()
1696
+
1697
+ async def owner_snapshot(self) -> SharedOwnerSnapshot | None:
1698
+ self._check_open()
1699
+ reply = await self.endpoint.request({"op": "observe"})
1700
+ return None if reply is None else owner_snapshot_from_wire(reply)
1686
1701
 
1687
1702
  @property
1688
1703
  def client(self) -> AsyncMongoClient[DocumentType]:
@@ -29,6 +29,10 @@ from client_query_cache._core.keys import NamespaceId
29
29
  from client_query_cache._core.manager import DEFAULT_MAX_NAMESPACES, CacheCoreConfig
30
30
  from client_query_cache._core.snapshots import BypassReason
31
31
  from client_query_cache._core.stream_cost import LagCaptureWindowConfig
32
+ from client_query_cache._shared.diagnostics import (
33
+ SharedBypassReason,
34
+ SharedStreamStatus,
35
+ )
32
36
  from client_query_cache._shared.wire import (
33
37
  LENGTH_BYTES,
34
38
  PROTOCOL_VERSION,
@@ -257,6 +261,7 @@ class SharedCacheOwner:
257
261
  "_paused_until",
258
262
  "_rings",
259
263
  "_selector",
264
+ "_started",
260
265
  "client",
261
266
  "config",
262
267
  "core",
@@ -325,6 +330,7 @@ class SharedCacheOwner:
325
330
  self._listener: socket.socket | None = None
326
331
  self._lock_file: TextIO | None = None
327
332
  self._paused_until = 0.0
333
+ self._started = time.monotonic()
328
334
 
329
335
  def _publish_progress(self, database: str) -> None:
330
336
  assert self._index is not None
@@ -401,13 +407,13 @@ class SharedCacheOwner:
401
407
 
402
408
  def _gate(self, database: str, now: NonNegativeFloat) -> str | None:
403
409
  if database not in self.config.databases:
404
- return "database-not-authorized"
410
+ return SharedBypassReason.DATABASE_NOT_AUTHORIZED.value
405
411
  if self._activate(database, now) != "active":
406
- return "stream-starting"
412
+ return SharedBypassReason.STREAM_STARTING.value
407
413
  if not self.core.is_database_available(database):
408
- return "stream-unavailable"
414
+ return SharedBypassReason.STREAM_UNAVAILABLE.value
409
415
  if not self.lease_fresh(database, now):
410
- return "progress-expired"
416
+ return SharedBypassReason.PROGRESS_EXPIRED.value
411
417
  return None
412
418
 
413
419
  def _new_handle(
@@ -504,7 +510,10 @@ class SharedCacheOwner:
504
510
  self.counters.refreshes += 1
505
511
  return {"r": "refresh", "epoch": 0, "index_generation": 0}
506
512
  self.counters.bypasses += 1
507
- return {"r": "bypass", "reason": "namespace_capacity"}
513
+ return {
514
+ "r": "bypass",
515
+ "reason": SharedBypassReason.NAMESPACE_CAPACITY.value,
516
+ }
508
517
  current, index_generation = metadata
509
518
  if epoch != current:
510
519
  self.counters.refreshes += 1
@@ -579,7 +588,7 @@ class SharedCacheOwner:
579
588
  if probe_token is None:
580
589
  self.counters.bypasses += 1
581
590
  reason = (
582
- "namespace_capacity"
591
+ SharedBypassReason.NAMESPACE_CAPACITY.value
583
592
  if not self.core.can_register_namespace(namespace)
584
593
  else BypassReason.METADATA_UNAVAILABLE.value
585
594
  )
@@ -816,12 +825,41 @@ class SharedCacheOwner:
816
825
  else:
817
826
  self.counters.rejected_admissions += 1
818
827
 
828
+ def _stream_status(
829
+ self, database: str, now: NonNegativeFloat
830
+ ) -> SharedStreamStatus:
831
+ with self._activation_lock:
832
+ try:
833
+ state, _since = self._activation[database]
834
+ except KeyError:
835
+ return SharedStreamStatus.NOT_STARTED
836
+ if state == "pending":
837
+ return SharedStreamStatus.STARTING
838
+ if state == "failed":
839
+ return SharedStreamStatus.STARTUP_FAILED
840
+ if not self.core.is_database_available(database):
841
+ return SharedStreamStatus.UNAVAILABLE
842
+ if not self.lease_fresh(database, now):
843
+ return SharedStreamStatus.PROGRESS_EXPIRED
844
+ return SharedStreamStatus.HEALTHY
845
+
819
846
  def observation(self, now: NonNegativeFloat) -> Message:
820
847
  snapshot = self.core.snapshot()
848
+ shared_index = self.config.shared_index
821
849
  return {
822
850
  "scope": "group",
823
851
  "incarnation": self.incarnation,
824
852
  "observed_monotonic": now,
853
+ "uptime_seconds": now - self._started,
854
+ "limits": {
855
+ "index_entries": None if shared_index is None else shared_index.slots,
856
+ "namespaces": self.core.max_namespaces,
857
+ "connections": self.config.limits.connections,
858
+ },
859
+ "namespaces": sum(
860
+ len(self.core.namespaces_for_database(database))
861
+ for database in self.config.databases
862
+ ),
825
863
  "cache": {
826
864
  "used_bytes": snapshot.used_bytes,
827
865
  "entry_count": snapshot.entry_count,
@@ -839,6 +877,7 @@ class SharedCacheOwner:
839
877
  "available_since": None
840
878
  if self._index is None
841
879
  else self.core.available_since(database),
880
+ "status": self._stream_status(database, now).value,
842
881
  }
843
882
  for database in self.config.databases
844
883
  },
@@ -0,0 +1,165 @@
1
+ from __future__ import annotations
2
+
3
+ from dataclasses import dataclass
4
+ from enum import StrEnum
5
+ from itertools import starmap
6
+ from typing import TYPE_CHECKING, Final, TypedDict, cast
7
+
8
+ from client_query_cache._types import (
9
+ NonEmptyStr,
10
+ NonNegativeFloat,
11
+ NonNegativeInt,
12
+ PositiveInt,
13
+ )
14
+
15
+ if TYPE_CHECKING:
16
+ from collections.abc import Mapping
17
+
18
+ from client_query_cache._shared.attachment import Message
19
+
20
+
21
+ class SharedBypassReason(StrEnum):
22
+ SESSION = "session"
23
+ READ_PROFILE = "read_profile"
24
+ UNSUPPORTED_OPTIONS = "unsupported_options"
25
+ UNSAFE_FILTER = "unsafe_filter"
26
+ UNSAFE_PROJECTION = "unsafe_projection"
27
+ UNSAFE_PIPELINE = "unsafe_pipeline"
28
+ UNCANONICALIZABLE_KEY = "uncanonicalizable_key"
29
+ UNPORTABLE_KEY = "unportable_key"
30
+ SHARED_SCOPE = "shared_scope"
31
+ MISSING_COLLECTION = "missing_collection"
32
+ VIEW_COLLECTION = "view_collection"
33
+ TIME_SERIES_COLLECTION = "time_series_collection"
34
+ METADATA_UNAVAILABLE = "metadata_unavailable"
35
+ METADATA_REFRESH = "metadata_refresh"
36
+ NAMESPACE_CAPACITY = "namespace_capacity"
37
+ DATABASE_NOT_AUTHORIZED = "database_not_authorized"
38
+ STREAM_STARTING = "stream_starting"
39
+ STREAM_UNAVAILABLE = "stream_unavailable"
40
+ PROGRESS_EXPIRED = "progress_expired"
41
+ OWNER_UNAVAILABLE = "owner_unavailable"
42
+ UNSPECIFIED = "unspecified"
43
+
44
+
45
+ class SharedStreamStatus(StrEnum):
46
+ NOT_STARTED = "not_started"
47
+ STARTING = "starting"
48
+ STARTUP_FAILED = "startup_failed"
49
+ UNAVAILABLE = "unavailable"
50
+ PROGRESS_EXPIRED = "progress_expired"
51
+ HEALTHY = "healthy"
52
+
53
+
54
+ @dataclass(frozen=True, slots=True)
55
+ class SharedBypassReasonCount:
56
+ reason: SharedBypassReason
57
+ count: NonNegativeInt
58
+
59
+
60
+ @dataclass(frozen=True, slots=True)
61
+ class SharedCacheStatistics:
62
+ hits: NonNegativeInt
63
+ misses: NonNegativeInt
64
+ bypasses: NonNegativeInt
65
+ oversized_bypasses: NonNegativeInt
66
+ bypass_reasons: tuple[SharedBypassReasonCount, ...]
67
+
68
+
69
+ REASONS_BY_VALUE: Final = {reason.value: reason for reason in SharedBypassReason}
70
+
71
+
72
+ def reason_counts(
73
+ recorded: Mapping[SharedBypassReason, NonNegativeInt],
74
+ ) -> tuple[SharedBypassReasonCount, ...]:
75
+ totals = dict.fromkeys(SharedBypassReason, 0)
76
+ totals.update(recorded)
77
+ return tuple(starmap(SharedBypassReasonCount, totals.items()))
78
+
79
+
80
+ @dataclass(frozen=True, slots=True)
81
+ class SharedCapacityUsage:
82
+ in_use: NonNegativeInt
83
+ limit: PositiveInt
84
+
85
+
86
+ @dataclass(frozen=True, slots=True)
87
+ class SharedDatabaseHealth:
88
+ database_name: NonEmptyStr
89
+ status: SharedStreamStatus
90
+
91
+
92
+ @dataclass(frozen=True, slots=True)
93
+ class SharedOwnerSnapshot:
94
+ incarnation: int
95
+ uptime_seconds: NonNegativeFloat
96
+ cache_bytes: SharedCapacityUsage
97
+ index_entries: SharedCapacityUsage
98
+ namespaces: SharedCapacityUsage
99
+ connections: SharedCapacityUsage
100
+ evictions: NonNegativeInt
101
+ rejected_connections: NonNegativeInt
102
+ streams: tuple[SharedDatabaseHealth, ...]
103
+
104
+
105
+ class _Limits(TypedDict):
106
+ index_entries: PositiveInt
107
+ namespaces: PositiveInt
108
+ connections: PositiveInt
109
+
110
+
111
+ class _Cache(TypedDict):
112
+ used_bytes: NonNegativeInt
113
+ budget_bytes: PositiveInt
114
+ evictions: NonNegativeInt
115
+
116
+
117
+ class _Database(TypedDict):
118
+ status: str
119
+
120
+
121
+ class _Counters(TypedDict):
122
+ connections_rejected: NonNegativeInt
123
+
124
+
125
+ class _SharedIndex(TypedDict):
126
+ published: NonNegativeInt
127
+
128
+
129
+ class _Observation(TypedDict):
130
+ incarnation: int
131
+ uptime_seconds: NonNegativeFloat
132
+ limits: _Limits
133
+ namespaces: NonNegativeInt
134
+ connections: NonNegativeInt
135
+ cache: _Cache
136
+ counters: _Counters
137
+ shared_index: _SharedIndex
138
+ databases: dict[str, _Database]
139
+
140
+
141
+ def owner_snapshot_from_wire(reply: Message) -> SharedOwnerSnapshot:
142
+ return _snapshot(cast("_Observation", reply))
143
+
144
+
145
+ def _snapshot(observation: _Observation) -> SharedOwnerSnapshot:
146
+ limits = observation["limits"]
147
+ cache = observation["cache"]
148
+ return SharedOwnerSnapshot(
149
+ incarnation=int(observation["incarnation"]),
150
+ uptime_seconds=observation["uptime_seconds"],
151
+ cache_bytes=SharedCapacityUsage(cache["used_bytes"], cache["budget_bytes"]),
152
+ index_entries=SharedCapacityUsage(
153
+ observation["shared_index"]["published"], limits["index_entries"]
154
+ ),
155
+ namespaces=SharedCapacityUsage(observation["namespaces"], limits["namespaces"]),
156
+ connections=SharedCapacityUsage(
157
+ observation["connections"], limits["connections"]
158
+ ),
159
+ evictions=cache["evictions"],
160
+ rejected_connections=observation["counters"]["connections_rejected"],
161
+ streams=tuple(
162
+ SharedDatabaseHealth(name, SharedStreamStatus(database["status"]))
163
+ for name, database in observation["databases"].items()
164
+ ),
165
+ )
@@ -14,6 +14,15 @@ from client_query_cache._core.stream_health import (
14
14
  StreamHealthSnapshot,
15
15
  StreamHealthStatus,
16
16
  )
17
+ from client_query_cache._shared.diagnostics import (
18
+ SharedBypassReason,
19
+ SharedBypassReasonCount,
20
+ SharedCacheStatistics,
21
+ SharedCapacityUsage,
22
+ SharedDatabaseHealth,
23
+ SharedOwnerSnapshot,
24
+ SharedStreamStatus,
25
+ )
17
26
  from client_query_cache._shared_index import LocalCacheCore as CacheCore
18
27
 
19
28
  from .collection import CachedCollection
@@ -35,8 +44,15 @@ __all__ = [
35
44
  "RetentionDeclineCount",
36
45
  "RetentionDeclineReason",
37
46
  "RetentionRecordKind",
47
+ "SharedBypassReason",
48
+ "SharedBypassReasonCount",
38
49
  "SharedCacheManager",
50
+ "SharedCacheStatistics",
39
51
  "SharedCachedCollection",
52
+ "SharedCapacityUsage",
53
+ "SharedDatabaseHealth",
54
+ "SharedOwnerSnapshot",
55
+ "SharedStreamStatus",
40
56
  "StreamCostSnapshot",
41
57
  "StreamHealthSnapshot",
42
58
  "StreamHealthStatus",
@@ -1,7 +1,7 @@
1
1
  from __future__ import annotations
2
2
 
3
3
  import math
4
- from typing import TYPE_CHECKING
4
+ from typing import TYPE_CHECKING, Any
5
5
 
6
6
  try:
7
7
  from opentelemetry.metrics import Observation
@@ -17,6 +17,10 @@ from client_query_cache._core.stream_cost import (
17
17
  INVALIDATION_LAG_CLOCK_SKEW_LIMITATION,
18
18
  RESIDENT_BYTES_SCOPE,
19
19
  )
20
+ from client_query_cache._shared.adapters import (
21
+ AsyncSharedCacheManager,
22
+ SharedCacheManager,
23
+ )
20
24
  from client_query_cache._types import Probability
21
25
 
22
26
  if TYPE_CHECKING:
@@ -30,6 +34,9 @@ __all__ = ["register_cache_metrics"]
30
34
 
31
35
  _DB_NAMESPACE_ATTRIBUTE = "db.namespace"
32
36
 
37
+ type SharedStatisticsSource = SharedCacheManager[Any] | AsyncSharedCacheManager[Any]
38
+ type CounterSource = StatisticsSource | SharedStatisticsSource
39
+
33
40
  _CACHE_COUNTER_FIELDS: tuple[tuple[str, str, str], ...] = (
34
41
  ("client_query_cache.cache.hits", "hits", "Cumulative cache hits."),
35
42
  ("client_query_cache.cache.misses", "misses", "Cumulative cache misses."),
@@ -50,6 +57,10 @@ _CACHE_COUNTER_FIELDS: tuple[tuple[str, str, str], ...] = (
50
57
  ),
51
58
  )
52
59
 
60
+ _WORKER_COUNTER_FIELDS = tuple(
61
+ counter for counter in _CACHE_COUNTER_FIELDS if counter[1] != "evictions"
62
+ )
63
+
53
64
  _STREAM_COUNTER_FIELDS: tuple[tuple[str, str, str, str], ...] = (
54
65
  (
55
66
  "client_query_cache.stream.polls",
@@ -84,7 +95,7 @@ def _percentile(sorted_samples: tuple[float, ...], percentile: Probability) -> f
84
95
 
85
96
 
86
97
  def _make_cache_counter_callback(
87
- cache_core: StatisticsSource, field: str
98
+ cache_core: CounterSource, field: str
88
99
  ) -> Callable[[CallbackOptions], Iterable[Observation]]:
89
100
  def callback(_options: CallbackOptions) -> Iterable[Observation]:
90
101
  yield Observation(getattr(cache_core.snapshot(), field))
@@ -93,7 +104,7 @@ def _make_cache_counter_callback(
93
104
 
94
105
 
95
106
  def _make_bypass_reason_callback(
96
- cache_core: StatisticsSource,
107
+ cache_core: CounterSource,
97
108
  ) -> Callable[[CallbackOptions], Iterable[Observation]]:
98
109
  def callback(_options: CallbackOptions) -> Iterable[Observation]:
99
110
  for record in cache_core.snapshot().bypass_reasons:
@@ -104,8 +115,12 @@ def _make_bypass_reason_callback(
104
115
  return callback
105
116
 
106
117
 
107
- def _register_cache_counters(meter: Meter, cache_core: StatisticsSource) -> None:
108
- for name, field, description in _CACHE_COUNTER_FIELDS:
118
+ def _register_cache_counters(
119
+ meter: Meter,
120
+ cache_core: CounterSource,
121
+ fields: tuple[tuple[str, str, str], ...],
122
+ ) -> None:
123
+ for name, field, description in fields:
109
124
  meter.create_observable_counter(
110
125
  name,
111
126
  callbacks=[_make_cache_counter_callback(cache_core, field)],
@@ -206,14 +221,7 @@ def _validate_lag_percentiles(lag_percentiles: tuple[float, ...]) -> None:
206
221
  raise CacheConfigurationError(message)
207
222
 
208
223
 
209
- def register_cache_metrics(
210
- meter: Meter,
211
- cache_core: StatisticsSource,
212
- *,
213
- lag_percentiles: tuple[Probability, ...] = (0.5, 0.95, 1.0),
214
- ) -> None:
215
- _validate_lag_percentiles(lag_percentiles)
216
- _register_cache_counters(meter, cache_core)
224
+ def _register_bypass_reasons(meter: Meter, cache_core: CounterSource) -> None:
217
225
  meter.create_observable_counter(
218
226
  "client_query_cache.cache.bypasses.by_reason",
219
227
  callbacks=[_make_bypass_reason_callback(cache_core)],
@@ -222,6 +230,21 @@ def register_cache_metrics(
222
230
  "Cumulative ordinary cache bypass recording events by fixed reason."
223
231
  ),
224
232
  )
233
+
234
+
235
+ def register_cache_metrics(
236
+ meter: Meter,
237
+ cache_core: StatisticsSource | SharedStatisticsSource,
238
+ *,
239
+ lag_percentiles: tuple[Probability, ...] = (0.5, 0.95, 1.0),
240
+ ) -> None:
241
+ _validate_lag_percentiles(lag_percentiles)
242
+ if isinstance(cache_core, (SharedCacheManager, AsyncSharedCacheManager)):
243
+ _register_cache_counters(meter, cache_core, _WORKER_COUNTER_FIELDS)
244
+ _register_bypass_reasons(meter, cache_core)
245
+ return
246
+ _register_cache_counters(meter, cache_core, _CACHE_COUNTER_FIELDS)
247
+ _register_bypass_reasons(meter, cache_core)
225
248
  _register_cache_gauges(meter, cache_core)
226
249
  _register_stream_counters(meter, cache_core)
227
250
  _register_lag_gauges(meter, cache_core, lag_percentiles)
@@ -20,13 +20,21 @@ from annotated_types import Ge, Le
20
20
  from client_query_cache._core.errors import CacheClosedError, CacheConfigurationError
21
21
  from client_query_cache._core.manager import CacheCoreConfig
22
22
  from client_query_cache._core.stream_cost import DEFAULT_LAG_CAPTURE_WINDOW_CONFIG
23
- from client_query_cache._shared.adapters import SharedCacheStatistics
24
23
  from client_query_cache._shared.attachment import AttachmentConfig
25
24
  from client_query_cache._shared.coordinator import (
26
25
  OwnerConfig,
27
26
  SharedCacheOwner,
28
27
  TransportLimits,
29
28
  )
29
+ from client_query_cache._shared.diagnostics import (
30
+ SharedBypassReason,
31
+ SharedBypassReasonCount,
32
+ SharedCacheStatistics,
33
+ SharedCapacityUsage,
34
+ SharedDatabaseHealth,
35
+ SharedOwnerSnapshot,
36
+ SharedStreamStatus,
37
+ )
30
38
  from client_query_cache._shared.shared_index import SharedIndexLimits
31
39
  from client_query_cache._types import PositiveInt
32
40
 
@@ -36,10 +44,16 @@ if TYPE_CHECKING:
36
44
  from multiprocessing.process import BaseProcess
37
45
 
38
46
  __all__ = [
47
+ "SharedBypassReason",
48
+ "SharedBypassReasonCount",
39
49
  "SharedCacheConfig",
40
50
  "SharedCacheConnection",
41
51
  "SharedCacheServer",
42
52
  "SharedCacheStatistics",
53
+ "SharedCapacityUsage",
54
+ "SharedDatabaseHealth",
55
+ "SharedOwnerSnapshot",
56
+ "SharedStreamStatus",
43
57
  ]
44
58
 
45
59
  _SERVERS: weakref.WeakSet[SharedCacheServer] = weakref.WeakSet()
@@ -47,6 +61,8 @@ _LOGGER = logging.getLogger(__name__)
47
61
  _MAX_NAMESPACES = (1 << 32) - 1
48
62
  _MAX_ARENA_BYTES = _MAX_NAMESPACES * 8
49
63
  _MAX_SLOTS = 1 << ((sys.maxsize // 64).bit_length() - 1)
64
+ _FRAME_OVERHEAD_BYTES = 65_536
65
+ _DATABASE_OBSERVATION_BYTES = 128
50
66
 
51
67
 
52
68
  def _detach_servers_after_fork() -> (
@@ -177,15 +193,18 @@ class SharedCacheServer:
177
193
  self._directory_cleanup = weakref.finalize(self, shutil.rmtree, self._directory)
178
194
  _SERVERS.add(self)
179
195
  path = str(self._directory / "owner.sock")
196
+ frame_overhead_bytes = _FRAME_OVERHEAD_BYTES + sum(
197
+ _DATABASE_OBSERVATION_BYTES + len(name.encode()) for name in databases
198
+ )
180
199
  limits = TransportLimits(
181
200
  rpc_deadline_seconds=0.25,
182
201
  progress_expiry_seconds=3.0,
183
- queued_bytes_per_connection=config.max_entry_bytes + 65_536,
202
+ queued_bytes_per_connection=config.max_entry_bytes + frame_overhead_bytes,
184
203
  requests_per_connection=256,
185
204
  connections=config.connections,
186
205
  captures=4096,
187
206
  capture_seconds=30.0,
188
- frame_overhead_bytes=65_536,
207
+ frame_overhead_bytes=frame_overhead_bytes,
189
208
  )
190
209
  self._config = OwnerConfig(
191
210
  socket_path=path,
@@ -14,6 +14,15 @@ from client_query_cache._core.stream_health import (
14
14
  StreamHealthSnapshot,
15
15
  StreamHealthStatus,
16
16
  )
17
+ from client_query_cache._shared.diagnostics import (
18
+ SharedBypassReason,
19
+ SharedBypassReasonCount,
20
+ SharedCacheStatistics,
21
+ SharedCapacityUsage,
22
+ SharedDatabaseHealth,
23
+ SharedOwnerSnapshot,
24
+ SharedStreamStatus,
25
+ )
17
26
  from client_query_cache._shared_index import LocalCacheCore as CacheCore
18
27
 
19
28
  from .collection import CachedCollection
@@ -35,8 +44,15 @@ __all__ = [
35
44
  "RetentionDeclineCount",
36
45
  "RetentionDeclineReason",
37
46
  "RetentionRecordKind",
47
+ "SharedBypassReason",
48
+ "SharedBypassReasonCount",
38
49
  "SharedCacheManager",
50
+ "SharedCacheStatistics",
39
51
  "SharedCachedCollection",
52
+ "SharedCapacityUsage",
53
+ "SharedDatabaseHealth",
54
+ "SharedOwnerSnapshot",
55
+ "SharedStreamStatus",
40
56
  "StreamCostSnapshot",
41
57
  "StreamHealthSnapshot",
42
58
  "StreamHealthStatus",