astreum 0.2.48__tar.gz → 0.2.49__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: astreum
-Version: 0.2.48
+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.48 → 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.48 → astreum-0.2.49}/pyproject.toml

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

{astreum-0.2.48 → astreum-0.2.49}/src/astreum/utils/logging.py

@@ -16,8 +16,6 @@ from typing import Any, Dict, Optional
 
 from blake3 import blake3
 
-LOG_ENV_VARS = ("ASTREUM_LOG_DIR", "YOUR_LIB_LOG_DIR")
-
 # Fixed identity for all loggers in this library
 _ORG_NAME = "Astreum"
 _PRODUCT_NAME = "lib-py"
@@ -65,12 +63,7 @@ def _derive_instance_id() -> str:
 
 
 def _log_root(org: str, product: str, instance_id: str) -> pathlib.Path:
-    """Resolve the base directory for logs, allowing an override via env vars."""
-    for env_var in LOG_ENV_VARS:
-        override = os.getenv(env_var)
-        if override:
-            return pathlib.Path(override) / org / product / "logs" / instance_id
-
+    """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
@@ -222,6 +215,5 @@ def logging_setup(config: dict) -> logging.LoggerAdapter:
 __all__ = [
     "HumanFormatter",
     "JSONFormatter",
-    "LOG_ENV_VARS",
     "logging_setup",
 ]

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: astreum
-Version: 0.2.48
+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