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.

• 🔍 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.

pip install insighttrail

Or install from source:

# Replace with your repository URL
git clone https://github.com/your-username/insighttrail.git
cd insighttrail
pip install -e .

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.

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.

You can customize InsightTrail's behavior by passing parameters to the middleware.

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
)

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.

InsightTrail generates structured JSON logs, making them easy to parse and analyze.

{
    "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": { "...": "..." }
}

• Python 3.7 or higher
• Flask 2.x or higher
• Additional dependencies:
  • blinker
  • psutil
  • werkzeug

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.

This project is licensed under the MIT License.

For support, please create an issue in the project's GitHub repository.