bench get-app https://github.com/Aerele-RnD/optimus

[![Listed on Frappe Gems](https://frappegems.com/api/method/frappe_gems.seo.badge?app=Aerele-RnD%2Foptimus)](https://frappegems.com/gems/apps/Aerele-RnD/optimus)

Optimus

A flow-aware performance profiler for Frappe and ERPNext. Records a real business workflow (Sales Invoice save → submit → Delivery Note → submit → …), joins it with server resource state and browser-side timings, and produces two downloadable HTML reports you can actually act on: a Safe Report to share with a third-party dev shop without leaking customer data, and a Raw Report for internal debugging with full stack traces and SQL literals.

> Status: v0.7.0 — production-ready. MIT-licensed. 1281 tests in CI on every push (ruff + pytest matrix on Python 3.12 / 3.14). See the CHANGELOG for the full feature history, including the v0.7.0 rename from frappe_profiler → optimus. > > Design docs: apps/frappe_profiler_design/ holds the architecture deep-dive, spec history, and planning notes. The architecture rationale and extension points live in ARCHITECTURE.md.

---

Table of contents

• What it is
• What it isn't
• Install
• 60-second quickstart
• The customer → partner handoff
• Finding types
• How it works
• Dependencies
• Comparison with alternatives
• Production safety
• Scheduler-disabled sites
• Configuration
• Runtime flags
• Custom analyzers
• Verification checklist
• Troubleshooting
• Development
• Contributing
• License

---

What it is

• On-demand profiler for specific slow flows. You press Start, run your slow flow, press Stop, and get a report. No always-on overhead. No data egress. No external service.
• Flow-aware. Automatically captures the entire chain of HTTP requests and background jobs triggered by one business operation — e.g. a single Sales Invoice submit that enqueues GL posting, stock updates, and GST calculation shows up as one session, not four disconnected transactions. The only profiler that does this for Frappe.
• Customer-safe report. Safe mode replaces SQL literals with ?, strips docnames and filters from URLs, redacts headers and form data, and bleach-sanitizes any user-typed notes. Shareable with a third-party dev shop over email without leaking PII.
• ERPNext-native findings. N+1 detection blames erpnext/accounts/gl_entry.py:211 instead of frappe/database/database.py:sql. Findings know about Document hooks, permission queries, naming series, and child table patterns.
• Server + browser + infra in one report. v0.5.0 adds per-action CPU/RSS/DB pool/RQ queue snapshots and per-XHR timings with Web Vitals, joined to the matching recording by correlation header. You can tell code-slow from server-slow, and backend-slow from network-slow.

What it isn't

• Not always-on monitoring. If you need "alert me when production p95 regresses," use New Relic / Datadog / Sentry. We're opt-in and session-scoped by design.
• Not distributed tracing. We only see Frappe. A microservices architecture spanning Python + Go + Node needs OpenTelemetry.
• Not a replacement for frappe.recorder. We extend it — we reuse its SQL capture and stack walker unchanged, and add session tracking, multi-request joining, resource/frontend capture, and the analyze pipeline on top.

---

Install

cd ~/frappe-bench
bench get-app https://github.com//optimus.git
bench --site  install-app optimus
bench --site  migrate
bench restart

Tested on Frappe v16 with MariaDB and Redis. The app declares required_apps = ["frappe"] and has one external dependency (pyinstrument >= 4.6, < 6, pure-Python, no compiled extensions).

After install, a Optimus User role is created automatically. All existing System Managers are granted this role, and new System Managers get it automatically via a User.validate hook.

---

60-second quickstart

1. Open Desk. A bright red Profiler pill appears in the bottom-right corner.
2. Click it. A dialog asks for a label, an optional "Steps to Reproduce" note, and a Capture Python call tree toggle (leave on).
3. Click Start. The pill turns green and shows an elapsed timer.
4. Run your flow — save a Sales Invoice, submit it, wait for background jobs, whatever you want profiled.
5. Click the pill again to Stop. The pill turns orange ("Analyzing…") while the analyze pipeline runs (typically 2–15 seconds).
6. Click the pill once more (now blue, "Report ready") to jump to the session form.
7. Click Download Safe Report or Download Safe Report (PDF). Email it to whoever needs it.

That's the whole workflow. No configuration required.

---

The customer → partner handoff

This is the primary use case and the feature set is built around it.

Traditional workflow — how 90% of ERPNext performance debugging happens today:

> Customer: "Saving a Sales Invoice is slow." > Partner: "Can you check the slow query log?" > Customer: "..." > Partner: "Send me a screenshot." > (30 minutes of back-and-forth follow)

With optimus:

1. Customer records the slow flow (one dialog, one click, no technical knowledge required).
2. Customer downloads Safe Report from the session form. Safe mode redacts:
   • SQL literals → ?
   • Request headers (Authorization, Cookie, CSRF tokens, anything matching password|secret|token|api[-_]?key|card_number|cvv|ssn|aadhar|pan_number) → [REDACTED]
   • Form data → same redaction
   • URLs: /app/sales-invoice/SI-2026-00123/edit → /app/sales-invoice//edit; ?filters=[...], ?source_name=X → ?filters=?, ?source_name=?
   • User-typed notes → bleach-sanitized HTML (strips `