Setup guide

Run Flask Error Tracker yourself

You need Python 3.9 or newer. The only dependencies are Flask and PyYAML. Pick embedded mode for a single Flask app, or standalone mode to collect errors from many apps and stacks.

1 · Install

git clone https://github.com/<coming-soon>/flask-error-tracker
cd flask-error-tracker
pip install -e .            # add ".[dev]" for pytest

2a · Embed it in a Flask app

from flask import Flask
from flask_error_tracker import init_error_tracker

app = Flask(__name__)
init_error_tracker(app)          # dashboard at /error-log, JSON API at /api/errors

Unhandled exceptions are logged automatically as server errors. To log handled errors yourself, call the database directly:

from flask_error_tracker import get_error_db
import traceback

try:
    charge_card()
except Exception as e:
    get_error_db().log_error(category='api', error_type=type(e).__name__,
                             error_message=str(e), stack_trace=traceback.format_exc())
    raise

Options for init_error_tracker are url_prefix, catch_flask_errors (default on) and debug_button ('errors-only', 'always' or False).

2b · Or run it standalone

cp config.example.yaml config.yaml     # optional
python app.py --port 5100 --no-debug
# dashboard → http://localhost:5100/error-log

A Dockerfile is included. Mount the data/ directory as a volume so the SQLite database and saved settings survive rebuilds.

For local use without a login portal, set REQUIRE_AUTH=false. Don't use that setting on anything reachable from the internet.

3 · Send errors from other apps

Every stack posts JSON to /api/log-frontend-error. When ERROR_INGEST_TOKEN is set on the server, also send it as the X-Error-Ingest-Token header. Browsers using sendBeacon can't set headers, so they pass it as ?token= instead.

Browser: errors are captured automatically.

<script>
  window.ERROR_TRACKER_CONTEXT = {
    endpoint: 'https://errors.example.com/api/log-frontend-error',
    project_name: 'my-site',
  };
</script>
<script src="https://errors.example.com/error-tracker-static/error-collector.js"></script>

Node.js:

const FlaskErrorTracker = require('./clients/node');
const tracker = new FlaskErrorTracker({
  endpoint: process.env.ERROR_TRACKER_ENDPOINT,
  projectName: 'api',
  ingestToken: process.env.ERROR_TRACKER_TOKEN,
});

Anything else (curl, PHP, Go…):

curl -X POST https://errors.example.com/api/log-frontend-error \
  -H 'Content-Type: application/json' \
  -H "X-Error-Ingest-Token: $ERROR_TRACKER_TOKEN" \
  -d '{"errors":[{"error_type":"TypeError","error_message":"boom","project_name":"shop"}]}'

The repository also includes ready-made clients for Next.js and WordPress in clients/.

4 · Configure

Edit config.yaml (copy it from config.example.yaml) to set the database path, project name, domain, dashboard back-link, which categories are logged, and your own custom categories. On the standalone server, the signed-in owner can change the same settings on the /settings page without a restart.

error_logging:
  database_path: data/error_log.db
  project_name: my-app
  domain_url: https://myapp.com
  custom_categories:
    payments: "Payment Processing"

5 · Protect the standalone dashboard

Error logs often contain URLs, user input and stack traces, so never expose a dashboard without authentication. The standalone server includes a gate that checks signed sessions from a login portal. Configure it with these environment variables:

HD_SESSION_SECRET=…          # shared session-signing secret (required)
[email protected]   # who may open the dashboard
ERROR_INGEST_TOKEN=…         # shared secret for apps that post errors
LOGIN_PORTAL_URL=https://login.example.com/login

If you'd rather use another gate, such as Cloudflare Access or a reverse proxy with auth, put it in front of the service. The embedded Blueprint relies on your app's own authentication.