Hy Structured Logging

A comprehensive structured logging package for 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)

pip install hy-structured-logging

From Source

# 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)

(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:

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

;; 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

(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:

(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:

(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:

(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:

hy demo/basic_usage.hy
python demo/advanced_usage.py

Development

Task Runner

The project includes a PyDoit task runner written in Hy:

# 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

# 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 file for details.

Acknowledgments

• Built with 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 on GitHub.

Author

Jay MD - jaymd96

---

Made with ❤️ and Lisp