lmcache-cli 0.4.5.dev0__py3-none-any.whl

lmcache/v1/mp_observability/subscribers/logging/l2.py

@@ -0,0 +1,73 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""L2 storage logging subscriber — debug logs for L2 store/prefetch events."""
+
+# Future
+from __future__ import annotations
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventCallback, EventSubscriber
+
+logger = init_logger(__name__)
+
+
+class L2LoggingSubscriber(EventSubscriber):
+    """Logs L2 store and prefetch events at debug level."""
+
+    def get_subscriptions(self) -> dict[EventType, EventCallback]:
+        return {
+            EventType.L2_STORE_SUBMITTED: self._on_store_submitted,
+            EventType.L2_STORE_COMPLETED: self._on_store_completed,
+            EventType.L2_PREFETCH_LOOKUP_SUBMITTED: self._on_lookup_submitted,
+            EventType.L2_PREFETCH_LOOKUP_COMPLETED: self._on_lookup_completed,
+            EventType.L2_PREFETCH_LOAD_SUBMITTED: self._on_load_submitted,
+            EventType.L2_PREFETCH_LOAD_COMPLETED: self._on_load_completed,
+        }
+
+    def _on_store_submitted(self, event: Event) -> None:
+        logger.debug(
+            "L2 store submitted: %d keys to adapter %d",
+            event.metadata["key_count"],
+            event.metadata["adapter_index"],
+        )
+
+    def _on_store_completed(self, event: Event) -> None:
+        logger.debug(
+            "L2 store completed: adapter %d, %d succeeded, %d failed",
+            event.metadata["adapter_index"],
+            event.metadata["succeeded_count"],
+            event.metadata["failed_count"],
+        )
+
+    def _on_lookup_submitted(self, event: Event) -> None:
+        logger.debug(
+            "L2 prefetch lookup submitted: request %d, %d keys to %d adapters",
+            event.metadata["request_id"],
+            event.metadata["key_count"],
+            event.metadata["adapter_count"],
+        )
+
+    def _on_lookup_completed(self, event: Event) -> None:
+        logger.debug(
+            "L2 prefetch lookup completed: request %d, %d prefix hits",
+            event.metadata["request_id"],
+            event.metadata["prefix_hit_count"],
+        )
+
+    def _on_load_submitted(self, event: Event) -> None:
+        logger.debug(
+            "L2 prefetch load submitted: request %d, %d keys to %d adapters",
+            event.metadata["request_id"],
+            event.metadata["key_count"],
+            event.metadata["adapter_count"],
+        )
+
+    def _on_load_completed(self, event: Event) -> None:
+        logger.debug(
+            "L2 prefetch load completed: request %d, %d loaded, %d failed",
+            event.metadata["request_id"],
+            event.metadata["loaded_count"],
+            event.metadata["failed_count"],
+        )

lmcache/v1/mp_observability/subscribers/logging/lookup_hash.py

@@ -0,0 +1,209 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Lookup hash file-logging subscriber.
+
+Subscribes to ``MP_LOOKUP`` events and writes lookup hash data to
+rotating JSONL files for offline analysis.  Because the EventBus
+drain thread dispatches callbacks off the hot path, no extra queue
+or worker thread is needed — file I/O happens in the EventBus
+background thread.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+import io
+import json
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventCallback, EventSubscriber
+
+logger = init_logger(__name__)
+
+# Pattern for discovering existing log files on disk.
+_LOG_FILE_GLOB = "lookup_hashes_*.jsonl"
+
+
+def _format_timestamp(ts: float) -> str:
+    """Format a unix timestamp as a compact datetime string.
+
+    Example: 20260401_143025
+    """
+    dt = datetime.fromtimestamp(ts, tz=timezone.utc)
+    return dt.strftime("%Y%m%d_%H%M%S")
+
+
+@dataclass
+class LookupHashLogConfig:
+    """Configuration for lookup hash file logging.
+
+    When ``output_dir`` is non-empty, chunk hashes computed during
+    lookup are written to rotating JSONL files for offline analysis.
+    """
+
+    output_dir: str = ""
+    """Directory to write lookup hash JSONL files.
+    Empty string disables logging."""
+
+    rotation_interval_sec: int = 6 * 3600
+    """Time interval in seconds before rotating to a new file
+    (default 6 hours)."""
+
+    rotation_max_size: int = 100 * 1024 * 1024
+    """Max file size in bytes before rotating even if the time
+    interval has not elapsed (default 100MB)."""
+
+    max_files: int = 100
+    """Max number of log files to keep before deleting oldest."""
+
+    @property
+    def enabled(self) -> bool:
+        """Whether lookup hash logging is enabled."""
+        return bool(self.output_dir)
+
+
+class LookupHashLoggingSubscriber(EventSubscriber):
+    """EventBus subscriber that writes lookup hashes to rotating JSONL files.
+
+    Leverages the EventBus drain thread for async I/O instead of maintaining
+    its own queue and worker.
+
+    Files rotate when either the time interval or file size limit is
+    reached, whichever comes first.  File names include a
+    human-readable timestamp, e.g.::
+
+        lookup_hashes_20260401_143025_000003.jsonl
+
+    Each JSONL line has the format::
+
+        {"timestamp": 1711929600.123, "request_id": "req-abc",
+         "model_name": "DeepSeek-V3",
+         "chunk_size": 256, "seq_len": 1024,
+         "dtypes": ["float8_e4m3fn"],
+         "shapes": [[32, 256, 128]],
+         "chunk_hashes": ["0xab...", ...]}
+    """
+
+    def __init__(self, config: LookupHashLogConfig) -> None:
+        self._config = config
+        self.output_dir = Path(config.output_dir)
+        self.output_dir.mkdir(parents=True, exist_ok=True)
+
+        # File state (only accessed from the EventBus drain thread)
+        self._current_file_size: int = 0
+        self._current_file: Optional[Path] = None
+        self._current_handle: Optional[io.TextIOWrapper] = None
+        self._current_file_opened_at: float = 0.0
+
+        # Discover existing log files so max_files limit accounts
+        # for files from previous runs.
+        self._file_list: list[Path] = sorted(
+            self.output_dir.glob(_LOG_FILE_GLOB),
+            key=lambda p: p.stat().st_mtime,
+        )
+        self._file_count: int = len(self._file_list)
+
+        logger.info(
+            "LookupHashLoggingSubscriber started: output_dir=%s, "
+            "rotation_interval=%ds, "
+            "rotation_max_size=%d, max_files=%d, "
+            "existing_files=%d",
+            self.output_dir,
+            config.rotation_interval_sec,
+            config.rotation_max_size,
+            config.max_files,
+            len(self._file_list),
+        )
+
+    # -- EventSubscriber interface -----------------------------------------
+
+    def get_subscriptions(self) -> dict[EventType, EventCallback]:
+        return {
+            EventType.MP_LOOKUP: self._on_lookup_hashes,
+        }
+
+    def shutdown(self) -> None:
+        """Close the current file handle on EventBus shutdown."""
+        if self._current_handle is not None:
+            self._current_handle.close()
+            self._current_handle = None
+        logger.info("LookupHashLoggingSubscriber closed")
+
+    # -- Callback ----------------------------------------------------------
+
+    def _on_lookup_hashes(self, event: Event) -> None:
+        """Write a lookup hash event to the current JSONL file."""
+        meta = event.metadata
+        timestamp = event.timestamp
+
+        if self._needs_rotation(timestamp):
+            self._rotate_file(timestamp)
+
+        chunk_hashes_raw = meta.get("chunk_hashes", [])
+        data = {
+            "timestamp": timestamp,
+            "request_id": meta.get("request_id", ""),
+            "model_name": meta.get("model_name", ""),
+            "chunk_size": meta.get("chunk_size", 0),
+            "seq_len": meta.get("seq_len", 0),
+            "dtypes": meta.get("dtypes", []),
+            "shapes": meta.get("shapes", []),
+            "chunk_hashes": [
+                "0x" + h.hex() if isinstance(h, bytes) else hex(h)
+                for h in chunk_hashes_raw
+            ],
+        }
+        line = json.dumps(data) + "\n"
+        if self._current_handle is not None:
+            self._current_handle.write(line)
+            self._current_handle.flush()
+            self._current_file_size = self._current_handle.tell()
+
+    # -- File rotation -----------------------------------------------------
+
+    def _needs_rotation(self, now: float) -> bool:
+        """Check if the current file needs rotation."""
+        if self._current_handle is None:
+            return True
+        elapsed = now - self._current_file_opened_at
+        if elapsed >= self._config.rotation_interval_sec:
+            return True
+        if self._current_file_size >= self._config.rotation_max_size:
+            return True
+        return False
+
+    def _rotate_file(self, now: float) -> None:
+        """Close current file and open a new one."""
+        if self._current_handle is not None:
+            self._current_handle.close()
+            self._current_handle = None
+
+        time_str = _format_timestamp(now)
+        self._current_file = (
+            self.output_dir / f"lookup_hashes_{time_str}_{self._file_count:06d}.jsonl"
+        )
+        self._current_handle = open(self._current_file, "w", encoding="utf-8")
+        self._current_file_opened_at = now
+        self._current_file_size = 0
+        self._file_count += 1
+        self._file_list.append(self._current_file)
+
+        # Enforce max file count
+        while len(self._file_list) > self._config.max_files:
+            oldest = self._file_list.pop(0)
+            try:
+                if oldest.exists():
+                    oldest.unlink()
+            except Exception as e:
+                logger.error(
+                    "Failed to delete old lookup hash file %s: %s",
+                    oldest,
+                    e,
+                )

lmcache/v1/mp_observability/subscribers/logging/mp_server.py

@@ -0,0 +1,90 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""MP Server logging subscriber — debug logs for store/retrieve/lookup events.
+
+Logs are emitted via Python's standard logging module.  When OpenTelemetry
+is installed, ``init_logger`` automatically attaches an OTel
+``LoggingHandler`` so records are forwarded to OTel when a
+``LoggerProvider`` is configured at startup.
+"""
+
+# Future
+from __future__ import annotations
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventCallback, EventSubscriber
+
+logger = init_logger(__name__)
+
+
+class MPServerLoggingSubscriber(EventSubscriber):
+    """Logs MP server store/retrieve/lookup events at debug level."""
+
+    def get_subscriptions(self) -> dict[EventType, EventCallback]:
+        return {
+            EventType.MP_STORE_START: self._on_store_start,
+            EventType.MP_STORE_END: self._on_store_end,
+            EventType.MP_RETRIEVE_START: self._on_retrieve_start,
+            EventType.MP_RETRIEVE_END: self._on_retrieve_end,
+            EventType.MP_LOOKUP_PREFETCH_START: self._on_lookup_prefetch_start,
+            EventType.MP_LOOKUP_PREFETCH_END: self._on_lookup_prefetch_end,
+            EventType.MP_VLLM_BLOCK_ALLOCATION: self._on_block_allocation,
+        }
+
+    def _on_store_start(self, event: Event) -> None:
+        logger.debug(
+            "MP store start: session=%s device=%s",
+            event.session_id,
+            event.metadata.get("device"),
+        )
+
+    def _on_store_end(self, event: Event) -> None:
+        logger.debug(
+            "MP store end: session=%s device=%s stored_count=%s",
+            event.session_id,
+            event.metadata.get("device"),
+            event.metadata.get("stored_count"),
+        )
+
+    def _on_retrieve_start(self, event: Event) -> None:
+        logger.debug(
+            "MP retrieve start: session=%s device=%s",
+            event.session_id,
+            event.metadata.get("device"),
+        )
+
+    def _on_retrieve_end(self, event: Event) -> None:
+        logger.debug(
+            "MP retrieve end: session=%s device=%s retrieved_count=%s",
+            event.session_id,
+            event.metadata.get("device"),
+            event.metadata.get("retrieved_count"),
+        )
+
+    def _on_lookup_prefetch_start(self, event: Event) -> None:
+        logger.debug(
+            "MP lookup/prefetch start: session=%s",
+            event.session_id,
+        )
+
+    def _on_lookup_prefetch_end(self, event: Event) -> None:
+        logger.debug(
+            "MP lookup/prefetch end: session=%s found_count=%s",
+            event.session_id,
+            event.metadata.get("found_count"),
+        )
+
+    def _on_block_allocation(self, event: Event) -> None:
+        records = event.metadata.get("records", [])
+        for rec in records:
+            logger.debug(
+                "vLLM block allocation: req_id=%s "
+                "new_blocks=%d new_tokens=%d "
+                "block_ids=%s",
+                rec.req_id,
+                len(rec.new_block_ids),
+                len(rec.new_token_ids),
+                rec.new_block_ids[:10],
+            )

lmcache/v1/mp_observability/subscribers/logging/sm.py

@@ -0,0 +1,59 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""StorageManager logging subscriber — debug logs for SM events.
+
+Logs are emitted via Python's standard logging module.  When OpenTelemetry
+is installed, ``init_logger`` automatically attaches an OTel
+``LoggingHandler`` so records are forwarded to OTel when a
+``LoggerProvider`` is configured at startup.
+"""
+
+# Future
+from __future__ import annotations
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventCallback, EventSubscriber
+
+logger = init_logger(__name__)
+
+
+class SMLoggingSubscriber(EventSubscriber):
+    """Logs StorageManager events at debug level."""
+
+    def get_subscriptions(self) -> dict[EventType, EventCallback]:
+        return {
+            EventType.SM_READ_PREFETCHED: self._on_read_prefetched,
+            EventType.SM_READ_PREFETCHED_FINISHED: self._on_read_prefetched_finished,
+            EventType.SM_WRITE_RESERVED: self._on_write_reserved,
+            EventType.SM_WRITE_FINISHED: self._on_write_finished,
+        }
+
+    def _on_read_prefetched(self, event: Event) -> None:
+        logger.debug(
+            "SM read prefetched: %d succeeded, %d failed",
+            len(event.metadata["succeeded_keys"]),
+            len(event.metadata["failed_keys"]),
+        )
+
+    def _on_read_prefetched_finished(self, event: Event) -> None:
+        logger.debug(
+            "SM read prefetched finished: %d succeeded, %d failed",
+            len(event.metadata["succeeded_keys"]),
+            len(event.metadata["failed_keys"]),
+        )
+
+    def _on_write_reserved(self, event: Event) -> None:
+        logger.debug(
+            "SM write reserved: %d succeeded, %d failed",
+            len(event.metadata["succeeded_keys"]),
+            len(event.metadata["failed_keys"]),
+        )
+
+    def _on_write_finished(self, event: Event) -> None:
+        logger.debug(
+            "SM write finished: %d succeeded, %d failed",
+            len(event.metadata["succeeded_keys"]),
+            len(event.metadata["failed_keys"]),
+        )

lmcache/v1/mp_observability/subscribers/metrics/__init__.py

@@ -0,0 +1,20 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# First Party
+from lmcache.v1.mp_observability.subscribers.metrics.l0_lifecycle import (
+    L0LifecycleSubscriber,
+)
+from lmcache.v1.mp_observability.subscribers.metrics.l1 import L1MetricsSubscriber
+from lmcache.v1.mp_observability.subscribers.metrics.l1_lifecycle import (
+    L1LifecycleSubscriber,
+)
+from lmcache.v1.mp_observability.subscribers.metrics.l2 import L2MetricsSubscriber
+from lmcache.v1.mp_observability.subscribers.metrics.sm import SMMetricsSubscriber
+
+__all__ = [
+    "L0LifecycleSubscriber",
+    "L1LifecycleSubscriber",
+    "L1MetricsSubscriber",
+    "L2MetricsSubscriber",
+    "SMMetricsSubscriber",
+]