# 🧠 logmachine 2.1.0
> Collaborative, beautiful logging system for distributed developers
**logmachine** helps teams log smarter. It’s a fully pluggable logging system that supports colored output, JSON parsing, structured log forwarding via **HTTP or Socket.IO**, and log centralization — all from a standard Python logging interface.
---
## 🚀 Features
- 🔥 **Color-coded terminal logs** (DEBUG, INFO, WARNING, ERROR, SUCCESS)
- 📤 **Log forwarding** to a central HTTP or Socket.IO server
- 🪵 **Custom log levels** (add your own with `.new_level(...)`)
- 👥 **User identity tracking** for team-based logs
- 🧩 **Pluggable backends**: send logs to a central server or local files
- 📦 **Simple JSON output** for web dashboards or collectors
- 🧽 Strips ANSI escape codes from logs for clean parsing
- 🧠 Automatically resolves usernames and saves them in `~/.cl_username`
---
## ⚙️ Installation
```bash
pip install logmachine
```
---
## 🧰 Usage
### Basic Setup
```python
from logmachine import ContribLog
# Create a simple logger without central logging
# Providing a noon-empty string initializes the logger with that name, else the root logger is used to collect every single log in the python process.
logger = ContribLog("myapp", debug_level=1)
logger.info("Hello, world!")
logger.error("An error occurred!")
logger.success("Operation completed successfully!")
logger.debug("Debugging information here.")
logger.warning("This is a warning message.")
```
### With Central Logging (HTTP or Socket.IO)
```python
logger_config = {
"url": "https://logmachine.bufferpunk.com", # Base server URL
"room": "team_alpha", # Your organization or room
"endpoint": "/api/logs", # Optional, defaults to /api/logs
"headers": {"Authorization": "Bearer token"},
"socketio": True, # Set False to use HTTP
"socketio_path": "/api/socket.io/" # Optional
}
logger = ContribLog("with_central", debug_level=0, central=logger_config, socketio=True)
logger.success("Central logging is working!")
```
---
## 🎨 Log Format
Every log includes:
* ✅ Username (resolved automatically or via server)
* 📁 Module directory
* ⏱️ Timestamp
* 📦 Level (INFO, ERROR, etc.)
* 📝 Message
Sample (terminal):
```
(username @ myapp) 🤌 CL Timing: [ 2025-08-04T11:23:52 ]
[ INFO ] Server started on port 8000
🏁
```
---
## 🛠️ Advanced
### Add Your Own Log Level
```python
log.new_level("CRITICAL_HACK", 60)
log.critical_hack("Zero day found!")
```
---
## 📤 Parse & Export
### Convert Logs to JSON
```python
json_logs = log.jsonifier()
for entry in json_logs:
print(entry)
```
---
## 📡 Central Server Compatibility
To use Socket.IO, your central server must support these events:
* `log`: Receives log payloads: `{ room: string, data: object }`
* `GET /api/get_username?base=localname`: Returns `{ "username": "..." }`
---
## 🤖 Environment Variables
* `CL_USERNAME`: Manually override detected username
* Automatically stored in `~/.cl_username` for persistent identity
---
## 🔐 Security
* HTTP headers (e.g. `Authorization`) can be injected
* Central log transmission is fully customizable
---
## 🔧 Configuration Summary
| Param | Type | Description |
| --------------- | ------ | -------------------------------------------------- |
| `url` | `str` | Central server base URL |
| `room` | `str` | Logical group or org name |
| `endpoint` | `str` | HTTP endpoint for POST logs (default: `/api/logs`) |
| `headers` | `dict` | Extra headers to send (e.g. auth token) |
| `socketio` | `bool` | Whether to use Socket.IO instead of HTTP |
| `socketio_path` | `str` | Path to socket.io on the server |
---
## 📄 License
MIT License
---
## 🙋♂️ Author
Mugabo Gusenga
[logmachine.bufferpunk.com](https://logmachine.bufferpunk.com)
[GitHub](https://github.com/Scion-Kin/logmachine)
---
## ❤️ Contribute
PRs and issues are welcome!
This tool is built for devs who want **beautiful logs with distributed brains**.
Let’s make debugging fun again.
Raw data
{
"_id": null,
"home_page": null,
"name": "logmachine",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "logging, devtools, collaborative, open source, cli, json, ansi",
"author": null,
"author_email": "Mugabo Gusenga <mugabo@bufferpunk.com>",
"download_url": "https://files.pythonhosted.org/packages/ad/27/eb1d6a2df5b394b615b898e550a6d94ba47060d7281e8b5ad547483a21a2/logmachine-2.1.0.tar.gz",
"platform": null,
"description": "# \ud83e\udde0 logmachine 2.1.0\n\n> Collaborative, beautiful logging system for distributed developers\n\n**logmachine** helps teams log smarter. It\u2019s a fully pluggable logging system that supports colored output, JSON parsing, structured log forwarding via **HTTP or Socket.IO**, and log centralization \u2014 all from a standard Python logging interface.\n\n---\n\n## \ud83d\ude80 Features\n\n- \ud83d\udd25 **Color-coded terminal logs** (DEBUG, INFO, WARNING, ERROR, SUCCESS)\n- \ud83d\udce4 **Log forwarding** to a central HTTP or Socket.IO server\n- \ud83e\udeb5 **Custom log levels** (add your own with `.new_level(...)`)\n- \ud83d\udc65 **User identity tracking** for team-based logs\n- \ud83e\udde9 **Pluggable backends**: send logs to a central server or local files\n- \ud83d\udce6 **Simple JSON output** for web dashboards or collectors\n- \ud83e\uddfd Strips ANSI escape codes from logs for clean parsing\n- \ud83e\udde0 Automatically resolves usernames and saves them in `~/.cl_username`\n\n---\n\n## \u2699\ufe0f Installation\n\n```bash\npip install logmachine\n```\n\n---\n\n## \ud83e\uddf0 Usage\n\n### Basic Setup\n\n```python\nfrom logmachine import ContribLog\n\n# Create a simple logger without central logging\n# Providing a noon-empty string initializes the logger with that name, else the root logger is used to collect every single log in the python process.\nlogger = ContribLog(\"myapp\", debug_level=1)\n\nlogger.info(\"Hello, world!\")\nlogger.error(\"An error occurred!\")\nlogger.success(\"Operation completed successfully!\")\nlogger.debug(\"Debugging information here.\")\nlogger.warning(\"This is a warning message.\")\n```\n\n### With Central Logging (HTTP or Socket.IO)\n\n```python\nlogger_config = {\n \"url\": \"https://logmachine.bufferpunk.com\", # Base server URL\n \"room\": \"team_alpha\", # Your organization or room\n \"endpoint\": \"/api/logs\", # Optional, defaults to /api/logs\n \"headers\": {\"Authorization\": \"Bearer token\"},\n \"socketio\": True, # Set False to use HTTP\n \"socketio_path\": \"/api/socket.io/\" # Optional\n}\nlogger = ContribLog(\"with_central\", debug_level=0, central=logger_config, socketio=True)\nlogger.success(\"Central logging is working!\")\n```\n\n---\n\n## \ud83c\udfa8 Log Format\n\nEvery log includes:\n\n* \u2705 Username (resolved automatically or via server)\n* \ud83d\udcc1 Module directory\n* \u23f1\ufe0f Timestamp\n* \ud83d\udce6 Level (INFO, ERROR, etc.)\n* \ud83d\udcdd Message\n\nSample (terminal):\n\n```\n(username @ myapp) \ud83e\udd0c CL Timing: [ 2025-08-04T11:23:52 ]\n[ INFO ] Server started on port 8000\n\ud83c\udfc1\n```\n\n---\n\n## \ud83d\udee0\ufe0f Advanced\n\n### Add Your Own Log Level\n\n```python\nlog.new_level(\"CRITICAL_HACK\", 60)\nlog.critical_hack(\"Zero day found!\")\n```\n\n---\n\n## \ud83d\udce4 Parse & Export\n\n### Convert Logs to JSON\n\n```python\njson_logs = log.jsonifier()\nfor entry in json_logs:\n print(entry)\n```\n\n---\n\n## \ud83d\udce1 Central Server Compatibility\n\nTo use Socket.IO, your central server must support these events:\n\n* `log`: Receives log payloads: `{ room: string, data: object }`\n* `GET /api/get_username?base=localname`: Returns `{ \"username\": \"...\" }`\n\n---\n\n## \ud83e\udd16 Environment Variables\n\n* `CL_USERNAME`: Manually override detected username\n* Automatically stored in `~/.cl_username` for persistent identity\n\n---\n\n## \ud83d\udd10 Security\n\n* HTTP headers (e.g. `Authorization`) can be injected\n* Central log transmission is fully customizable\n\n---\n\n## \ud83d\udd27 Configuration Summary\n\n| Param | Type | Description |\n| --------------- | ------ | -------------------------------------------------- |\n| `url` | `str` | Central server base URL |\n| `room` | `str` | Logical group or org name |\n| `endpoint` | `str` | HTTP endpoint for POST logs (default: `/api/logs`) |\n| `headers` | `dict` | Extra headers to send (e.g. auth token) |\n| `socketio` | `bool` | Whether to use Socket.IO instead of HTTP |\n| `socketio_path` | `str` | Path to socket.io on the server |\n\n---\n\n## \ud83d\udcc4 License\n\nMIT License\n\n---\n\n## \ud83d\ude4b\u200d\u2642\ufe0f Author\n\nMugabo Gusenga\n[logmachine.bufferpunk.com](https://logmachine.bufferpunk.com)\n[GitHub](https://github.com/Scion-Kin/logmachine)\n\n---\n\n## \u2764\ufe0f Contribute\n\nPRs and issues are welcome!\nThis tool is built for devs who want **beautiful logs with distributed brains**.\nLet\u2019s make debugging fun again.\n",
"bugtrack_url": null,
"license": null,
"summary": "Collaborative, beautiful logging system for distributed developers",
"version": "2.1.0",
"project_urls": {
"Documentation": "https://github.com/Scion-Kin/logmachine",
"Homepage": "https://logmachine.bufferpunk.com",
"Source": "https://github.com/Scion-Kin/logmachine",
"Tracker": "https://github.com/Scion-Kin/logmachine/issues"
},
"split_keywords": [
"logging",
" devtools",
" collaborative",
" open source",
" cli",
" json",
" ansi"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4857f3357388e5e10ac839fb20d054a33e2cdf278e4e5774007923d24b981a07",
"md5": "36089feeb4cc4ec3ab07d3e0f04a0fdc",
"sha256": "58d6d4fb34aafe2bb554480ec2f7bf4c4af9ab3326a6e78a33191acfc38a8efd"
},
"downloads": -1,
"filename": "logmachine-2.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "36089feeb4cc4ec3ab07d3e0f04a0fdc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 7138,
"upload_time": "2025-08-04T13:38:48",
"upload_time_iso_8601": "2025-08-04T13:38:48.174595Z",
"url": "https://files.pythonhosted.org/packages/48/57/f3357388e5e10ac839fb20d054a33e2cdf278e4e5774007923d24b981a07/logmachine-2.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ad27eb1d6a2df5b394b615b898e550a6d94ba47060d7281e8b5ad547483a21a2",
"md5": "2628b220f3445d7674cb4f8370137e28",
"sha256": "78ad1fb5839ba03205c348eb899b810192e3bcb7df54cdeb1ec43ccc78ae314d"
},
"downloads": -1,
"filename": "logmachine-2.1.0.tar.gz",
"has_sig": false,
"md5_digest": "2628b220f3445d7674cb4f8370137e28",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 6894,
"upload_time": "2025-08-04T13:38:49",
"upload_time_iso_8601": "2025-08-04T13:38:49.709036Z",
"url": "https://files.pythonhosted.org/packages/ad/27/eb1d6a2df5b394b615b898e550a6d94ba47060d7281e8b5ad547483a21a2/logmachine-2.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-04 13:38:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Scion-Kin",
"github_project": "logmachine",
"github_not_found": true,
"lcname": "logmachine"
}
JSON
