astreum 0.2.47__tar.gz → 0.2.49__tar.gz

{astreum-0.2.47/src/astreum.egg-info → astreum-0.2.49}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: astreum
-Version: 0.2.47
+Version: 0.2.49
 Summary: Python library to interact with the Astreum blockchain and its Lispeum virtual machine.
 Author-email: "Roy R. O. Okello" <roy@stelar.xyz>
 Project-URL: Homepage, https://github.com/astreum/lib
@@ -35,6 +35,8 @@ When initializing an `astreum.Node`, pass a dictionary with any of the options b
 | `validation_secret_key`     | hex string | `None`         | X25519 private key that lets the node participate in the validation route. Leave unset for a non‑validator node.                                                                 |
 | `storage_path`              | string     | `None`         | Directory where objects are persisted. If *None*, the node uses an in‑memory store.                                                                                              |
 | `storage_get_relay_timeout` | float      | `5`            | Seconds to wait for an object requested from peers before timing‑out.                                                                                                            |
+| `logging_retention`         | int        | `90`           | Number of days to keep rotated log files (daily gzip).                                                                                                                           |
+| `verbose`                   | bool       | `False`        | When **True**, also mirror JSON logs to stdout with a human-readable format.                                                                                                     |
 
 ### Networking
 
@@ -136,6 +138,17 @@ except ParseError as e:
 
 ---
 
+
+## Logging
+
+Every `Node` instance wires up structured logging automatically:
+
+- Logs land in per-instance files named `node.log` under `%LOCALAPPDATA%\Astreum\lib-py\logs/<instance_id>` on Windows and `$XDG_STATE_HOME` (or `~/.local/state`)/`Astreum/lib-py/logs/<instance_id>` on other platforms. The `<instance_id>` is the first 16 hex characters of a BLAKE3 hash of the caller's file path, so running the node from different entry points keeps their logs isolated.
+- Files rotate at midnight UTC with gzip compression (`node-YYYY-MM-DD.log.gz`) and retain 90 days by default. Override via `config["logging_retention"]`.
+- Each event is a single JSON line containing timestamp, level, logger, message, process/thread info, module/function, and the derived `instance_id`.
+- Set `config["verbose"] = True` to mirror logs to stdout in a human-friendly format like `[2025-04-13-42-59] [info] Starting Astreum Node`.
+- The very first entry emitted is the banner `Starting Astreum Node`, signalling that the logging pipeline is live before other subsystems spin up.
+
 ## Testing
 
 ```bash

{astreum-0.2.47 → astreum-0.2.49}/README.md

@@ -17,6 +17,8 @@ When initializing an `astreum.Node`, pass a dictionary with any of the options b
 | `validation_secret_key`     | hex string | `None`         | X25519 private key that lets the node participate in the validation route. Leave unset for a non‑validator node.                                                                 |
 | `storage_path`              | string     | `None`         | Directory where objects are persisted. If *None*, the node uses an in‑memory store.                                                                                              |
 | `storage_get_relay_timeout` | float      | `5`            | Seconds to wait for an object requested from peers before timing‑out.                                                                                                            |
+| `logging_retention`         | int        | `90`           | Number of days to keep rotated log files (daily gzip).                                                                                                                           |
+| `verbose`                   | bool       | `False`        | When **True**, also mirror JSON logs to stdout with a human-readable format.                                                                                                     |
 
 ### Networking
 
@@ -118,6 +120,17 @@ except ParseError as e:
 
 ---
 
+
+## Logging
+
+Every `Node` instance wires up structured logging automatically:
+
+- Logs land in per-instance files named `node.log` under `%LOCALAPPDATA%\Astreum\lib-py\logs/<instance_id>` on Windows and `$XDG_STATE_HOME` (or `~/.local/state`)/`Astreum/lib-py/logs/<instance_id>` on other platforms. The `<instance_id>` is the first 16 hex characters of a BLAKE3 hash of the caller's file path, so running the node from different entry points keeps their logs isolated.
+- Files rotate at midnight UTC with gzip compression (`node-YYYY-MM-DD.log.gz`) and retain 90 days by default. Override via `config["logging_retention"]`.
+- Each event is a single JSON line containing timestamp, level, logger, message, process/thread info, module/function, and the derived `instance_id`.
+- Set `config["verbose"] = True` to mirror logs to stdout in a human-friendly format like `[2025-04-13-42-59] [info] Starting Astreum Node`.
+- The very first entry emitted is the banner `Starting Astreum Node`, signalling that the logging pipeline is live before other subsystems spin up.
+
 ## Testing
 
 ```bash

{astreum-0.2.47 → astreum-0.2.49}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "astreum"
-version = "0.2.47"
+version = "0.2.49"
 authors = [
   { name="Roy R. O. Okello", email="roy@stelar.xyz" },
 ]

{astreum-0.2.47 → astreum-0.2.49}/src/astreum/_node.py

@@ -3,24 +3,27 @@ from typing import Dict, Optional
 import uuid
 import threading
 
-from ._storage.atom import Atom
-from ._lispeum import Env, Expr, Meter, low_eval, parse, tokenize, ParseError
-
-__all__ = [
-    "Node",
-    "Env",
-    "Expr",
-    "Meter",
-    "parse",
-    "tokenize",
-]
-
-def bytes_touched(*vals: bytes) -> int:
+from ._storage.atom import Atom
+from ._lispeum import Env, Expr, Meter, low_eval, parse, tokenize, ParseError
+from .utils.logging import logging_setup
+
+__all__ = [
+    "Node",
+    "Env",
+    "Expr",
+    "Meter",
+    "parse",
+    "tokenize",
+]
+
+def bytes_touched(*vals: bytes) -> int:
     """For metering: how many bytes were manipulated (max of operands)."""
     return max((len(v) for v in vals), default=1)
 
 class Node:
     def __init__(self, config: dict):
+        self.logger = logging_setup(config)
+        self.logger.info("Starting Astreum Node")
         # Storage Setup
         self.in_memory_storage: Dict[bytes, Atom] = {}
         self.in_memory_storage_lock = threading.RLock()

astreum-0.2.49/src/astreum/utils/logging.py

@@ -0,0 +1,219 @@
+from __future__ import annotations
+
+import atexit
+import inspect
+import gzip
+import json
+import logging
+import logging.handlers
+import os
+import pathlib
+import platform
+import queue
+import shutil
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional
+
+from blake3 import blake3
+
+# Fixed identity for all loggers in this library
+_ORG_NAME = "Astreum"
+_PRODUCT_NAME = "lib-py"
+
+
+def _safe_path(path_str: str) -> Optional[pathlib.Path]:
+    try:
+        return pathlib.Path(path_str).resolve()
+    except Exception:
+        try:
+            return pathlib.Path(path_str).absolute()
+        except Exception:
+            return None
+
+
+def _hash_path(path: pathlib.Path) -> str:
+    try:
+        data = str(path).encode("utf-8", errors="ignore")
+    except Exception:
+        data = repr(path).encode("utf-8", errors="ignore")
+    return blake3(data).hexdigest()
+
+
+def _find_caller_path() -> pathlib.Path:
+    stack = inspect.stack()
+    candidates: list[pathlib.Path] = []
+    for frame_info in stack[2:]:
+        filename = frame_info.filename
+        if not filename:
+            continue
+        path = _safe_path(filename)
+        if path is None:
+            continue
+        candidates.append(path)
+        if "astreum" not in path.parts:
+            return path
+
+    if candidates:
+        return candidates[0]
+    return pathlib.Path.cwd()
+
+
+def _derive_instance_id() -> str:
+    return _hash_path(_find_caller_path())[:16]
+
+
+def _log_root(org: str, product: str, instance_id: str) -> pathlib.Path:
+    """Resolve the base directory for logs using platform defaults."""
+    if platform.system() == "Windows":
+        base = os.getenv("LOCALAPPDATA") or str(pathlib.Path.home())
+        return pathlib.Path(base) / org / product / "logs" / instance_id
+
+    xdg_state = os.getenv("XDG_STATE_HOME")
+    base_path = pathlib.Path(xdg_state) if xdg_state else pathlib.Path.home() / ".local" / "state"
+    return base_path / org / product / "logs" / instance_id
+
+
+class JSONFormatter(logging.Formatter):
+    """Log record formatter that emits JSON objects per line."""
+
+    def format(self, record: logging.LogRecord) -> str:  # type: ignore[override]
+        payload: Dict[str, Any] = {
+            "ts": datetime.fromtimestamp(record.created, tz=timezone.utc).isoformat(),
+            "level": record.levelname,
+            "logger": record.name,
+            "msg": record.getMessage(),
+            "pid": record.process,
+            "thread": record.threadName,
+            "module": record.module,
+            "func": record.funcName,
+            "instance_id": getattr(record, "instance_id", None),
+        }
+
+        for key, value in record.__dict__.items():
+            if key in payload or key.startswith(("_", "msecs", "relativeCreated")):
+                continue
+            try:
+                json.dumps(value)
+            except Exception:
+                continue
+            payload[key] = value
+
+        return json.dumps(payload, ensure_ascii=False)
+
+
+def _gzip_rotator(src: str, dst: str) -> None:
+    """Rotate the log file by gzipping it and removing the original."""
+    with open(src, "rb") as source, gzip.open(f"{dst}.gz", "wb") as target:
+        shutil.copyfileobj(source, target)
+    os.remove(src)
+
+
+def _namer(default_name: str) -> str:
+    """Custom name for rotated logs: node-YYYY-MM-DD.log."""
+    path = pathlib.Path(default_name)
+    parent = path.parent
+    name = path.name
+    fragments = name.split(".log.")
+    if len(fragments) != 2:
+        return default_name
+    stem, date_part = fragments
+    return str(parent / f"{stem}-{date_part}.log")
+
+
+def _human_line(record: logging.LogRecord) -> str:
+    """Format a record as a concise human-readable line."""
+    dt = datetime.fromtimestamp(record.created, tz=timezone.utc)
+    stamp = f"{dt:%Y-%m-%d}-{dt:%S}-{dt:%M}"
+    return f"[{stamp}] [{record.levelname.lower()}] {record.getMessage()}"
+
+
+class HumanFormatter(logging.Formatter):
+    """Simple formatter for optional verbose console output."""
+
+    def format(self, record: logging.LogRecord) -> str:  # type: ignore[override]
+        return _human_line(record)
+
+
+def _shutdown_listener(listener: logging.handlers.QueueListener, handlers: list[logging.Handler]) -> None:
+    """Stop the queue listener and close handlers on interpreter exit."""
+    try:
+        listener.stop()
+    except Exception:
+        pass
+    finally:
+        for handler in handlers:
+            try:
+                handler.close()
+            except Exception:
+                pass
+
+
+def logging_setup(config: dict) -> logging.LoggerAdapter:
+    """Configure logging according to the runtime config and return an adapter."""
+    if config is None:
+        config = {}
+    elif not isinstance(config, dict):
+        config = dict(config)
+
+    org = _ORG_NAME
+    product = _PRODUCT_NAME
+    instance_id = _derive_instance_id()
+
+    retention_value = config.get("retention_days")
+    retention_days = int(retention_value) if retention_value is not None else 90
+
+    verbose = bool(config.get("verbose", False))
+
+    log_dir = _log_root(org, product, instance_id)
+    log_dir.mkdir(parents=True, exist_ok=True)
+
+    base_file = log_dir / "node.log"
+    file_handler = logging.handlers.TimedRotatingFileHandler(
+        filename=str(base_file),
+        when="midnight",
+        interval=1,
+        backupCount=max(retention_days, 0),
+        utc=True,
+        encoding="utf-8",
+        delay=True,
+    )
+    file_handler.setFormatter(JSONFormatter())
+    file_handler.rotator = _gzip_rotator
+    file_handler.namer = _namer
+
+    handler_list: list[logging.Handler] = [file_handler]
+
+    if verbose:
+        console_handler = logging.StreamHandler()
+        console_handler.setLevel(logging.INFO)
+        console_handler.setFormatter(HumanFormatter())
+        handler_list.append(console_handler)
+
+    log_queue: queue.Queue[logging.LogRecord] = queue.Queue(-1)
+    queue_handler = logging.handlers.QueueHandler(log_queue)
+
+    base_logger = logging.getLogger(f"{product}.{instance_id}")
+    base_logger.setLevel(logging.INFO)
+    base_logger.handlers.clear()
+    base_logger.propagate = False
+    base_logger.addHandler(queue_handler)
+
+    listener = logging.handlers.QueueListener(
+        log_queue, *handler_list, respect_handler_level=True
+    )
+    listener.daemon = True
+    listener.start()
+    atexit.register(_shutdown_listener, listener, handler_list)
+
+    adapter = logging.LoggerAdapter(base_logger, {"instance_id": instance_id})
+    setattr(adapter, "_queue_listener", listener)
+    setattr(adapter, "_handlers", handler_list)
+
+    return adapter
+
+
+__all__ = [
+    "HumanFormatter",
+    "JSONFormatter",
+    "logging_setup",
+]

{astreum-0.2.47 → astreum-0.2.49/src/astreum.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: astreum
-Version: 0.2.47
+Version: 0.2.49
 Summary: Python library to interact with the Astreum blockchain and its Lispeum virtual machine.
 Author-email: "Roy R. O. Okello" <roy@stelar.xyz>
 Project-URL: Homepage, https://github.com/astreum/lib
@@ -35,6 +35,8 @@ When initializing an `astreum.Node`, pass a dictionary with any of the options b
 | `validation_secret_key`     | hex string | `None`         | X25519 private key that lets the node participate in the validation route. Leave unset for a non‑validator node.                                                                 |
 | `storage_path`              | string     | `None`         | Directory where objects are persisted. If *None*, the node uses an in‑memory store.                                                                                              |
 | `storage_get_relay_timeout` | float      | `5`            | Seconds to wait for an object requested from peers before timing‑out.                                                                                                            |
+| `logging_retention`         | int        | `90`           | Number of days to keep rotated log files (daily gzip).                                                                                                                           |
+| `verbose`                   | bool       | `False`        | When **True**, also mirror JSON logs to stdout with a human-readable format.                                                                                                     |
 
 ### Networking
 
@@ -136,6 +138,17 @@ except ParseError as e:
 
 ---
 
+
+## Logging
+
+Every `Node` instance wires up structured logging automatically:
+
+- Logs land in per-instance files named `node.log` under `%LOCALAPPDATA%\Astreum\lib-py\logs/<instance_id>` on Windows and `$XDG_STATE_HOME` (or `~/.local/state`)/`Astreum/lib-py/logs/<instance_id>` on other platforms. The `<instance_id>` is the first 16 hex characters of a BLAKE3 hash of the caller's file path, so running the node from different entry points keeps their logs isolated.
+- Files rotate at midnight UTC with gzip compression (`node-YYYY-MM-DD.log.gz`) and retain 90 days by default. Override via `config["logging_retention"]`.
+- Each event is a single JSON line containing timestamp, level, logger, message, process/thread info, module/function, and the derived `instance_id`.
+- Set `config["verbose"] = True` to mirror logs to stdout in a human-friendly format like `[2025-04-13-42-59] [info] Starting Astreum Node`.
+- The very first entry emitted is the banner `Starting Astreum Node`, signalling that the logging pipeline is live before other subsystems spin up.
+
 ## Testing
 
 ```bash

{astreum-0.2.47 → astreum-0.2.49}/src/astreum.egg-info/SOURCES.txt

@@ -55,4 +55,5 @@ src/astreum/storage/__init__.py
 src/astreum/storage/object.py
 src/astreum/storage/setup.py
 src/astreum/utils/bytes.py
-src/astreum/utils/integer.py
+src/astreum/utils/integer.py
+src/astreum/utils/logging.py