# Hy Structured Logging
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://github.com/hylang/hy)
A comprehensive structured logging package for [Hy](https://github.com/hylang/hy) that provides JSON-formatted logging with support for contexts, child loggers, decorators, and more. Perfect for building observable, debuggable applications in Lisp on the Python platform.
## Features
- **Structured Output** - JSON and text format output support for easy parsing and analysis
- **Context Management** - Context-aware logging with nested contexts that propagate to child loggers
- **Hierarchical Loggers** - Create child loggers with inherited configuration and context
- **Function Decorators** - Automatic logging for function entry/exit and performance tracking
- **Request Tracking** - Built-in request ID generation and tracking across log entries
- **Flexible Configuration** - Configurable log levels, formats, and filtering
- **Thread-Safe** - Safe for use in concurrent and multi-threaded applications
- **AI Integration** - Claude subagent for intelligent log analysis and debugging assistance
- **Framework Integration** - Ready-to-use integrations for CherryPy and SQLObject
- **Performance Utilities** - Built-in Timer, retry mechanisms, and memoization helpers
## Installation
### From PyPI (when published)
```bash
pip install hy-structured-logging
```
### From Source
```bash
# Clone the repository
git clone https://github.com/jaymd96/hy-structured-logging.git
cd hy-structured-logging
# Install in development mode
pip install -e .
# Or build and install
python -m build
pip install dist/*.whl
```
## Quick Start
### Basic Usage (Hy)
```hy
(import hy-structured-logging.structured-logging :as log)
;; Initialize logging
(log.init-logging :level "INFO" :format "json")
;; Log messages with structured data
(log.info "User logged in" {"user_id" "123" "ip" "192.168.1.1"})
(log.warning "High memory usage" {"percent" 85 "threshold" 80})
(log.error "Database connection failed" {"retry_count" 3 "error" "timeout"})
```
### Python Integration
The package works seamlessly from Python:
```python
import hy
from hy_structured_logging import structured_logging as log
# Initialize and use just like from Hy
log.init_logging(level="INFO", format="json")
log.info("Processing started", {"items": 100, "batch_id": "abc123"})
with log.with_context({"request_id": "req-001"}):
log.info("Handling request", {"endpoint": "/api/users"})
```
### Context Management
```hy
;; Add persistent context that applies to all subsequent logs
(log.with-context {"service" "api" "version" "1.0.0"}
(log.info "Service started" {})
;; Nested contexts
(log.with-context {"request_id" "req-123"}
(log.info "Processing request" {"method" "GET"})
(log.info "Request completed" {"status" 200})))
```
### Using the Batteries Module
```hy
(import hy-structured-logging.batteries :as batteries)
;; Timer for performance tracking
(let [timer (batteries.Timer "data-processing")]
(with [t timer]
;; Your code here
(process-data))
(log.info "Processing complete" {"duration_ms" (* (.elapsed timer) 1000)}))
;; Retry mechanism
(batteries.with-retry
(fn [] (fetch-data-from-api))
:max-attempts 3
:delay 1.0)
;; Memoization
(setv cached-fn (batteries.memoize expensive-calculation))
```
## Advanced Features
### Child Loggers
Create specialized loggers for different components:
```hy
(setv db-logger (log.get-child-logger "database"))
(setv api-logger (log.get-child-logger "api"))
(.info db-logger "Query executed" {"query" "SELECT * FROM users" "rows" 42})
(.info api-logger "Request received" {"endpoint" "/users" "method" "GET"})
```
### Function Decorators
Automatically log function calls:
```hy
(import hy-structured-logging.structured-logging [log-execution])
(defn [log-execution] process-payment [amount user-id]
;; Function automatically logs entry and exit
(charge-card amount user-id))
```
### AI-Powered Analysis
Use the Claude subagent for intelligent log analysis:
```hy
(import hy-structured-logging.claude-subagent :as subagent)
;; Analyze logs for patterns
(subagent.analyze-logs "/var/log/app.log"
:pattern "error"
:time-range "1h")
;; Get debugging suggestions
(subagent.suggest-fix "Database connection timeout errors")
```
## Demo Scripts
Explore the `demo/` directory for comprehensive examples:
- `demo/basic_usage.hy` - Core features demonstration in Hy
- `demo/advanced_usage.py` - Advanced Python integration examples
Run demos:
```bash
hy demo/basic_usage.hy
python demo/advanced_usage.py
```
## Development
### Task Runner
The project includes a [PyDoit](https://pydoit.org/) task runner written in Hy:
```bash
# List all available tasks
hy dodo.hy list
# Run tests
hy dodo.hy test
# Build distribution packages
hy dodo.hy build
# Run demos
hy dodo.hy demo
# Upload to PyPI (when ready)
hy dodo.hy upload
```
### Running Tests
```bash
# Run all tests
hy test_structured_logging.hy
hy test_claude_subagent.hy
# Or use the task runner
hy dodo.hy test
```
## Project Structure
```
hy-structured-logging/
├── hy_structured_logging/ # Main package
│ ├── __init__.hy
│ ├── structured_logging.hy # Core logging functionality
│ ├── structured_logging_config.hy # Configuration management
│ ├── batteries.hy # Utility functions and helpers
│ ├── claude_subagent.hy # AI integration
│ └── integrations/ # Framework integrations
│ ├── cherrypy.hy
│ └── sqlobject.hy
├── demo/ # Demo scripts
│ ├── basic_usage.hy
│ └── advanced_usage.py
├── test_*.hy # Test files
├── dodo.hy # Task runner
└── pyproject.toml # Package configuration
```
## Configuration
### Log Levels
- `DEBUG` - Detailed diagnostic information
- `INFO` - General informational messages
- `WARNING` - Warning messages for potential issues
- `ERROR` - Error messages for failures
- `CRITICAL` - Critical issues requiring immediate attention
### Output Formats
- `json` - Structured JSON output (recommended for production)
- `text` - Human-readable text format (useful for development)
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Acknowledgments
- Built with [Hy](https://github.com/hylang/hy) - A Lisp dialect embedded in Python
- Inspired by structured logging best practices from the Python ecosystem
- AI integration powered by Claude
## Support
For issues, questions, or suggestions, please [open an issue](https://github.com/jaymd96/hy-structured-logging/issues) on GitHub.
## Author
**Jay MD** - [jaymd96](https://github.com/jaymd96)
---
Made with ❤️ and Lisp
Raw data
{
"_id": null,
"home_page": null,
"name": "hy-structured-logging",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "logging, structured-logging, json, hy, lisp",
"author": null,
"author_email": "Jay MD <jaymd96@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/76/f6/45429f7b6c5945fa82ddd1ec5f948ae09a4be95afa82f4d1cf79d9030f64/hy_structured_logging-1.0.1.tar.gz",
"platform": null,
"description": "# Hy Structured Logging\n\n[](https://opensource.org/licenses/MIT)\n[](https://www.python.org/downloads/)\n[](https://github.com/hylang/hy)\n\nA comprehensive structured logging package for [Hy](https://github.com/hylang/hy) that provides JSON-formatted logging with support for contexts, child loggers, decorators, and more. Perfect for building observable, debuggable applications in Lisp on the Python platform.\n\n## Features\n\n- **Structured Output** - JSON and text format output support for easy parsing and analysis\n- **Context Management** - Context-aware logging with nested contexts that propagate to child loggers\n- **Hierarchical Loggers** - Create child loggers with inherited configuration and context\n- **Function Decorators** - Automatic logging for function entry/exit and performance tracking\n- **Request Tracking** - Built-in request ID generation and tracking across log entries\n- **Flexible Configuration** - Configurable log levels, formats, and filtering\n- **Thread-Safe** - Safe for use in concurrent and multi-threaded applications\n- **AI Integration** - Claude subagent for intelligent log analysis and debugging assistance\n- **Framework Integration** - Ready-to-use integrations for CherryPy and SQLObject\n- **Performance Utilities** - Built-in Timer, retry mechanisms, and memoization helpers\n\n## Installation\n\n### From PyPI (when published)\n```bash\npip install hy-structured-logging\n```\n\n### From Source\n```bash\n# Clone the repository\ngit clone https://github.com/jaymd96/hy-structured-logging.git\ncd hy-structured-logging\n\n# Install in development mode\npip install -e .\n\n# Or build and install\npython -m build\npip install dist/*.whl\n```\n\n## Quick Start\n\n### Basic Usage (Hy)\n\n```hy\n(import hy-structured-logging.structured-logging :as log)\n\n;; Initialize logging\n(log.init-logging :level \"INFO\" :format \"json\")\n\n;; Log messages with structured data\n(log.info \"User logged in\" {\"user_id\" \"123\" \"ip\" \"192.168.1.1\"})\n(log.warning \"High memory usage\" {\"percent\" 85 \"threshold\" 80})\n(log.error \"Database connection failed\" {\"retry_count\" 3 \"error\" \"timeout\"})\n```\n\n### Python Integration\n\nThe package works seamlessly from Python:\n\n```python\nimport hy\nfrom hy_structured_logging import structured_logging as log\n\n# Initialize and use just like from Hy\nlog.init_logging(level=\"INFO\", format=\"json\")\n\nlog.info(\"Processing started\", {\"items\": 100, \"batch_id\": \"abc123\"})\n\nwith log.with_context({\"request_id\": \"req-001\"}):\n log.info(\"Handling request\", {\"endpoint\": \"/api/users\"})\n```\n\n### Context Management\n\n```hy\n;; Add persistent context that applies to all subsequent logs\n(log.with-context {\"service\" \"api\" \"version\" \"1.0.0\"}\n (log.info \"Service started\" {})\n \n ;; Nested contexts\n (log.with-context {\"request_id\" \"req-123\"}\n (log.info \"Processing request\" {\"method\" \"GET\"})\n (log.info \"Request completed\" {\"status\" 200})))\n```\n\n### Using the Batteries Module\n\n```hy\n(import hy-structured-logging.batteries :as batteries)\n\n;; Timer for performance tracking\n(let [timer (batteries.Timer \"data-processing\")]\n (with [t timer]\n ;; Your code here\n (process-data))\n (log.info \"Processing complete\" {\"duration_ms\" (* (.elapsed timer) 1000)}))\n\n;; Retry mechanism\n(batteries.with-retry \n (fn [] (fetch-data-from-api))\n :max-attempts 3\n :delay 1.0)\n\n;; Memoization\n(setv cached-fn (batteries.memoize expensive-calculation))\n```\n\n## Advanced Features\n\n### Child Loggers\n\nCreate specialized loggers for different components:\n\n```hy\n(setv db-logger (log.get-child-logger \"database\"))\n(setv api-logger (log.get-child-logger \"api\"))\n\n(.info db-logger \"Query executed\" {\"query\" \"SELECT * FROM users\" \"rows\" 42})\n(.info api-logger \"Request received\" {\"endpoint\" \"/users\" \"method\" \"GET\"})\n```\n\n### Function Decorators\n\nAutomatically log function calls:\n\n```hy\n(import hy-structured-logging.structured-logging [log-execution])\n\n(defn [log-execution] process-payment [amount user-id]\n ;; Function automatically logs entry and exit\n (charge-card amount user-id))\n```\n\n### AI-Powered Analysis\n\nUse the Claude subagent for intelligent log analysis:\n\n```hy\n(import hy-structured-logging.claude-subagent :as subagent)\n\n;; Analyze logs for patterns\n(subagent.analyze-logs \"/var/log/app.log\" \n :pattern \"error\"\n :time-range \"1h\")\n\n;; Get debugging suggestions\n(subagent.suggest-fix \"Database connection timeout errors\")\n```\n\n## Demo Scripts\n\nExplore the `demo/` directory for comprehensive examples:\n\n- `demo/basic_usage.hy` - Core features demonstration in Hy\n- `demo/advanced_usage.py` - Advanced Python integration examples\n\nRun demos:\n```bash\nhy demo/basic_usage.hy\npython demo/advanced_usage.py\n```\n\n## Development\n\n### Task Runner\n\nThe project includes a [PyDoit](https://pydoit.org/) task runner written in Hy:\n\n```bash\n# List all available tasks\nhy dodo.hy list\n\n# Run tests\nhy dodo.hy test\n\n# Build distribution packages\nhy dodo.hy build\n\n# Run demos\nhy dodo.hy demo\n\n# Upload to PyPI (when ready)\nhy dodo.hy upload\n```\n\n### Running Tests\n\n```bash\n# Run all tests\nhy test_structured_logging.hy\nhy test_claude_subagent.hy\n\n# Or use the task runner\nhy dodo.hy test\n```\n\n## Project Structure\n\n```\nhy-structured-logging/\n\u251c\u2500\u2500 hy_structured_logging/ # Main package\n\u2502 \u251c\u2500\u2500 __init__.hy\n\u2502 \u251c\u2500\u2500 structured_logging.hy # Core logging functionality\n\u2502 \u251c\u2500\u2500 structured_logging_config.hy # Configuration management\n\u2502 \u251c\u2500\u2500 batteries.hy # Utility functions and helpers\n\u2502 \u251c\u2500\u2500 claude_subagent.hy # AI integration\n\u2502 \u2514\u2500\u2500 integrations/ # Framework integrations\n\u2502 \u251c\u2500\u2500 cherrypy.hy\n\u2502 \u2514\u2500\u2500 sqlobject.hy\n\u251c\u2500\u2500 demo/ # Demo scripts\n\u2502 \u251c\u2500\u2500 basic_usage.hy\n\u2502 \u2514\u2500\u2500 advanced_usage.py\n\u251c\u2500\u2500 test_*.hy # Test files\n\u251c\u2500\u2500 dodo.hy # Task runner\n\u2514\u2500\u2500 pyproject.toml # Package configuration\n```\n\n## Configuration\n\n### Log Levels\n- `DEBUG` - Detailed diagnostic information\n- `INFO` - General informational messages\n- `WARNING` - Warning messages for potential issues\n- `ERROR` - Error messages for failures\n- `CRITICAL` - Critical issues requiring immediate attention\n\n### Output Formats\n- `json` - Structured JSON output (recommended for production)\n- `text` - Human-readable text format (useful for development)\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- Built with [Hy](https://github.com/hylang/hy) - A Lisp dialect embedded in Python\n- Inspired by structured logging best practices from the Python ecosystem\n- AI integration powered by Claude\n\n## Support\n\nFor issues, questions, or suggestions, please [open an issue](https://github.com/jaymd96/hy-structured-logging/issues) on GitHub.\n\n## Author\n\n**Jay MD** - [jaymd96](https://github.com/jaymd96)\n\n---\n\nMade with \u2764\ufe0f and Lisp\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A structured logging package for Hy with JSON output support",
"version": "1.0.1",
"project_urls": {
"Homepage": "https://github.com/jaymd96/hy-structured-logging",
"Issues": "https://github.com/jaymd96/hy-structured-logging/issues",
"Repository": "https://github.com/jaymd96/hy-structured-logging"
},
"split_keywords": [
"logging",
" structured-logging",
" json",
" hy",
" lisp"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "58c7626fb3b2a5a147ab22399b54b4c3103f7608e7fac585cb9366a7dcd017e5",
"md5": "e7f4679151db6982c75112d665aff107",
"sha256": "2c65c93ac1d020495dc408cc691f94a8998e3eb91480914981861bf51026e3a2"
},
"downloads": -1,
"filename": "hy_structured_logging-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e7f4679151db6982c75112d665aff107",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 27604,
"upload_time": "2025-08-31T21:13:37",
"upload_time_iso_8601": "2025-08-31T21:13:37.352469Z",
"url": "https://files.pythonhosted.org/packages/58/c7/626fb3b2a5a147ab22399b54b4c3103f7608e7fac585cb9366a7dcd017e5/hy_structured_logging-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "76f645429f7b6c5945fa82ddd1ec5f948ae09a4be95afa82f4d1cf79d9030f64",
"md5": "5624e7e66fce4fa0e26052481a74df10",
"sha256": "09d84608dc3e420e1b9dcf10eee167dda13a21201919ecaa1c3bbbe03575700b"
},
"downloads": -1,
"filename": "hy_structured_logging-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "5624e7e66fce4fa0e26052481a74df10",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 29664,
"upload_time": "2025-08-31T21:13:38",
"upload_time_iso_8601": "2025-08-31T21:13:38.757733Z",
"url": "https://files.pythonhosted.org/packages/76/f6/45429f7b6c5945fa82ddd1ec5f948ae09a4be95afa82f4d1cf79d9030f64/hy_structured_logging-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-31 21:13:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jaymd96",
"github_project": "hy-structured-logging",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "hy",
"specs": [
[
">=",
"0.28.0"
]
]
}
],
"lcname": "hy-structured-logging"
}
JSON
