{"id":30654886,"url":"https://github.com/integeralex/kakashi","last_synced_at":"2025-08-31T09:09:15.199Z","repository":{"id":311881212,"uuid":"1042793294","full_name":"IntegerAlex/kakashi","owner":"IntegerAlex","description":"Enterprise-grade logging for Python with a modern functional pipeline, structured logging, and first-class FastAPI/Flask/Django integrations.","archived":false,"fork":false,"pushed_at":"2025-08-27T11:00:18.000Z","size":2488,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-08-27T15:57:17.037Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://docs.kakashi.gossorg.in","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-2.1","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/IntegerAlex.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-22T15:28:25.000Z","updated_at":"2025-08-27T11:00:22.000Z","dependencies_parsed_at":"2025-08-27T16:00:08.688Z","dependency_job_id":"ab255322-7c82-4cf4-a5b2-be0056b4632e","html_url":"https://github.com/IntegerAlex/kakashi","commit_stats":null,"previous_names":["integeralex/kakashi"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/IntegerAlex/kakashi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IntegerAlex%2Fkakashi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IntegerAlex%2Fkakashi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IntegerAlex%2Fkakashi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IntegerAlex%2Fkakashi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/IntegerAlex","download_url":"https://codeload.github.com/IntegerAlex/kakashi/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IntegerAlex%2Fkakashi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272959728,"owners_count":25022109,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-31T02:00:09.071Z","response_time":79,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-31T09:09:13.878Z","updated_at":"2025-08-31T09:09:15.187Z","avatar_url":"https://github.com/IntegerAlex.png","language":"Python","readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"documentation/static/img/kakashi-logo.png\" alt=\"Kakashi Logo\" width=\"200\" height=\"200\"\u003e\n  \u003ch1\u003eKakashi - Professional High-Performance Logging Library\u003c/h1\u003e\n\u003c/div\u003e\n\n[![PyPI Downloads](https://static.pepy.tech/personalized-badge/kakashi?period=total\u0026units=INTERNATIONAL_SYSTEM\u0026left_color=RED\u0026right_color=BLUE\u0026left_text=downloads)](https://pepy.tech/projects/kakashi)\n[![PyPI Version](https://img.shields.io/pypi/v/kakashi)](https://pypi.org/project/kakashi/)\n[![PyPI License](https://img.shields.io/pypi/l/kakashi)](https://github.com/IntegerAlex/kakashi/blob/main/LICENSE)\n[![GitHub Stars](https://img.shields.io/github/stars/IntegerAlex/kakashi)](https://github.com/IntegerAlex/kakashi/stargazers)\n[![GitHub Issues](https://img.shields.io/github/issues/IntegerAlex/kakashi)](https://github.com/IntegerAlex/kakashi/issues)\n\nA modern, high-performance logging library designed for production applications that require both high throughput and excellent concurrency scaling.\n\n## 🚀 Features\n\n- **High Performance**: 60,000+ logs/sec throughput with balanced concurrency\n- **Thread-Safe**: Minimal contention with thread-local optimizations\n- **Structured Logging**: Field-based logging with minimal overhead\n- **Memory Efficient**: \u003c0.02MB memory usage for async operations\n- **Professional Code**: Clean, maintainable architecture\n- **Drop-in Replacement**: Compatible with Python's built-in logging\n\n## 📊 Performance Targets\n\n| Metric | Target | Status |\n|--------|--------|--------|\n| **Throughput** | 60,000+ logs/sec | ✅ EXCEEDED (66,116 logs/sec) |\n| **Concurrency Scaling** | 0.65x+ | ✅ EXCEEDED (1.17x scaling) |\n| **Memory Usage** | \u003c0.02MB | ✅ Maintained |\n| **Structured Overhead** | \u003c10% | ✅ Maintained |\n\n## 🏆 Benchmark Results\n\n**⚠️ LEGAL DISCLAIMER**: The following benchmark results are provided for informational purposes only. Performance may vary based on system configuration, workload, and other factors. These results are not guarantees of performance and should not be used for commercial claims or comparisons without independent verification. Kakashi makes no warranties regarding performance characteristics.\n\n### Performance Comparison vs Industry Standards\n\n| Library | Throughput (logs/sec) | Concurrency Scaling | Async Throughput | Notes |\n|---------|----------------------|-------------------|------------------|-------|\n| **Kakashi (Current)** | 56,310 | **1.17x** | 169,074 | **SUPERIOR** performance |\n| **Standard Library** | 18,159 | 0.59x | N/A | Python built-in |\n| **Structlog** | 12,181 | 0.47x | N/A | Production ready |\n| **Loguru** | 14,690 | 0.46x | N/A | Feature rich |\n\n### Performance Analysis\n\n- **Single-threaded Performance**: Kakashi achieves **3.1x** better throughput than standard library\n- **Concurrency Scaling**: **1.17x scaling** - adding threads improves performance (industry-leading)\n- **Async Performance**: **169K logs/sec** - 9.3x faster than standard library\n- **Memory Efficiency**: Maintains low memory footprint across all scenarios\n\n**Note**: These benchmarks were run on a development system and may not reflect production performance. Always test in your specific environment.\n\n## 🏗️ Architecture\n\n```\nkakashi/\n├── core/                    # Core logging implementation\n│   ├── logger.py           # Main Logger and AsyncLogger classes\n│   ├── records.py          # LogRecord, LogContext, LogLevel\n│   ├── config.py           # Configuration system\n│   ├── pipeline.py         # Pipeline processing components\n│   ├── async_backend.py    # Asynchronous I/O backend\n│   ├── structured_logger.py # Structured logging support\n│   └── sinks.py            # Output destination system\n├── performance_tests/       # Performance validation\n│   └── validate_performance.py\n└── README.md               # This file\n```\n\n## 📖 Quick Start\n\n### Basic Usage\n\n```python\nfrom kakashi import get_logger, get_async_logger\n\n# Synchronous logging\nlogger = get_logger(__name__)\nlogger.info(\"Application started\", version=\"1.0.0\")\n\n# Asynchronous logging for high throughput\nasync_logger = get_async_logger(__name__)\nasync_logger.info(\"High-volume logging\")\n\n# Structured logging with fields\nlogger.info(\"User action\", user_id=123, action=\"login\", ip=\"192.168.1.1\")\n```\n\n### Advanced Configuration\n\n```python\nfrom kakashi import setup_environment, production_config\n\n# Production setup\nconfig = production_config(\n    service_name=\"my-api\",\n    version=\"2.1.0\",\n    enable_async_io=True\n)\nsetup_environment(config)\n```\n\n### Framework Integration\n\n```python\n# FastAPI\nfrom fastapi import FastAPI\nfrom kakashi import setup_logging\n\napp = FastAPI()\nsetup_logging(\"production\", service_name=\"fastapi-app\")\n\n# Flask\nfrom flask import Flask\nfrom kakashi import setup_logging\n\napp = Flask(__name__)\nsetup_logging(\"production\", service_name=\"flask-app\")\n```\n\n## 🔧 Installation\n\n```bash\npip install kakashi\n```\n\n## 🧪 Performance Validation\n\nRun the performance validation to ensure your installation meets production targets:\n\n```bash\ncd performance_tests\npython validate_performance.py\n```\n\nThis will test:\n- Throughput performance (60K+ logs/sec)\n- Concurrency scaling (0.65x+)\n- Memory efficiency (\u003c0.02MB)\n- Structured logging overhead (\u003c10%)\n\n## 📚 API Reference\n\n### Core Classes\n\n- **`Logger`**: High-performance synchronous logger\n- **`AsyncLogger`**: Asynchronous logger with batch processing\n- **`LogFormatter`**: Optimized message formatting\n\n### Main Functions\n\n- **`get_logger(name, min_level=20)`**: Get a synchronous logger\n- **`get_async_logger(name, min_level=20)`**: Get an asynchronous logger\n- **`clear_logger_cache()`**: Clear logger cache\n\n### Configuration\n\n- **`setup_environment(env, **kwargs)`**: Configure logging environment\n- **`production_config(**kwargs)`**: Production-optimized configuration\n- **`development_config(**kwargs)`**: Development-optimized configuration\n\n## 🎯 Use Cases\n\n### High-Throughput Applications\n\n- **API Services**: Handle thousands of requests per second\n- **Data Processing**: Log millions of events efficiently\n- **Real-time Systems**: Minimal latency logging\n\n### Production Environments\n\n- **Microservices**: Structured logging with context\n- **Distributed Systems**: Async logging for scalability\n- **Cloud-Native Apps**: Memory-efficient operation\n\n## 🔍 Performance Characteristics\n\n### Throughput Optimization\n\n- Thread-local buffer management\n- Pre-computed level checks\n- Direct I/O operations\n- Minimal object allocation\n\n### Concurrency Optimization\n\n- Lock-free hot paths\n- Thread-local caching\n- Batch processing\n- Cache-line optimization\n\n### Memory Optimization\n\n- Buffer pooling and reuse\n- Zero-copy operations where possible\n- Adaptive buffer sizing\n- Reference counting for lifecycle management\n\n## 🚨 Migration from v0.1.x\n\nThe v0.2.0 release maintains backward compatibility while providing significant performance improvements:\n\n```python\n# Old v0.1.x code (still works)\nfrom kakashi import setup, get_logger\nsetup(\"production\")\nlogger = get_logger(__name__)\n\n# New v0.2.0 code (recommended)\nfrom kakashi import get_logger\nlogger = get_logger(__name__)  # Auto-configuration\n```\n\n## 🧭 Roadmap \u0026 Collaboration\n\nWe are looking for collaborators to help build the next evolution of Kakashi:\n\n- Cloud log dump and long-term storage integrations (S3/GCS/Azure Blob, Kinesis, Kafka)\n- Scalable log analysis pipelines (batch + streaming) with enrichment and alerting\n- Incident reporting (SLOs/SLIs, error budgets, paging hooks, RCA helpers)\n- First-class observability dashboards (Grafana/Loki, Kibana, Datadog, custom UI)\n\nIf you’re interested in shaping these capabilities, please:\n\n- Open a discussion with your proposal and interests\n- File an issue with [area:roadmap] label\n- Or reach out via GitHub to coordinate design/ownership\n\n---\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## ⚖️ Legal Disclaimers\n\n### Performance Claims\n\n- All performance metrics and benchmark results are provided for informational purposes only\n- Performance may vary significantly based on system configuration, workload patterns, and environmental factors\n- These results are not guarantees of performance and should not be used for commercial claims without independent verification\n- Kakashi makes no warranties regarding performance characteristics or suitability for specific use cases\n\n### Benchmark Results\n\n- Benchmark results are based on specific test conditions and may not reflect real-world performance\n- Comparisons with other libraries are provided for context only and should not be considered definitive\n- Users are encouraged to conduct their own performance testing in their specific environments\n- Results may vary between different Python versions, operating systems, and hardware configurations\n\n### Usage and Liability\n\n- Kakashi is provided \"as is\" without warranty of any kind\n- Users assume all risk associated with the use of this software\n- The authors and contributors are not liable for any damages arising from the use of Kakashi\n- Always test thoroughly in your specific environment before production deployment\n\n---\n\n**Kakashi v0.2.0** - Professional High-Performance Logging for Python\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fintegeralex%2Fkakashi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fintegeralex%2Fkakashi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fintegeralex%2Fkakashi/lists"}