lognote 0.2.2

A Black Box Flight Recorder for Python applications.

Stop guessing why your production code crashed. Start replaying it.

---

🛩️ What is lognote?

lognote acts like an airplane's Flight Data Recorder — silently capturing every function call, argument, and variable state in the background. When your app crashes, lognote hands you a full AI-driven autopsy report — no print statements, no heavy debuggers, no regrets.

In a world where logs are often too thin and debuggers are too heavy, lognote sits perfectly in the middle with Agentic Instrumentation that works without touching a single line of your existing code.

┌─────────────────────────────────────────────────────────┐
│                    YOUR APPLICATION                     │
│                                                         │
│   main() → service() → db_query() → 💥 CRASH           │
│      ↑           ↑          ↑                           │
│      └───────────┴──────────┘                           │
│           lognote records EVERYTHING                    │
└─────────────────────────────────────────────────────────┘

---

🧩 The Real Problem (And How lognote Solves It)

🔴 The Problem	✅ The lognote Solution
The "Heisenbug" — crashes that vanish under a debugger	Captures the exact locals() state at the millisecond of failure
Production Latency — tracing slows everything down	Non-blocking background worker: main thread overhead < 1ms
PII Leaks — passwords & tokens ending up in log files	Multi-layer Semantic Filter redacts secrets before they touch disk
Post-Mortem Fatigue — staring at stack traces for hours	AI diagnosis explains why the crash happened in plain English

---

🏗️ System Architecture

╔══════════════════════════════════════════════════════════════════╗
║                    lognote Flight Recorder                       ║
╠══════════════════════════════════════════════════════════════════╣
║                                                                  ║
║   Your Code          sys.settrace Engine                         ║
║   ──────────  ──►   ─────────────────────                        ║
║   main()             IGNITE: Hook into your project scope        ║
║   service()          FILTER: Skip stdlib & site-packages         ║
║   db_query()         CAPTURE: locals(), args, return values      ║
║                             │                                    ║
║                             ▼                                    ║
║                     ┌───────────────┐                            ║
║                     │  Async Queue  │  ← Non-blocking buffer     ║
║                     └───────┬───────┘                            ║  
║                             │                                    ║
║                             ▼                                    ║
║                     ┌───────────────┐                            ║
║                     │ PII Scrubber  │  ← Redacts secrets         ║
║                     └───────┬───────┘                            ║
║                             │                                    ║
║                             ▼                                    ║
║                     ┌───────────────┐                            ║
║                     │  JSON Flight  │  ← Structured record       ║
║                     │    Record     │                            ║
║                     └───────────────┘                            ║
╚══════════════════════════════════════════════════════════════════╝

4 Phases, Zero Effort:

1. 🔥 Ignite — sys.settrace hooks into every call in your project
2. 🔍 Filter — Ignores site-packages and stdlib for maximum performance
3. 📥 Buffer — Events pushed to a thread-safe Queue
4. 💾 Process — Background thread scrubs PII and writes the .json Flight Record

---

🚀 Quickstart

Step 1 — Install

pip install lognote

Step 2 — One Line. That's It.

import lognote

# 🔥 Ignite the flight recorder
lognote.ignite(output_dir="./traces", secret_scrubbing=True)

# ✅ The rest of your application — completely unchanged
def process_payment(user_id, amount):
    ...

def fetch_user(token):
    ...

No decorators. No wrappers. No config files. Just one line at the top of main.py.

Step 3 — Analyze the Crash

When a crash occurs, a .json Flight Record is auto-generated. Replay it with the built-in Time-Travel CLI:

python -m lognote view ./traces/lognote_trace_1714412345.json

You'll get a beautiful terminal dashboard like this:

╔══════════════════════════════════════════════════════════╗
║  🛩  lognote — Flight Record Analysis                    ║
║  File: lognote_trace_1714412345.json                     ║
╠══════════════════════════════════════════════════════════╣
║  Timeline                                                ║
║  ─────────────────────────────────────────────────────── ║
║  14:22:01.001  →  main()         [ENTER]  args={}        ║
║  14:22:01.003  →  fetch_user()   [ENTER]  token=***      ║
║  14:22:01.045  →  db_query()     [ENTER]  sql="SELECT…"  ║
║  14:22:01.099  →  db_query()     [EXIT]   result=None    ║
║  14:22:01.100  →  process()      [ERROR]  💥 CRASH       ║
║                                                          ║
║  🤖 AI Diagnosis                                        ║
║  ─────────────────────────────────────────────────────── ║
║  db_query() returned None because the connection pool    ║
║  was exhausted. process() tried to call .rows on None.   ║
║  Fix: Add a null-check after db_query() or increase      ║
║  MAX_POOL_SIZE in your database config.                  ║
╚══════════════════════════════════════════════════════════╝

---

💎 Features at a Glance

Feature	Description
🎯 Zero-Config	No decorators, no wrappers. ignite() and you're done.
🤖 Agentic Tracing	Automatically identifies function boundaries & captures all arguments.
🔒 Privacy-First	Built-in RegEx + keyword filters for SSN, passwords, API tokens.
⚡ Async by Design	Background worker writes logs — your API latency stays untouched.
🖥️ Rich Dashboard	Terminal UI with full event timeline leading to the crash.
🧠 AI Diagnosis	Plain-English explanation of why the crash happened.
🗂️ Structured Output	Portable .json flight records — pipe to any observability stack.

---

⚙️ Configuration Reference

lognote.ignite(
    output_dir    = "./logs",    # Where to save .json flight records
    secret_scrubbing = True,     # Auto-mask: passwords, tokens, SSNs
    max_queue_size   = 1000,     # Cap memory during high-burst execution
)

Parameter	Default	Description
output_dir	./logs	Directory for .json flight records
secret_scrubbing	True	Redact sensitive variable names/values
max_queue_size	1000	Memory ceiling during burst traffic

---

🔐 Privacy & Security

lognote's Multi-Layer Semantic Filter protects your users before data ever reaches disk:

Raw Variable State
       │
       ▼
  ┌─────────────────────────────┐
  │  Layer 1: Keyword Match     │  password, token, secret, key, ssn…
  ├─────────────────────────────┤
  │  Layer 2: RegEx Patterns    │  /Bearer [A-Z0-9]+/, credit card…
  ├─────────────────────────────┤
  │  Layer 3: Entropy Scanner   │  High-entropy strings → likely keys
  └─────────────────────────────┘
       │
       ▼
  Scrubbed Record  →  { "token": "***REDACTED***" }

---

🛣️ Roadmap

• Core sys.settrace engine
• Async queue + background worker
• Multi-layer PII scrubber
• Time-Travel CLI viewer
• AI-powered crash diagnosis
• 🔜 OpenTelemetry export
• 🔜 Web dashboard (FastAPI + React)
• 🔜 async/await coroutine tracing
• 🔜 Pytest plugin for trace-on-fail

---

🤝 Contributing

lognote is open-source and welcomes contributors! Here's how to get started:

# Clone the repo
git clone https://github.com/Nvishal2006/lognote.git
cd lognote

# Set up your environment
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# Run tests
pytest tests/

• 🐛 Found a bug? Open an issue on GitHub
• 💬 Want to discuss? Join the conversation on LinkedIn
• 🌟 Like the project? Star it — it helps more than you'd think!

---

👨💻 Author

Building tools that make Python production-ready.

---

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

---

lognote — Because every crash deserves a black box.

_{Made with ❤️ by Vishal N · Python Observability · Open Source}