https://github.com/insighttrail/insighttrail
InsightTrail: Your all-in-one observability tool for Flask. Features a real-time web UI, automatic request/error tracing, structured JSON logging, and performance metrics. Easy to set up, powerful to use.
https://github.com/insighttrail/insighttrail
analytics-dashboard devtools flask flask-middleware logging logging-and-metrics logging-library monitoring observability python tracing
Last synced: 3 months ago
JSON representation
InsightTrail: Your all-in-one observability tool for Flask. Features a real-time web UI, automatic request/error tracing, structured JSON logging, and performance metrics. Easy to set up, powerful to use.
- Host: GitHub
- URL: https://github.com/insighttrail/insighttrail
- Owner: insightTrail
- License: mit
- Created: 2025-06-10T18:28:23.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-19T13:04:32.000Z (about 1 year ago)
- Last Synced: 2025-09-13T02:56:43.151Z (10 months ago)
- Topics: analytics-dashboard, devtools, flask, flask-middleware, logging, logging-and-metrics, logging-library, monitoring, observability, python, tracing
- Language: HTML
- Homepage:
- Size: 26.4 KB
- Stars: 1
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# InsightTrail
[](https://www.python.org/downloads/)
[](https://flask.palletsprojects.com/)
[](https://opensource.org/licenses/MIT)
## Overview
InsightTrail is a powerful yet lightweight observability middleware for Flask applications. It provides comprehensive logging, real-time metrics, and request tracing out of the box. Designed for developers who need to monitor, debug, and gain insights into their Flask microservices with minimal setup.
With its clean web UI, you can visualize analytics, inspect logs, and track down issues without leaving your browser.
## Key Features
- 🔍 **Request & Error Tracing**: Automatically generate unique trace IDs for each request and trace errors with full context.
- 📊 **Real-time Analytics UI**: A built-in web dashboard to visualize key metrics, inspect logs, and analyze application performance.
- 📝 **Structured JSON Logging**: Smart, structured logging with configurable log levels and automatic log rotation.
- 🚀 **Performance Metrics**: Capture response times, CPU/memory usage, and other system-level metrics for each request.
- 📦 **Dependency Tracking**: Monitor your project's dependencies and check for the latest versions.
- ✅ **Sensible Defaults**: Works out of the box with sane defaults, requiring no initial configuration.
- ⚙️ **Highly Configurable**: Customize logging, log file paths, UI access, and more to fit your needs.
## Installation
```bash
pip install insighttrail
```
Or install from source:
```bash
# Replace with your repository URL
git clone https://github.com/your-username/insighttrail.git
cd insighttrail
pip install -e .
```
## Quick Start
### Basic Usage
Simply wrap your Flask app with the `InsightTrailMiddleware`. It will automatically start logging to a file in your project's parent directory and enable the web UI.
```python
from flask import Flask
from insighttrail import InsightTrailMiddleware
app = Flask(__name__)
# Initialize InsightTrail with default settings
# Logs will be stored in ../logs/insighttrail.log
# The UI will be available at /insight
middleware = InsightTrailMiddleware(app)
@app.route('/')
def hello():
return 'Hello, World!'
if __name__ == '__main__':
app.run()
```
After running your app, navigate to `/insight` to view the analytics dashboard.
### Advanced Configuration
You can customize InsightTrail's behavior by passing parameters to the middleware.
```python
from flask import Flask
from insighttrail import InsightTrailMiddleware
app = Flask(__name__)
# Initialize InsightTrail with custom settings
middleware = InsightTrailMiddleware(
app,
log_file='path/to/your/logs/app.log',
log_level='DEBUG',
max_file_size=5 * 1024 * 1024, # 5MB
backup_count=10,
enable_ui=True,
url_prefix='/monitoring' # Access the UI at /monitoring
)
```
## Web UI
InsightTrail comes with a built-in web interface to visualize the data it collects. By default, it's available at the `/insight` endpoint of your application.
The UI provides:
- **Real-time Metrics**: View total requests, error rates, and average response times.
- **Log Viewer**: Search, filter, and inspect detailed, structured logs.
- **Error Analysis**: Examine exceptions with full stack traces and request context.
- **System Health**: Monitor CPU, memory, and disk usage.
## Configuration Options
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `log_file` | str | `None` | Path to the log file. If `None`, defaults to `logs/insighttrail.log` in the parent directory of the app's root path. |
| `log_level` | str | `'INFO'` | Minimum log level to capture (e.g., `'DEBUG'`, `'INFO'`, `'WARNING'`). |
| `max_file_size` | int | `1048576` (1MB) | Maximum size of the log file in bytes before rotation. |
| `backup_count` | int | `5` | Number of backup log files to keep. |
| `enable_ui` | bool | `True` | Enable or disable the web UI. |
| `url_prefix` | str | `'/insight'` | The URL prefix for the web UI endpoint. |
## Log Output Format
InsightTrail generates structured JSON logs, making them easy to parse and analyze.
```json
{
"trace_id": "a7b1c2d3-e4f5-g6h7-i8j9-k0l1m2n3o4p5",
"timestamp": "2024-07-29T12:34:56.789012",
"level": "INFO",
"request": {
"method": "GET",
"path": "/api/users",
"status": 200,
"duration_ms": 45.67,
"client": "127.0.0.1"
},
"runtime": { "...": "..." },
"system": { "...": "..." }
}
```
## Requirements
- Python 3.7 or higher
- Flask 2.x or higher
- Additional dependencies:
- blinker
- psutil
- werkzeug
## Contributing
Contributions are welcome! If you have a feature request, bug report, or want to improve the code, please feel free to submit an issue or a pull request.
## License
This project is licensed under the MIT License.
## Support
For support, please create an issue in the project's GitHub repository.