{"id":31539779,"url":"https://github.com/insighttrail/insighttrail","last_synced_at":"2026-03-27T04:44:54.022Z","repository":{"id":298365974,"uuid":"999755500","full_name":"insightTrail/insighttrail","owner":"insightTrail","description":"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.","archived":false,"fork":false,"pushed_at":"2025-06-19T13:04:32.000Z","size":27,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-13T02:56:43.151Z","etag":null,"topics":["analytics-dashboard","devtools","flask","flask-middleware","logging","logging-and-metrics","logging-library","monitoring","observability","python","tracing"],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/insightTrail.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"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-06-10T18:28:23.000Z","updated_at":"2025-06-21T15:14:07.000Z","dependencies_parsed_at":"2025-06-10T19:32:40.683Z","dependency_job_id":"00778fad-9a05-441c-bf56-97cb1023ddd6","html_url":"https://github.com/insightTrail/insighttrail","commit_stats":null,"previous_names":["insighttrail/insighttrail"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/insightTrail/insighttrail","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/insightTrail%2Finsighttrail","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/insightTrail%2Finsighttrail/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/insightTrail%2Finsighttrail/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/insightTrail%2Finsighttrail/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/insightTrail","download_url":"https://codeload.github.com/insightTrail/insighttrail/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/insightTrail%2Finsighttrail/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278290983,"owners_count":25962666,"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-10-04T02:00:05.491Z","response_time":63,"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":["analytics-dashboard","devtools","flask","flask-middleware","logging","logging-and-metrics","logging-library","monitoring","observability","python","tracing"],"created_at":"2025-10-04T09:14:48.120Z","updated_at":"2025-10-04T09:14:49.057Z","avatar_url":"https://github.com/insightTrail.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# InsightTrail\r\n\r\n[![Python Version](https://img.shields.io/badge/python-3.7%2B-blue.svg)](https://www.python.org/downloads/)\r\n[![Flask Version](https://img.shields.io/badge/flask-2.x%2B-green.svg)](https://flask.palletsprojects.com/)\r\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\r\n\r\n## Overview\r\nInsightTrail 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.\r\n\r\nWith its clean web UI, you can visualize analytics, inspect logs, and track down issues without leaving your browser.\r\n\r\n## Key Features\r\n- 🔍 **Request \u0026 Error Tracing**: Automatically generate unique trace IDs for each request and trace errors with full context.\r\n- 📊 **Real-time Analytics UI**: A built-in web dashboard to visualize key metrics, inspect logs, and analyze application performance.\r\n- 📝 **Structured JSON Logging**: Smart, structured logging with configurable log levels and automatic log rotation.\r\n- 🚀 **Performance Metrics**: Capture response times, CPU/memory usage, and other system-level metrics for each request.\r\n- 📦 **Dependency Tracking**: Monitor your project's dependencies and check for the latest versions.\r\n- ✅ **Sensible Defaults**: Works out of the box with sane defaults, requiring no initial configuration.\r\n- ⚙️ **Highly Configurable**: Customize logging, log file paths, UI access, and more to fit your needs.\r\n\r\n## Installation\r\n\r\n```bash\r\npip install insighttrail\r\n```\r\n\r\nOr install from source:\r\n\r\n```bash\r\n# Replace with your repository URL\r\ngit clone https://github.com/your-username/insighttrail.git\r\ncd insighttrail\r\npip install -e .\r\n```\r\n\r\n## Quick Start\r\n\r\n### Basic Usage\r\nSimply 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.\r\n\r\n```python\r\nfrom flask import Flask\r\nfrom insighttrail import InsightTrailMiddleware\r\n\r\napp = Flask(__name__)\r\n\r\n# Initialize InsightTrail with default settings\r\n# Logs will be stored in ../logs/insighttrail.log\r\n# The UI will be available at /insight\r\nmiddleware = InsightTrailMiddleware(app)\r\n\r\n@app.route('/')\r\ndef hello():\r\n    return 'Hello, World!'\r\n\r\nif __name__ == '__main__':\r\n    app.run()\r\n```\r\nAfter running your app, navigate to `/insight` to view the analytics dashboard.\r\n\r\n### Advanced Configuration\r\nYou can customize InsightTrail's behavior by passing parameters to the middleware.\r\n\r\n```python\r\nfrom flask import Flask\r\nfrom insighttrail import InsightTrailMiddleware\r\n\r\napp = Flask(__name__)\r\n\r\n# Initialize InsightTrail with custom settings\r\nmiddleware = InsightTrailMiddleware(\r\n    app,\r\n    log_file='path/to/your/logs/app.log',\r\n    log_level='DEBUG',\r\n    max_file_size=5 * 1024 * 1024,  # 5MB\r\n    backup_count=10,\r\n    enable_ui=True,\r\n    url_prefix='/monitoring' # Access the UI at /monitoring\r\n)\r\n```\r\n\r\n## Web UI\r\nInsightTrail 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.\r\n\r\nThe UI provides:\r\n- **Real-time Metrics**: View total requests, error rates, and average response times.\r\n- **Log Viewer**: Search, filter, and inspect detailed, structured logs.\r\n- **Error Analysis**: Examine exceptions with full stack traces and request context.\r\n- **System Health**: Monitor CPU, memory, and disk usage.\r\n\r\n## Configuration Options\r\n\r\n| Parameter | Type | Default | Description |\r\n|-----------|------|---------|-------------|\r\n| `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. |\r\n| `log_level` | str | `'INFO'` | Minimum log level to capture (e.g., `'DEBUG'`, `'INFO'`, `'WARNING'`). |\r\n| `max_file_size` | int | `1048576` (1MB) | Maximum size of the log file in bytes before rotation. |\r\n| `backup_count` | int | `5` | Number of backup log files to keep. |\r\n| `enable_ui` | bool | `True` | Enable or disable the web UI. |\r\n| `url_prefix` | str | `'/insight'` | The URL prefix for the web UI endpoint. |\r\n\r\n## Log Output Format\r\nInsightTrail generates structured JSON logs, making them easy to parse and analyze.\r\n\r\n```json\r\n{\r\n    \"trace_id\": \"a7b1c2d3-e4f5-g6h7-i8j9-k0l1m2n3o4p5\",\r\n    \"timestamp\": \"2024-07-29T12:34:56.789012\",\r\n    \"level\": \"INFO\",\r\n    \"request\": {\r\n        \"method\": \"GET\",\r\n        \"path\": \"/api/users\",\r\n        \"status\": 200,\r\n        \"duration_ms\": 45.67,\r\n        \"client\": \"127.0.0.1\"\r\n    },\r\n    \"runtime\": { \"...\": \"...\" },\r\n    \"system\": { \"...\": \"...\" }\r\n}\r\n```\r\n\r\n## Requirements\r\n\r\n- Python 3.7 or higher\r\n- Flask 2.x or higher\r\n- Additional dependencies:\r\n  - blinker\r\n  - psutil\r\n  - werkzeug\r\n\r\n## Contributing\r\nContributions 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.\r\n\r\n## License\r\nThis project is licensed under the MIT License.\r\n\r\n## Support\r\nFor support, please create an issue in the project's GitHub repository.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finsighttrail%2Finsighttrail","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finsighttrail%2Finsighttrail","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finsighttrail%2Finsighttrail/lists"}