docs(logging): document async durability semantics and testing patterns

.gitignore

@@ -167,4 +167,5 @@ logs/
 # Documentation build
 documentation/build/
 documentation/.docusaurus/
-documentation/node_modules/
+documentation/node_modules/
+.gitbotrc.json

CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- Async logging flush semantics documentation and shutdown patterns guide.
+- New guides: `testing-patterns.md` (async logger testing), `common-pitfalls.md`.
+- `AsyncConfig` validation with helpful error messages.
+- Async logger test utilities: `wait_for_async_queue_drain`, `async_logger_with_teardown` fixture.
+- Export of `shutdown_async_backend` from main `kakashi` package.
+
+### Changed
+- README license reference corrected to LGPL-2.1.
+- Expanded async-backends documentation with flush semantics and shutdown patterns.
+- Deprecated legacy `AsyncLogger` (removal planned for v0.4.0); use `kakashi.core.async_interface.get_async_logger`.
+- Type hints completed in `logger.py`, `async_interface.py`.
+- Deprecations doc now documents dual async systems and migration path.
+
+### Fixed
+- Session test teardown now shuts down both legacy and functional async backends.
+
 ## [0.2.1] - 2026-02-05
 
 ### Changed

README.md

@@ -64,14 +64,24 @@ kakashi/
 │   ├── structured_logger.py # Structured logging support
 │   └── sinks.py            # Output destination system
 ├── performance_tests/       # Performance validation
-│   └── validate_performance.py
+│   ├── test_performance.py
+│   ├── test_api_compatibility.py
+│   └── test_stability.py
 └── README.md               # This file
 ```
 
 ## 📖 Quick Start
 
 ### Basic Usage
 
+**Tip:** For production apps using async logging, register shutdown at startup to prevent message loss:
+
+```python
+import atexit
+from kakashi import shutdown_async_logging, shutdown_async_backend
+atexit.register(shutdown_async_backend)  # For functional async; use shutdown_async_logging for legacy
+```
+
 ```python
 from kakashi import get_logger, get_async_logger
 
@@ -131,7 +141,8 @@ Run the performance validation to ensure your installation meets production targ
 
 ```bash
 cd performance_tests
-python validate_performance.py
+pip install -r requirements.txt
+python -m pytest test_performance.py -v --benchmark-only
 ```
 
 This will test:
@@ -199,19 +210,35 @@ This will test:
 
 ## 🚨 Migration from v0.1.x
 
-The v0.2.0 release maintains backward compatibility while providing significant performance improvements:
+The v0.2.x release maintains backward compatibility while providing significant performance improvements:
 
 ```python
 # Old v0.1.x code (still works)
-from kakashi import setup, get_logger
-setup("production")
+from kakashi import setup_logging, get_logger
+setup_logging("production")
 logger = get_logger(__name__)
 
-# New v0.2.0 code (recommended)
+# New v0.2.x code (recommended)
 from kakashi import get_logger
 logger = get_logger(__name__)  # Auto-configuration
 ```
 
+### Async Logger Migration
+
+```python
+# Legacy (will be deprecated)
+from kakashi import get_async_logger, shutdown_async_logging
+logger = get_async_logger(__name__)
+# ... use logger ...
+shutdown_async_logging()
+
+# Functional (recommended)
+from kakashi.core.async_interface import get_async_logger, shutdown_async_backend
+logger = get_async_logger(__name__)  # Same name, different implementation
+# ... use logger ...
+shutdown_async_backend(timeout=5.0)
+```
+
 ## 🧭 Roadmap & Collaboration
 
 We are looking for collaborators to help build the next evolution of Kakashi:
@@ -235,7 +262,7 @@ We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) f
 
 ## 📄 License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+This project is licensed under the LGPL-2.1 License - see the [LICENSE](LICENSE) file for details.
 
 ## ⚖️ Legal Disclaimers
 
@@ -262,4 +289,4 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ---
 
-**Kakashi v0.2.0** - Professional High-Performance Logging for Python
+**Kakashi v0.2.1** - Professional High-Performance Logging for Python

documentation/docs/api/core.md

@@ -97,7 +97,7 @@ class AsyncLogger:
     def critical(self, message: str, **fields: Any) -> None
     def exception(self, message: str, **fields: Any) -> None
 
-    def flush(self) -> None
+    def flush(self) -> None  # Best effort only - see below
 ```
 
 **Key Features:**
@@ -106,6 +106,8 @@ class AsyncLogger:
 - Batch processing for optimal throughput
 - Graceful shutdown with proper cleanup
 
+**Warning - `flush()` semantics:** `AsyncLogger.flush()` is best-effort only. It sleeps 1ms to yield to the background worker but does NOT guarantee that queued messages have been written. For durability guarantees at shutdown, use `shutdown_async_logging()` or `shutdown_async_backend(timeout=...)` instead.
+
 ## Utility Functions
 
 ### `clear_logger_cache()`

documentation/docs/guides/async-backends.md

@@ -167,6 +167,16 @@ def setup_analytics_logging():
     return logger
 ```
 
+### Flush Semantics (Important)
+
+**`flush()` on async loggers does NOT guarantee durability.**
+
+- **Legacy AsyncLogger** (from `kakashi.core.logger`): `flush()` only sleeps 1ms to yield to the background worker. It does **not** wait for queued messages to be written.
+- **Functional async loggers** (from `kakashi.core.async_interface`): There is no `flush()` that drains the queue. Messages are processed asynchronously in batches.
+- **Only `shutdown_async_backend(timeout=...)` guarantees** that all queued messages are processed before the process exits. This is the ONLY way to ensure no message loss at shutdown.
+
+**Do not rely on `flush()` for application logic.** Treat async logging as best-effort telemetry. For critical audit trails or state, write to a reliable store (database, message queue) and log secondarily.
+
 ### Error Handling and Recovery
 
 ```python
@@ -181,27 +191,45 @@ def graceful_shutdown():
         print(f"Error during shutdown: {e}")
 ```
 
-### Best Practices
+### Application Shutdown Patterns
 
-1. **Queue Sizing**: Start with 25,000-50,000 max queue size, adjust based on throughput
-2. **Worker Count**: Use 2-4 workers for most applications, 8+ for extreme throughput
-3. **Batch Sizing**: Start with 200-500 batch size, increase for higher throughput
-4. **Monitoring**: Monitor queue sizes and worker health in production
-5. **Error Handling**: Implement graceful shutdown to prevent message loss
-6. **Graceful Shutdown**: Ensure all queued messages are processed on shutdown
+**You must call `shutdown_async_backend()` at application exit** to prevent message loss. If the process exits without shutdown, queued messages may never be written.
+
+#### Recommended: Register with atexit
 
 ```python
 import atexit
 from kakashi.core.async_interface import shutdown_async_backend
 
-# Register shutdown handler
+# Register early (e.g. at startup)
 atexit.register(shutdown_async_backend)
 
-# Or manually at exit:
-def cleanup():
-    shutdown_async_backend(timeout=10.0)
+# Or with custom timeout for high-volume apps:
+atexit.register(lambda: shutdown_async_backend(timeout=10.0))
 ```
 
+#### Timeout Considerations
+
+- **Default (5s)**: Suitable for most applications
+- **High-volume**: Use 10-30s if you expect large queues or slow disk/network I/O
+- **Tests**: Use shorter timeouts (1-2s) to avoid hanging test suites
+- If timeout is exceeded, some messages may be dropped during shutdown
+
+#### What Happens Without Shutdown
+
+- Worker threads are daemon threads in some configurations; the process can exit before the queue drains
+- Even with non-daemon workers, abrupt exit (SIGKILL, `os._exit`) bypasses atexit
+- Result: silent message loss. Always register shutdown for production services.
+
+### Best Practices
+
+1. **Queue Sizing**: Start with 25,000-50,000 max queue size, adjust based on throughput
+2. **Worker Count**: Use 2-4 workers for most applications, 8+ for extreme throughput
+3. **Batch Sizing**: Start with 200-500 batch size, increase for higher throughput
+4. **Monitoring**: Monitor queue sizes and worker health in production
+5. **Error Handling**: Implement graceful shutdown to prevent message loss
+6. **Graceful Shutdown**: Ensure all queued messages are processed on shutdown (see Application Shutdown Patterns above)
+
 ---
 
 *Last updated: 2025-08-27*

documentation/docs/guides/common-pitfalls.md

@@ -0,0 +1,153 @@
+---
+id: common-pitfalls
+title: Common Pitfalls with Async Loggers
+---
+
+## Overview
+
+This guide documents common mistakes when using Kakashi's async logging and how to avoid them.
+
+## 1. Relying on `flush()` for Durability
+
+**Wrong**: Assuming `flush()` waits for all queued messages to be written.
+
+```python
+async_logger.info("Critical audit event")
+async_logger.flush()  # Does NOT guarantee durability!
+# Message may still be in queue - process could exit before it's written
+```
+
+**Why**: `AsyncLogger.flush()` only sleeps 1ms to yield to the background worker. Functional async loggers have no `flush()` that drains the queue.
+
+**Right**: Call `shutdown_async_backend(timeout=...)` at application exit.
+
+```python
+import atexit
+from kakashi.core.async_interface import shutdown_async_backend
+atexit.register(shutdown_async_backend)
+```
+
+---
+
+## 2. Not Shutting Down Async Backends
+
+**Wrong**: Letting the process exit without calling shutdown.
+
+```python
+# main.py
+logger = get_async_logger(__name__)
+logger.info("Server stopping")
+# Process exits - queued messages are lost
+```
+
+**Why**: Worker threads may not get CPU time to drain the queue before the process exits. Daemon threads are terminated immediately.
+
+**Right**: Register shutdown with atexit or call it explicitly before exit.
+
+```python
+atexit.register(lambda: shutdown_async_backend(timeout=10.0))
+```
+
+---
+
+## 3. Using Async Loggers in Tests Without Cleanup
+
+**Wrong**: Asserting on log output immediately after async logging.
+
+```python
+def test_login():
+    logger = get_async_logger("auth")
+    logger.info("User logged in", user_id="123")
+    assert "User logged in" in open("app.log").read()  # Flaky - message may not be written yet
+```
+
+**Why**: Messages are enqueued asynchronously. The assertion runs before the worker processes the queue.
+
+**Right**: Shut down the backend before asserting, or use a sync logger for this test.
+
+```python
+def test_login():
+    logger = get_async_logger("auth")
+    logger.info("User logged in", user_id="123")
+    shutdown_async_backend(timeout=2.0)
+    assert "User logged in" in open("app.log").read()
+```
+
+See [Testing Patterns](/docs/guides/testing-patterns) for more.
+
+---
+
+## 4. Queue Overflow and Silent Message Drops
+
+**Wrong**: Assuming every log call results in a written message.
+
+```python
+# High throughput - queue fills up
+for i in range(1_000_000):
+    logger.info("Event", id=i)  # Some messages may be dropped
+```
+
+**Why**: When the queue is full, the configured overflow strategy (e.g. `drop_oldest`) causes silent drops. There is no exception.
+
+**Right**: Monitor queue size via `get_async_stats()`, size the queue appropriately, and treat async logging as best-effort for non-critical telemetry.
+
+```python
+stats = get_async_stats()
+if stats.get("queue_size", 0) > 0.8 * stats.get("max_queue_size", 1):
+    # Consider backpressure or alerting
+    pass
+```
+
+---
+
+## 5. Mixing Legacy and Functional Async APIs
+
+**Wrong**: Calling both shutdown functions and getting confused about which backend is active.
+
+```python
+from kakashi import get_async_logger, shutdown_async_logging
+from kakashi.core.async_interface import get_async_logger as get_func_async, shutdown_async_backend
+
+# Two different systems - easy to mix up
+legacy = get_async_logger("a")
+func = get_func_async("b")
+# Which shutdown drains which queue?
+```
+
+**Why**: Kakashi has two separate async implementations. Each has its own queue and shutdown.
+
+**Right**: Stick to one system. For new code, use the functional API throughout.
+
+```python
+from kakashi.core.async_interface import get_async_logger, shutdown_async_backend
+logger = get_async_logger(__name__)
+# ...
+shutdown_async_backend()
+```
+
+---
+
+## 6. Blocking on Full Queue with Default Config
+
+**Wrong**: Assuming `put` always succeeds; in `block` mode a full queue can block the calling thread.
+
+```python
+# Default overflow_strategy is "block"
+for i in range(100_000):
+    logger.info("x")  # Can block indefinitely if workers are slow
+```
+
+**Right**: For high-throughput or latency-sensitive paths, use `queue_overflow_strategy="drop_oldest"` and accept potential drops, or increase queue size and worker count.
+
+---
+
+## Summary
+
+| Pitfall | Mitigation |
+|---------|------------|
+| Relying on `flush()` | Use `shutdown_async_backend()` at exit |
+| No shutdown | Register `atexit.register(shutdown_async_backend)` |
+| Flaky tests | Shut down before asserting, or use sync logger |
+| Queue overflow | Monitor stats, size queue, treat as best-effort |
+| Mixing APIs | Use functional async only for new code |
+| Blocking on full queue | Use `drop_oldest` or increase capacity |