# Kode Kronical
High-performance Python library for automated performance monitoring and system metrics collection.
## Overview
Kode Kronical provides automated performance monitoring for Python applications with:
- **Function Performance Tracking**: Automatic timing and profiling of Python functions
- **System Metrics Collection**: Real-time CPU, memory, and process monitoring
- **Enhanced Exception Handling**: Detailed error context with system correlation
- **AWS Integration**: Automatic DynamoDB uploads with 30-day TTL
- **Web Dashboard**: Comprehensive visualization via kode-kronical-viewer
- **Zero Configuration**: Works out-of-the-box with sensible defaults
## Installation
```bash
pip install kode-kronical
```
## Quick Start
### 1. Basic Usage
```python
from kode_kronical import KodeKronical
import time
# Initialize the performance tracker
kode = KodeKronical()
# Use as decorator
@kode.time_it
def slow_function(n):
time.sleep(0.1)
return sum(range(n))
@kode.time_it(store_args=True)
def process_data(data, multiplier=2):
return [x * multiplier for x in data]
# Call your functions - performance data is automatically collected
result1 = slow_function(1000)
result2 = process_data([1, 2, 3, 4, 5])
```
### 2. Configuration (Optional)
Create a `.kode-kronical.yaml` file in your project directory:
```yaml
kode_kronical:
enabled: true
min_execution_time: 0.001
local:
enabled: true
data_dir: "./perf_data"
filters:
exclude_modules:
- "requests"
- "boto3"
```
### 3. View Results
**Automatic Data Collection:**
- **Local Mode**: Performance data saved to `./perf_data/` as JSON files
- **AWS Mode**: Data uploaded to DynamoDB on program exit
**Web Dashboard:**
Use the [kode-kronical-viewer](https://github.com/jeremycharlesgillespie/kode-kronical-viewer) for visualization:
- Performance overview and metrics
- Function-by-function analysis
- Historical trends and comparisons
- System correlation analysis
## Key Features
### Enhanced Exception Handling
Kode Kronical captures detailed error context including system state when exceptions occur. See [Exception Handling Guide](docs/exception-handling.md) for examples and configuration.
### System Monitoring Daemon
Background daemon for continuous system monitoring that correlates with application performance. See [Daemon Guide](docs/daemon-guide.md) for complete setup and troubleshooting.
### AWS Integration
Automatic upload to DynamoDB with optimized schema:
- 1-minute data intervals for production efficiency
- 30-day TTL for automatic cleanup
- Real-time dashboard updates
## API Summary
```python
from kode_kronical import KodeKronical
kode = KodeKronical()
# Decorator usage
@kode.time_it # Basic timing
@kode.time_it(store_args=True) # Store function arguments
@kode.time_it(tags=["critical"]) # Add custom tags
# Programmatic access
summary = kode.get_summary() # Get performance summary
results = kode.get_timing_results() # Get detailed results
config = kode.get_config_info() # Get configuration info
```
## REST API
When using with kode-kronical-viewer, these endpoints are available:
- `GET /api/performance/` - Performance data with filtering
- `GET /api/hostnames/` - Available hostnames
- `GET /api/functions/` - Function analysis data
## Documentation
- **[Daemon Guide](docs/daemon-guide.md)** - Complete system monitoring setup and troubleshooting
- **[Exception Handling Guide](docs/exception-handling.md)** - Enhanced error context and debugging
- **[AWS Setup Guide](docs/aws-setup.md)** - DynamoDB configuration and deployment
## License
MIT License - see LICENSE file for details.
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests: `pytest tests/`
5. Submit a pull request
## Support
- [GitHub Issues](https://github.com/jeremycharlesgillespie/kode-kronical/issues)
- [Documentation](https://github.com/jeremycharlesgillespie/kode-kronical)
Raw data
{
"_id": null,
"home_page": null,
"name": "kode-kronical",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "performance, profiling, monitoring, timing, benchmarking",
"author": null,
"author_email": "Jeremy Gillespie <metalgear386@googlemail.com>",
"download_url": "https://files.pythonhosted.org/packages/32/45/0910251f00c0e6d68769cdf6172e8f6ed149fa2c0b3b1860ded0509499b3/kode_kronical-0.3.1.tar.gz",
"platform": null,
"description": "# Kode Kronical\n\nHigh-performance Python library for automated performance monitoring and system metrics collection.\n\n## Overview\n\nKode Kronical provides automated performance monitoring for Python applications with:\n\n- **Function Performance Tracking**: Automatic timing and profiling of Python functions\n- **System Metrics Collection**: Real-time CPU, memory, and process monitoring \n- **Enhanced Exception Handling**: Detailed error context with system correlation\n- **AWS Integration**: Automatic DynamoDB uploads with 30-day TTL\n- **Web Dashboard**: Comprehensive visualization via kode-kronical-viewer\n- **Zero Configuration**: Works out-of-the-box with sensible defaults\n\n## Installation\n\n```bash\npip install kode-kronical\n```\n\n## Quick Start\n\n### 1. Basic Usage\n\n```python\nfrom kode_kronical import KodeKronical\nimport time\n\n# Initialize the performance tracker\nkode = KodeKronical()\n\n# Use as decorator\n@kode.time_it\ndef slow_function(n):\n time.sleep(0.1)\n return sum(range(n))\n\n@kode.time_it(store_args=True)\ndef process_data(data, multiplier=2):\n return [x * multiplier for x in data]\n\n# Call your functions - performance data is automatically collected\nresult1 = slow_function(1000)\nresult2 = process_data([1, 2, 3, 4, 5])\n```\n\n### 2. Configuration (Optional)\n\nCreate a `.kode-kronical.yaml` file in your project directory:\n\n```yaml\nkode_kronical:\n enabled: true\n min_execution_time: 0.001\n\nlocal:\n enabled: true\n data_dir: \"./perf_data\"\n\nfilters:\n exclude_modules:\n - \"requests\"\n - \"boto3\"\n```\n\n### 3. View Results\n\n**Automatic Data Collection:**\n- **Local Mode**: Performance data saved to `./perf_data/` as JSON files\n- **AWS Mode**: Data uploaded to DynamoDB on program exit\n\n**Web Dashboard:**\nUse the [kode-kronical-viewer](https://github.com/jeremycharlesgillespie/kode-kronical-viewer) for visualization:\n- Performance overview and metrics\n- Function-by-function analysis \n- Historical trends and comparisons\n- System correlation analysis\n\n## Key Features\n\n### Enhanced Exception Handling\nKode Kronical captures detailed error context including system state when exceptions occur. See [Exception Handling Guide](docs/exception-handling.md) for examples and configuration.\n\n### System Monitoring Daemon\nBackground daemon for continuous system monitoring that correlates with application performance. See [Daemon Guide](docs/daemon-guide.md) for complete setup and troubleshooting.\n\n### AWS Integration\nAutomatic upload to DynamoDB with optimized schema:\n- 1-minute data intervals for production efficiency\n- 30-day TTL for automatic cleanup\n- Real-time dashboard updates\n\n## API Summary\n\n```python\nfrom kode_kronical import KodeKronical\n\nkode = KodeKronical()\n\n# Decorator usage\n@kode.time_it # Basic timing\n@kode.time_it(store_args=True) # Store function arguments\n@kode.time_it(tags=[\"critical\"]) # Add custom tags\n\n# Programmatic access\nsummary = kode.get_summary() # Get performance summary\nresults = kode.get_timing_results() # Get detailed results\nconfig = kode.get_config_info() # Get configuration info\n```\n\n## REST API\n\nWhen using with kode-kronical-viewer, these endpoints are available:\n\n- `GET /api/performance/` - Performance data with filtering\n- `GET /api/hostnames/` - Available hostnames\n- `GET /api/functions/` - Function analysis data\n\n## Documentation\n\n- **[Daemon Guide](docs/daemon-guide.md)** - Complete system monitoring setup and troubleshooting\n- **[Exception Handling Guide](docs/exception-handling.md)** - Enhanced error context and debugging\n- **[AWS Setup Guide](docs/aws-setup.md)** - DynamoDB configuration and deployment\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Run tests: `pytest tests/`\n5. Submit a pull request\n\n## Support\n\n- [GitHub Issues](https://github.com/jeremycharlesgillespie/kode-kronical/issues)\n- [Documentation](https://github.com/jeremycharlesgillespie/kode-kronical)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A lightweight Python performance tracking library with automatic data collection and visualization",
"version": "0.3.1",
"project_urls": {
"Bug Tracker": "https://github.com/jeremycharlesgillespie/kode-kronical/issues",
"Documentation": "https://kode-kronical.readthedocs.io/",
"Homepage": "https://github.com/jeremycharlesgillespie/kode-kronical",
"Repository": "https://github.com/jeremycharlesgillespie/kode-kronical"
},
"split_keywords": [
"performance",
" profiling",
" monitoring",
" timing",
" benchmarking"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "408228f2c070ab006a19ddfa37cadbf3ee36a189bac5a01ff776800b7ff1697e",
"md5": "65dc9b9ae562764c65d3315d6e567b45",
"sha256": "3aed14bb25833e19e78430084ad6f4d6a2110ee63c5b1f166c6a0b53457dbbc4"
},
"downloads": -1,
"filename": "kode_kronical-0.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "65dc9b9ae562764c65d3315d6e567b45",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 54461,
"upload_time": "2025-08-18T22:03:40",
"upload_time_iso_8601": "2025-08-18T22:03:40.024983Z",
"url": "https://files.pythonhosted.org/packages/40/82/28f2c070ab006a19ddfa37cadbf3ee36a189bac5a01ff776800b7ff1697e/kode_kronical-0.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "32450910251f00c0e6d68769cdf6172e8f6ed149fa2c0b3b1860ded0509499b3",
"md5": "525fb8ec622b7831de20b1125e7a2305",
"sha256": "ad53a68b549cada3b45b4af7293d399c5b432c21f3f0e43361616686f2beb777"
},
"downloads": -1,
"filename": "kode_kronical-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "525fb8ec622b7831de20b1125e7a2305",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 51521,
"upload_time": "2025-08-18T22:03:41",
"upload_time_iso_8601": "2025-08-18T22:03:41.266470Z",
"url": "https://files.pythonhosted.org/packages/32/45/0910251f00c0e6d68769cdf6172e8f6ed149fa2c0b3b1860ded0509499b3/kode_kronical-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-18 22:03:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jeremycharlesgillespie",
"github_project": "kode-kronical",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "boto3",
"specs": [
[
">=",
"1.26.0"
]
]
},
{
"name": "omegaconf",
"specs": [
[
">=",
"2.3.0"
]
]
},
{
"name": "psutil",
"specs": [
[
">=",
"5.9.0"
]
]
},
{
"name": "Django",
"specs": [
[
">=",
"4.2.0"
]
]
},
{
"name": "djangorestframework",
"specs": [
[
">=",
"3.14.0"
]
]
}
],
"lcname": "kode-kronical"
}
JSON
