fastlog-io 0.2.4

loguru fast wrapping supports fastapi

FastLOG is a lightweight wrapper around Loguru that offers Prometheus metrics, automatic `trace_id`, colourful output, and a dead‑simple configuration API.

---

✨ Features

• Zero‑config logger – from fastlog import log; log.info("hello") works instantly.
• Automatic trace_id – 7‑character NanoID is injected when none is bound, ideal for tracing.
• Configurable rotation & retention – ship with sane defaults (100 MB rotation) and tweak via configure().
• Stdlib interception – reset_std_logging() routes the standard logging module through fastlog.
• Directory watcher & notifier – MultiLogWatcher tails rotating *.log families, persists offsets, and forwards new lines over HTTP and/or Telegram.

---

🚀 Installation

pip install fastlog-io

Requirements

• Python ≥ 3.12
• loguru

---

⚡ Quickstart

import logging

from fastlog import configure, log

# override defaults if needed
configure(
    level='DEBUG',
    log_path='./logs/app.log',
    rotation='10 MB',
    retention='7 days',
)

log.info('service started')

# standard logging is intercepted automatically
logging.getLogger('my-app').warning('cache miss')

# add trace context
with log.trace_ctx():
    log.error('request failed')
    # use custom actions
    log.bind(action='api.call').info('request done')

Console output (colours stripped):

2025-10-13 12:23:00.193 | INFO     | 3hAhb3OFpU7zXKWBwp | ts.<module>:13 | service started
2025-10-13 12:23:00.194 | WARNING  | 1F1FwLwm4Orok0gs0a | [my-app]ts.<module>:16 | cache miss
2025-10-13 12:23:00.194 | ERROR    | WG8yiDxzO3MCmWy8CB | ts.<module>:20 | request failed
2025-10-13 12:23:00.194 | INFO     | WG8yiDxzO3MCmWy8CB | api.call     | request done

---

🖥️ Directory watcher CLI

FastLOG ships with a CLI that tails a directory of *.log files, resumes from persisted byte offsets, and forwards high‑severity bursts.

uv tool install fastlog-io

# Watch ./logs, post notifications to HTTP and Telegram
uv run fastlog ./logs \
  --endpoint "$FASTLOG_NOTIFY_ENDPOINT" \
  --min-level ERROR

# Or send to Telegram
uv run fastlog ./logs \
  --tg-token "$FASTLOG_NOTIFY_TG_TOKEN" \
  --tg-chat-id "$FASTLOG_NOTIFY_TG_CHAT_ID"
  --min-level ERROR

# show all options
uv run fastlog --help

Key behaviour:

• Rotations/renames are detected; offsets are stored in .multilogwatch.state.json.
• Notifications are batched, deduplicated, and retried up to three times per transport.
• Telegram delivery is optional—provide both --tg-token and --tg-chat-id (or matching env vars).

🔧 Environment variables

Variable	Default	Description
LOG_PATH	(empty)	Log file path; leave blank to log to stderr only
LOG_LEVEL	INFO	Minimum log level for configure()
LOG_ROTATION	100 MB	File rotation policy (Loguru syntax)
FASTLOG_NOTIFY_ENDPOINT	(empty)	HTTP endpoint used by the CLI watcher
FASTLOG_NOTIFY_LEVEL	(empty)	Minimum notification level override
FASTLOG_NOTIFY_TIMEOUT	(empty)	HTTP timeout override (seconds)
FASTLOG_NOTIFY_WINDOW_MINUTES	1.0	Aggregation window for batching
FASTLOG_NOTIFY_MAX_BYTES	4096	Maximum payload size per request
FASTLOG_NOTIFY_TG_TOKEN	(empty)	Telegram bot token for watcher notifications
FASTLOG_NOTIFY_TG_CHAT_ID	(empty)	Telegram chat ID for watcher notifications

Variables can also be supplied as CLI flags; command‑line arguments take precedence over environment values.

---

🛠 Development & Tests (powered by uv)

# run tests in a temp venv with test extras installed
uv run --with '.[test]' pytest -q

# build wheel + sdist
uv build

# verify the built wheel in a clean env
uv run --with dist/*.whl --with pytest pytest -q

---

📄 License

MIT © 2025 OWQ