diff --git a/README.md b/README.md index 1ce6fdc..380ec14 100644 --- a/README.md +++ b/README.md @@ -13,12 +13,12 @@ and emit; their records flow into the handlers `log_setup` wired. ## Install ``` -log_setup @ git+ssh://git@git.rethinkstudios.io/rethink-public/log_setup.git@v0.4.3 +log_setup @ git+ssh://git@git.rethinkstudios.io/rethink-public/log_setup.git@v0.5.0 ``` No dependencies — stdlib only. -Drop the `@v0.4.3` suffix from the line above to install the latest unpinned. +Drop the `@v0.5.0` suffix from the line above to install the latest unpinned. ## Quick start @@ -43,14 +43,14 @@ emits; the records land in the configured root. - **Format:** `2026-06-27 19:55:05 | module.name | INFO | message`. `%(name)s` is the `getLogger` name each module used, so you see which lib/module logged. - **Rotation** (`rotate=`): - - `"daily"` (default) — rolls at midnight, dated name into `log_dir`, keeps - `backup_count` days. - - `"size"` — rolls at `max_bytes`; numbered backups (`run.log.1`, `.2`, …) in `log_dir` - for the default flat retention, or timestamped names when tiered retention is on (below). - - `"on_start"` — on startup, moves an existing `run.log` into `log_dir` - (`run..log[.gz]`) and starts fresh; prunes to `backup_count`. + - `"daily"` (default) — rolls at midnight into `log_dir`, keeps `backup_count` days. + - `"size"` — rolls at `max_bytes` into `log_dir`, keeps `backup_count`. + - `"on_start"` — on startup, moves an existing live file into `log_dir` and starts fresh; + prunes to `backup_count`. - `None` — single file, no rotation. -- **compress=True** (default) gzips each rolled file (`run.log.2026-06-27.gz`). +- **Historic files are named off the project** — see below. Every rolled file is + `..log[.gz]`; the live file keeps its own name. +- **compress=True** (default) gzips each rolled file. - **Retention** = `backup_count` (default 14) for every mode — unless tiered retention is enabled (below). - **console=True** (off by default) also logs to stdout in the same format — opt in when @@ -59,6 +59,28 @@ emits; the records land in the configured root. The `name` you pass is normalized so it produces exactly one `.log`: `name="latest"` and `name="latest.log"` both yield the live file `latest.log` (never `latest.log.log`). +## Historic files are named off the project (`history_name`) + +The **live** file keeps its defined `name` (`latest.log`). The **historic** (rolled/gz) +files are named off the **project namespace** — by default the current directory's basename +— so you can tell at a glance which service a log came from: + +```python +# app run from bestbuy/run.py , with name="latest": +setup_logging(name="latest", rotate="daily") +# logs/ +# latest.log <- live (the tail -f target) +# bestbuy.2026-07-01_02-00-00.log <- historic, named off the project dir +# bestbuy.2026-06-30_02-00-00.log.gz +``` + +- **Default** = `os.path.basename(os.getcwd())` (the project directory). Zero config. +- Override with **`history_name="foo"`** → historic files become `foo..log[.gz]`. +- This changed in **v0.5.0**: historic files used to reuse the live `name`. To keep the old + behavior, pass `history_name=name`. +- Retention (tier counts / `backup_count`) is unchanged — it's just keyed to the project + stem now. + ## Tiered retention (`keep_uncompressed` / `keep_compressed`) The default is a flat `backup_count`: every rolled file is gzipped on roll and the oldest @@ -134,6 +156,7 @@ setup_logging( level="INFO", # root level everything inherits (str name or logging constant) module_levels=None, # {logger_name: level} per-logger overrides (exact name match) rotate="daily", # "daily" | "size" | "on_start" | None + history_name=None, # stem for rolled/historic files; None -> cwd basename (project) backup_count=14, # rotated files to keep (flat retention; ignored if tiered) keep_uncompressed=None, # tiered: newest N rolled logs kept PLAIN (opt-in) keep_compressed=None, # tiered: next M rolled logs kept GZIPPED (opt-in) diff --git a/pyproject.toml b/pyproject.toml index db57c03..6f05c36 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "hatchling.build" [project] name = "log_setup" -version = "0.4.3" +version = "0.5.0" description = "stdlib app-entry-point logging setup: live run.log, rotation, gzip, retention, consistent format" requires-python = ">=3.10" dependencies = [] diff --git a/src/log_setup/__init__.py b/src/log_setup/__init__.py index 8a961d8..0c624c7 100644 --- a/src/log_setup/__init__.py +++ b/src/log_setup/__init__.py @@ -19,4 +19,4 @@ from .setup import setup_logging __all__ = ["setup_logging"] -__version__ = "0.4.3" +__version__ = "0.5.0" diff --git a/src/log_setup/rotation.py b/src/log_setup/rotation.py index f28f1a1..958b6a8 100644 --- a/src/log_setup/rotation.py +++ b/src/log_setup/rotation.py @@ -80,27 +80,32 @@ def make_namer(log_dir: str, compress: bool) -> Callable[[str], str]: return namer -def make_size_namer( - stem: str, log_dir: str, clock=time.localtime, +def make_history_namer( + stem: str, log_dir: str, compress: bool = False, plain: bool = False, + clock=time.localtime, ) -> Callable[[str], str]: - """namer for tiered SIZE mode: a unique timestamped dest per roll, plain (no .gz) + """namer minting historic rolled files `..log[.gz]` in log_dir - stdlib RotatingFileHandler names rolls `.1`, `.2`, ... and shifts them — - a scheme that breaks once files are redirected into log_dir (the shift can't find - them, so every roll reuses slot 1). tiered retention wants unique per-roll names it - can rank + tier like the daily/on_start paths, so ignore the handler's `.N` suffix - entirely and mint `..log`, disambiguating a same-second collision - (against both the .log and .log.gz forms) with a counter. always plain — retier - decides compression. + used by size and daily (and their tiered variants). `stem` is the HISTORY stem (the + project namespace), independent of the live file's name — the returned rolled files + are keyed off it, and prune/retier glob the same stem. + + the stdlib handler's own rolled name (`.N` for size, `.log.` for daily) is + ignored — we mint our own uniform timestamped name so all modes converge on one shape + and retier can rank/tier them. `plain=True` (tiered mode) always lands `.log` and lets + retier decide compression; otherwise `.gz` is appended when `compress`. same-second + collisions are disambiguated with a counter, checking both .log and .log.gz forms. """ def namer(default_name: str) -> str: stamp = time.strftime("%Y-%m-%d_%H-%M-%S", clock()) - dest = os.path.join(log_dir, f"{stem}.{stamp}.log") + base = os.path.join(log_dir, f"{stem}.{stamp}") + candidate = base counter = 1 - while os.path.exists(dest) or os.path.exists(dest + ".gz"): - dest = os.path.join(log_dir, f"{stem}.{stamp}.{counter}.log") + while os.path.exists(candidate + ".log") or os.path.exists(candidate + ".log.gz"): + candidate = f"{base}.{counter}" counter += 1 - return dest + suffix = ".log.gz" if (compress and not plain) else ".log" + return candidate + suffix return namer @@ -150,9 +155,14 @@ def make_rotator( def rotate_on_start( live_path: str, log_dir: str, compress: bool, clock=time.localtime, keep_uncompressed: Optional[int] = None, keep_compressed: Optional[int] = None, + history_stem: Optional[str] = None, ) -> None: """move an existing live file into log_dir with a timestamp, gzipped if asked + the rolled file is named off `history_stem` (the project namespace) when given, so + historic files carry the project name independent of the live file's stem; falls back + to the live file's own stem when history_stem is None/empty. + no-op if the live file doesn't exist. used by rotate="on_start" before the fresh handler opens a new live file. the timestamp form is run.<%Y-%m-%d_%H-%M-%S>.log. @@ -164,7 +174,8 @@ def rotate_on_start( if not os.path.exists(live_path): return tiered = keep_uncompressed is not None or keep_compressed is not None - stem = os.path.splitext(os.path.basename(live_path))[0] + live_stem = os.path.splitext(os.path.basename(live_path))[0] + stem = os.path.basename(history_stem) if history_stem else live_stem stamp = time.strftime("%Y-%m-%d_%H-%M-%S", clock()) suffix = ".log.gz" if (compress and not tiered) else ".log" # the stamp is 1-second resolution; two starts in the same second would collide @@ -322,24 +333,24 @@ def attach_rolling( handler, log_dir: str, compress: bool, prune_stem: Optional[str] = None, backup_count: int = 0, keep_uncompressed: Optional[int] = None, keep_compressed: Optional[int] = None, - size_tiered: bool = False, + tiered: bool = False, ) -> Tuple[Callable, Callable]: """wire the custom namer + rotator onto a rotating handler; return them - pass `prune_stem`/`backup_count` so the rotator prunes `log_dir` after each roll - (the handler's own retention can't see the redirected rolled files). pass - `keep_uncompressed`/`keep_compressed` instead to use tiered retention (newest plain, - next gzipped, rest deleted) — see make_rotator. + rolled files are named off `prune_stem` (the HISTORY stem — the project namespace), + independent of the live file name, via make_history_namer: `..log[.gz]` + uniform across size and daily. this replaces the stdlib handler's own rolled-name + scheme (`.N` for size, `.log.` for daily), which can't inject a project stem and + (for size) can't be managed once files are redirected into log_dir. - `size_tiered` uses a timestamped per-roll namer (make_size_namer) instead of the - default one, for a tiered RotatingFileHandler (size mode): stdlib's `.1/.2` numbered - shift can't manage files redirected into log_dir, so each roll gets a unique dated - name that retier ranks/tiers like the daily/on_start paths. + pass `prune_stem`/`backup_count` so the rotator prunes `log_dir` after each roll (the + handler's own retention can't see the redirected rolled files). pass + `keep_uncompressed`/`keep_compressed` for tiered retention (newest plain, next gzipped, + rest deleted) — see make_rotator. `tiered=True` lands rolls plain (retier compresses). """ - if size_tiered: - namer = make_size_namer(os.path.basename(prune_stem or ""), log_dir) - else: - namer = make_namer(log_dir, compress) + namer = make_history_namer( + os.path.basename(prune_stem or ""), log_dir, compress, plain=tiered, + ) rotator = make_rotator( compress, log_dir, prune_stem, backup_count, keep_uncompressed, keep_compressed, ) diff --git a/src/log_setup/setup.py b/src/log_setup/setup.py index 22d2900..b4a8bf3 100644 --- a/src/log_setup/setup.py +++ b/src/log_setup/setup.py @@ -120,45 +120,64 @@ def _normalize_name(name: str) -> str: return name +def _history_stem() -> str: + """the project namespace for historic files: the cwd basename + + a service run from bestbuy/ gives historic files bestbuy..log[.gz]. falls back + to an empty string only for a degenerate cwd (e.g. "/"), which the caller resolves to + the live stem. + """ + try: + return os.path.basename(os.getcwd().rstrip(os.sep)) + except OSError: + return "" + + def _file_handler( - name: str, live_path: str, log_dir: str, rotate: Optional[str], + name: str, history_stem: str, live_path: str, log_dir: str, rotate: Optional[str], backup_count: int, max_bytes: int, compress: bool, keep_uncompressed: Optional[int], keep_compressed: Optional[int], ) -> logging.Handler: - """build the configured file handler with custom rolling into log_dir""" + """build the configured file handler with custom rolling into log_dir + + `name` is the LIVE stem (drives live_path); `history_stem` is the PROJECT stem that + rolled/historic files are named off + the retention glob keys on. they are decoupled: + the live file keeps its defined name, historic files carry the project namespace. + """ tiered = keep_uncompressed is not None or keep_compressed is not None if rotate == "size": # stdlib doRollover is a no-op when backupCount == 0, and its numbered .1/.2 shift - # can't manage files redirected into log_dir. in tiered size mode force a nonzero - # backupCount so the roll always fires (retier bounds retention, not backupCount) - # and use the timestamped size-namer (size_tiered) instead of the .N shift. + # can't manage files redirected into log_dir. force a nonzero backupCount so the + # roll always fires, and let attach_rolling's history namer name + retier/prune + # bound retention (keyed to history_stem). size_backup = backup_count if not tiered else max(backup_count, 1) handler = logging.handlers.RotatingFileHandler( live_path, maxBytes=max_bytes, backupCount=size_backup, encoding="utf-8", ) attach_rolling( - handler, log_dir, compress, prune_stem=name, backup_count=backup_count, + handler, log_dir, compress, prune_stem=history_stem, backup_count=backup_count, keep_uncompressed=keep_uncompressed, keep_compressed=keep_compressed, - size_tiered=tiered, + tiered=tiered, ) elif rotate == "daily": handler = logging.handlers.TimedRotatingFileHandler( live_path, when="midnight", backupCount=backup_count, encoding="utf-8", ) attach_rolling( - handler, log_dir, compress, prune_stem=name, backup_count=backup_count, + handler, log_dir, compress, prune_stem=history_stem, backup_count=backup_count, keep_uncompressed=keep_uncompressed, keep_compressed=keep_compressed, + tiered=tiered, ) else: if rotate == "on_start": if tiered: rotate_on_start( - live_path, log_dir, compress, + live_path, log_dir, compress, history_stem=history_stem, keep_uncompressed=keep_uncompressed, keep_compressed=keep_compressed, ) else: - rotate_on_start(live_path, log_dir, compress) - prune(log_dir, name, backup_count) + rotate_on_start(live_path, log_dir, compress, history_stem=history_stem) + prune(log_dir, history_stem, backup_count) elif rotate is not None: # a typo'd rotate value (e.g. "hourly") would otherwise silently fall through # to a non-rotating FileHandler and grow forever — warn, matching the @@ -177,6 +196,7 @@ def setup_logging( level: Union[int, str] = "INFO", module_levels: Optional[Dict[str, Union[int, str]]] = None, rotate: Optional[str] = "daily", + history_name: Optional[str] = None, backup_count: int = 14, keep_uncompressed: Optional[int] = None, keep_compressed: Optional[int] = None, @@ -193,6 +213,10 @@ def setup_logging( `name` -> .log live file at cwd; rolled/compressed copies go to `log_dir`. a trailing ".log" in `name` is stripped so "latest" and "latest.log" both produce the live file latest.log (never latest.log.log). + `history_name` names the rolled/historic files (`..log[.gz]`), + independent of the live file: it defaults to the PROJECT namespace = the cwd basename + (run from bestbuy/ -> historic files bestbuy....), and can be set explicitly. the + live file always keeps `name`; only the historic files carry the project name. `keep_uncompressed`/`keep_compressed` (default None) enable TIERED retention: when either is given, rolled files are kept as the newest `keep_uncompressed` uncompressed + the next `keep_compressed` gzipped, and the rest are deleted (total retained = @@ -231,6 +255,12 @@ def setup_logging( formatter = build_formatter(output, fmt, datefmt) stem = _normalize_name(name) live_path = f"{stem}.log" + # historic/rolled files are named off the project namespace, independent of the live + # file: history_name if given, else the cwd basename (e.g. run from bestbuy/ -> historic + # files bestbuy..log[.gz]). normalized + basenamed like `name`; falls back to the + # live stem for a degenerate cwd so naming/retention never break. + history_source = history_name if history_name is not None else _history_stem() + history_stem = os.path.basename(_normalize_name(history_source)) or stem handlers = [] @@ -243,7 +273,7 @@ def setup_logging( if file_ok: try: fh = _file_handler( - stem, live_path, log_dir, rotate, backup_count, max_bytes, compress, + stem, history_stem, live_path, log_dir, rotate, backup_count, max_bytes, compress, keep_uncompressed, keep_compressed, ) fh.setFormatter(formatter)