JSONL-LOGGER 1.0.0__tar.gz

jsonl_logger-1.0.0/JSONL_LOGGER.egg-info/PKG-INFO

@@ -0,0 +1,202 @@
+Metadata-Version: 2.4
+Name: JSONL-LOGGER
+Version: 1.0.0
+Summary: Async queue-based structured logging with JSONL output - single file, zero dependencies beyond python-dotenv
+Author-email: rocky <rocky@null.net>
+License: MIT
+Project-URL: Homepage, https://github.com/rocky/JSONL-LOGGER
+Project-URL: Bug Reports, https://github.com/rocky/JSONL-LOGGER/issues
+Project-URL: Source, https://github.com/rocky/JSONL-LOGGER
+Keywords: logging,jsonl,structured-logging,async-logging,audit-logging
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Logging
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Dynamic: license-file
+
+# JSONL-LOGGER
+
+Async queue-based structured logging with JSONL output - single file, zero dependencies beyond python-dotenv.
+
+## Installation
+
+```bash
+pip install JSONL-LOGGER
+```
+
+## Quick Start
+
+### 1. Configure Environment Variables
+
+Create a `.env` file in your project root:
+
+```bash
+PROJECT_DIRECTORY=/path/to/your/project
+LOGS_LOCAL_TIMEZONE=Asia/Kolkata
+```
+
+### 2. Import and Use
+
+```python
+from JSONL_LOGGER import log_info, log_warn, log_error, log_metric
+
+# Info logging with structured fields
+log_info("User logged in", user_id=123, email="user@example.com")
+
+# Warning logging
+log_warn("Rate limit approaching", remaining=10, reset_seconds=60)
+
+# Error logging with error codes
+log_error("Payment failed", error_code=500, error="insufficient_funds")
+
+# Metrics logging (custom METR level between INFO and WARNING)
+log_metric("api_latency_ms", 142.5, unit="ms", endpoint="/checkout", method="POST")
+log_metric("request_count", 1000, logfile_name="orders", module_name="order_service", status="success")
+
+# Notifications to main_logger.jsonl
+from JSONL_LOGGER import send_notification, send_notification_async
+
+send_notification("Application started", source_file="main.py")
+await send_notification_async("Deployment completed", source_file="deploy.py")
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `PROJECT_DIRECTORY` | Yes | - | Root directory for log storage |
+| `LOGS_LOCAL_TIMEZONE` | Yes | - | Local timezone (e.g., `Asia/Kolkata`, `UTC`) |
+| `LOGGER_FILE_NAME` | No | `LOGS` | Default log file name (set via env to override) |
+| `CONSOLE_LOGGING_ENABLED` | No | `false` | Enable colored console output |
+| `LOGGER_REGISTER_SIGNALS` | No | `false` | Register SIGINT/SIGTERM handlers for flush |
+| `LOGGER_DAEMON_THREAD` | No | `true` | Writer thread daemon status |
+| `LOGGER_MAX_BUFFER_SIZE` | No | `200000` | Maximum buffer entries before drop |
+| `DEBUG_PRINT` | No | `false` | Enable debug output |
+
+### Common Timezones
+
+```
+Asia:       Asia/Kolkata, Asia/Dubai, Asia/Singapore, Asia/Tokyo
+Europe:     Europe/London, Europe/Paris, Europe/Berlin
+Americas:   America/New_York, America/Chicago, America/Los_Angeles
+UTC:        UTC
+```
+
+## Output
+
+### File Structure
+
+```
+{PROJECT_DIRECTORY}/_LOGS_DIRECTORY/{YYYY_MM_DD}/LOGS/{logfile_name}.jsonl
+```
+
+Example: `/path/to/logs/_LOGS_DIRECTORY/2026_04_03/LOGS/orders.jsonl`
+
+### JSONL Format
+
+Each log entry is a valid JSON object on a single line:
+
+```json
+{"timestamp":"2026-04-03T05:30:00.000Z","timestamp_local":"2026-04-03T11:00:00.000+05:30","level":"INFO","logfile_name":"orders","module_name":"orders","source_file":"order_service.py","message":"User logged in","user_id":123}
+```
+
+### Dual-Write Behavior
+
+| Function | Writes To |
+|----------|------------|
+| `log_info()` | `{module}.jsonl` |
+| `log_warn()` | `{module}.jsonl`, `{module}.warn.jsonl` |
+| `log_error()` | `{module}.jsonl`, `{module}.errors.jsonl` |
+| `log_metric()` | `{module}.jsonl`, `{module}.metrics.jsonl` |
+| `send_notification()` | `main_logger.jsonl` |
+
+## Key Features
+
+1. **Queue-Based Async Logging** - Background thread writes to disk; API calls return immediately
+2. **Per-Module Log Files** - Each module gets its own JSONL file for independent retention
+3. **Dual Timestamps** - UTC for machine parsing, local time for human readability
+4. **Retry with Exponential Backoff** - 3 attempts with 100ms/200ms/400ms delays
+5. **Zero Data Loss** - Buffer capped at 50k entries; oldest dropped on overflow
+6. **Signal Handlers** - Optional SIGINT/SIGTERM flush on shutdown
+
+## Performance
+
+```
+┌───────────────────┬──────────┬──────────┬────────────┬──────────────────────────┐
+│ Test              │ Logs     │ Time     │ Throughput │ Status                  │
+├───────────────────┼──────────┼──────────┼────────────┼──────────────────────────┤
+│ Single-thread     │ 10,000   │ 1.04 sec │ 9,643/sec  │ ✅ PASS                 │
+│ Multi-thread      │ 100,000  │ 16.87 sec│ 5,902/sec  │ ✅ PASS                 │
+└───────────────────┴──────────┴──────────┴────────────┴──────────────────────────┘
+System: Ubuntu 24.04.4 LTS | AMD Ryzen 7 5800H | Python 3.12.3
+Tested: 10 runs average
+```
+
+## API Reference
+
+### log_info(message, logfile_name=None, module_name=None, source_file=None, **extra_fields)
+Log an info message with optional structured fields.
+- `message`: Log message
+- `logfile_name`: Log file name (auto-detected if omitted)
+- `module_name`: Source module name (auto-detected if omitted)
+- `source_file`: Actual source filename (auto-detected if omitted)
+- `**extra_fields`: Additional structured fields
+
+### log_warn(message, logfile_name=None, module_name=None, source_file=None, **extra_fields)
+Log a warning message. Writes to both main and `.warn.jsonl` files.
+- Same parameters as `log_info`
+
+### log_error(message, logfile_name=None, module_name=None, source_file=None, **extra_fields)
+Log an error message. Writes to both main and `.errors.jsonl` files.
+- Same parameters as `log_info`
+
+### log_metric(metric_name, value, unit="", logfile_name=None, module_name=None, source_file=None, **tags)
+Log a metric with custom METR level (between INFO and WARNING).
+- `metric_name`: Metric identifier (e.g. "api_latency_ms")
+- `value`: Numeric value (int or float)
+- `unit`: Unit label (e.g. "ms", "bytes")
+- `logfile_name`: Log file name (auto-detected if omitted)
+- `module_name`: Source module name (auto-detected if omitted)
+- `source_file`: Actual source filename (auto-detected if omitted)
+- `**tags`: Additional fields for grouping/filtering
+
+### send_notification(message, logfile_name=None, module_name=None, source_file=None)
+Send a notification to the main_logger.jsonl file (blocking).
+- `message`: Notification text
+- `logfile_name`: Log file name (auto-detected if omitted)
+- `module_name`: Source module name (auto-detected if omitted)
+- `source_file`: Actual source filename (auto-detected if omitted)
+
+### send_notification_async(message, logfile_name=None, module_name=None, source_file=None)
+Send a notification to the main_logger.jsonl file (non-blocking).
+- Same parameters as `send_notification`
+
+### _flush_logs()
+Manually flush all buffered logs to disk.
+
+## Error Handling
+
+The logger will raise `ValueError` if:
+- `PROJECT_DIRECTORY` is not set or doesn't exist
+- `LOGS_LOCAL_TIMEZONE` is not set
+- Directory is not writable
+
+Non-primitive types in extra fields will emit a stderr warning and be stringified.
+
+## Version
+
+Current: 1.0.0

jsonl_logger-1.0.0/JSONL_LOGGER.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+JSONL_LOGGER.py
+LICENSE
+README.md
+pyproject.toml
+JSONL_LOGGER.egg-info/PKG-INFO
+JSONL_LOGGER.egg-info/SOURCES.txt
+JSONL_LOGGER.egg-info/dependency_links.txt
+JSONL_LOGGER.egg-info/requires.txt
+JSONL_LOGGER.egg-info/top_level.txt

jsonl_logger-1.0.0/JSONL_LOGGER.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

jsonl_logger-1.0.0/JSONL_LOGGER.egg-info/requires.txt

@@ -0,0 +1,5 @@
+python-dotenv>=1.0.0
+
+[dev]
+pytest>=7.0.0
+pytest-cov>=4.0.0

jsonl_logger-1.0.0/JSONL_LOGGER.egg-info/top_level.txt

@@ -0,0 +1 @@
+JSONL_LOGGER