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.12.26 — production-ready. MIT-licensed. 1820 unit tests + 39 integration tests in CI on every push (ruff + pytest on Python 3.14; bench-driven integration suite on Frappe v16). See the CHANGELOG for the full feature history, including the v0.7.0 rename from frappe_profiler → optimus.

• What it is
• What it isn't
• Install
• 60-second quickstart
• Using Optimus
• The customer → partner handoff
• Finding types
• How it works
• Dependencies
• Comparison with alternatives
• Production safety
• Scheduler-disabled sites
• Configuration — Optimus Settings (DocType)
  • General tab
  • Analysis tab
  • AI Fix Suggestions tab
• Configuration — site_config.json (operator knobs)
• Runtime flags
• Custom analyzers
• Verification checklist
• Troubleshooting
• Development
• Contributing
• License

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

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

cd ~/frappe-bench
bench get-app https://github.com/Aerele-RnD/optimus.git
bench --site <your-site> install-app optimus
bench restart

Tested on Frappe v16 with MariaDB and Redis. The app declares required_apps = ["frappe"]. Runtime dependencies (installed automatically by bench get-app) are listed in pyproject.toml — currently pyinstrument, line_profiler, requests, sqlparse, and Jinja2, all pure-Python with no compiled extensions (line_profiler ships a small C extension; pre-built wheels exist for cpython 3.10–3.14).

After install, an 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.

After every upgrade: run bench restart so the new sign / verify code loads. Sessions captured before the restart have null call trees on their actions — their Phase-2 picker dialog opens with a yellow "No curated functions available" callout pointing this out. Capture a fresh session after the restart for a working picker.

1. Open Desk. A bright red Optimus 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 bottom-right widget is the only control surface a regular user needs. Its color reflects state:

The widget is only shown to users with the Optimus User role. System Managers receive it automatically; you can grant it to other users via User → Roles.

The Start dialog lets you set:

• Label — what shows up in the session list. Pick something searchable (SI submit, 100 items beats test).
• Steps to Reproduce / Notes — a rich-text block. Rendered at the top of both reports. Use it to give context to whoever reads the report ("Customer says save takes 8s; happens on every SI ≥ 50 items").
• Capture Python call tree — leave on for actionable findings. Turning it off gives you the v0.2.0 SQL-only behavior (~10–30% overhead instead of 1.5–2×), useful only when you specifically want to verify a SQL-level hypothesis without Python overhead.

Every session lands as an Optimus Session row. The form has three read-only sections:

1. Status + timing — Recording / Analyzing / Ready / Failed; start time; analyze wall-clock duration; counts of actions and findings.
2. Reports — two file links plus action buttons:
   • Download Safe Report / Open Safe Report — the customer- safe HTML. Email-shareable.
   • Download Raw Report / Open Raw Report — the un-redacted version. Hidden from non-admins; the link itself is permission- gated server-side, so guessing the file name does not bypass it.
   • Re-analyze — re-runs the analyze pipeline from the captured recordings (which live in Redis for 10 minutes after Stop). Useful when a session ends Failed because of a transient error. After 10 minutes the recordings are gone — re-analyze can still re-render reports from the persisted DocType data, but cannot recompute findings.
   • Regenerate Reports — re-renders both HTML files from the persisted Action/Finding rows. Cheaper than a full re-analyze; useful after an Optimus upgrade that improves the renderer.
   • Phase 2 → Line Profile — opens the picker dialog (see below).
   • Pin as Baseline / Unpin Baseline — see Baseline comparison below.
3. Captured actions + findings — child tables you can drill into without opening the report.

Both reports render from the same templates/report.html and the same persisted data — Safe mode is a renderer-time redaction pass, not a separate capture.

The default capture (Phase 1) tells you which functions are hot. Phase 2 tells you which lines inside those functions are hot. Use it when Phase 1 surfaces a hot path and you can't tell from reading the function which line is doing the work.

Workflow:

1. Open a Ready session, click Phase 2 → Line Profile.
2. The picker dialog shows curated candidates from Phase 1's call tree. Functions consuming ≥ 50 ms are pre-ticked as recommended.
3. Auto-expand hot chain (ticked by default) walks each pick down the call tree to instrument the full chain, not just the entry frame.
4. Click Start Phase 2 — the widget switches back to recording mode.
5. Re-execute the same flow you profiled in Phase 1.
6. Click Stop. Phase 2 analyze runs; the report adds a Line-Level Drilldown section with per-line hit-count and time.

Phase 2 has a per-request overhead budget (default 10s; tunable via optimus_phase2_overhead_budget_seconds in site_config). If the budget expires mid-request, line profiling disengages so the request finishes at natural speed, and the run is flagged "partial data". This stops a hot-loop pick from freezing the UI.

Optimus can call an LLM (Anthropic, OpenAI, Kimi, or any OpenAI- compatible endpoint including local ones like Ollama or LM Studio) to suggest concrete fixes for each finding. Off by default — no traffic leaves your bench until you enable it.

Three feature toggles, all under Optimus Settings → AI Fix Suggestions → Use the LLM for:

• Fix suggestions on findings — adds a "Suggest a fix (AI)" button per finding and an auto-suggest pass during analyze (when the auto-suggest checkbox below is on).
• Index recommendations — adds a "Suggest an index (AI)" button to the per-table breakdown.
• Humanized "Steps to Reproduce" — rewrites the auto-captured action list into a friendly flow ("Open Sales Invoice list, click New, …").

Turning any one of these off is a hard disable — the button is hidden, the API refuses, and re-rendered reports omit the AI block. See docs/AI-FIXING.md for the per-pathway data inventory and local-LLM recipes.

You're not done until the customer agrees the fix worked. Optimus's baseline comparison gives you a side-by-side report:

1. On a Ready "before" session, click Pin as Baseline.
2. Capture a "after" session of the same flow (same label is convenient but not required — the comparison matches actions by label, falling back to path).
3. Open the after-session's Safe or Raw report. Three new sections appear at the top:
   • Session-level delta — total wall time, query count, SQL/Python ms, with old → new.
   • Per-action comparison — matched actions with before/after stats.
   • Findings compared to baseline — Fixed / New / Unchanged with delta.
4. The customer signs off on concrete numbers, not "it feels faster".

To swap the baseline, unpin the old one and pin the new one.

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/<name>/edit; ?filters=[...], ?source_name=X → ?filters=?, ?source_name=?
   • User-typed notes → bleach-sanitized HTML (strips <script>, onclick, javascript: URLs)
   • Python function names from custom apps → my_acme_app:discounts (app-level, not module-level)
   • SQL identifiers (table/column/function names) are NOT redacted — they're code, not customer data
3. Customer emails the .html or .pdf to the partner. No VPN, no SSH, no shared credentials.
4. Partner opens the file on their laptop offline. The report is fully self-contained — no CDN fonts, no external scripts, no @import. Tested in CI via test_safe_report_self_contained.py.
5. Partner diagnoses and fixes. Every finding has a plain-language customer_description, a technical detail with callsite + query + suggested DDL, and an estimated impact in ms.
6. Partner re-records the fixed flow and pins the original slow session as a baseline. The new report auto-renders three comparison sections:
   • Session-level delta — total wall time, query count, SQL/Python ms (old vs new)
   • Per-action comparison — matched actions (by label, fallback to path) with before/after stats
   • Findings compared to baseline — which findings were Fixed, which are New regressions, which are Unchanged with delta
7. Customer signs off with concrete numbers instead of "it feels faster."

v0.5.1 emits 18 finding types across 10 analyzers. Every finding has a severity (High/Medium/Low) and an estimated impact in ms.

Five sentences:

1. Don't fork the recorder. We reuse frappe.recorder.Recorder, record(force=True), and dump() for SQL capture. Our app adds session tracking, per-user activation, background-job inheritance, resource/frontend capture, and the analyze pipeline on top.
2. Per-user activation via hook ordering. Frappe's before_request runs frappe.recorder.record() first (no-op without a global flag); our before_request runs second and calls record(force=True) only if the current user has an active session in our Redis pointer.
3. Background-job session inheritance via a frappe.enqueue patch. We wrap the canonical enqueue to inject _profiler_session_id into job kwargs whenever the calling user has an active session; the worker's before_job hook pops the marker (so the user's method never sees it) and activates recording for the job.
4. Frontend capture wraps WHATWG primitives, not Frappe APIs. optimus_frontend.js hooks window.fetch and XMLHttpRequest.prototype.open/send directly — the same approach every production APM library uses. Survives future Frappe upgrades because fetch and XHR are stable web platform standards, while jQuery ajaxComplete hooks would break when Frappe drops jQuery.
5. Ten analyzers, all pure functions. Per-action breakdown, top-N slow queries, N+1 (by callsite), EXPLAIN flags, index suggestions (verified against schema), per-table breakdown, Python call tree (v0.3.0), redundant calls (v0.3.0), infra pressure (v0.5.0), frontend timings (v0.5.0). Each is independently testable from JSON fixtures with no Frappe DB access.

For the full architecture (data-flow diagrams, hook order, edge cases, extension points), read the inline docstrings in optimus/analyze.py and optimus/renderer.py.

Deliberately minimal. Only one non-Frappe dependency is declared in pyproject.toml; everything else rides on Frappe, the standard library, or MariaDB's own EXPLAIN output. This keeps installs lightweight and avoids fighting anyone else's package pins.

These do real analytical work without pulling a dependency:

• EXPLAIN-based findings — Full Table Scan / Filesort / Temporary Table / Low Filter Ratio are derived from MariaDB's own EXPLAIN output dict (no SQL-planning library).
• N+1 detection — groups the recorder's captured stacks by (filename, lineno) and collapses multi-variant loops (v0.5.2 callsite dedup).
• Framework classifier — pure path-boundary matching against the FRAMEWORK_APPS frozenset (frappe, erpnext, hrms, lms, helpdesk, insights, crm, builder, wiki, drive, payments) + third-party lib heuristics.
• Post-fix timing projections — per-finding-type speedup factors (20× for full-scan, 3× for filesort, 2× for temp-table, filtered_pct/100 for low filter, 2× avg for N+1 batching). See analyzers/base.project_post_fix_ms.
• Per-app bucketing, executive summary, analyzer notes, collapsible sections — pure Python in the renderer + Jinja macros.

Positioning: commercial APMs are always-on monitoring for "something regressed, find it." optimus is on-demand debugging for "this specific customer flow is slow, what should my dev shop fix." They're complementary, not competitive. Most ERPNext shops run only optimus because Datadog is expensive and leaks customer data off-site.

For the specific job of "debug a slow ERPNext workflow and hand the report to a partner shop," optimus produces a better report than any commercial APM — because of callsite-grouped N+1, framework-native findings, flow-aware session, and customer-safe export. None of those exist anywhere else at any price.

This app is designed to run on production because the whole point is to measure with real data volumes. That said, recording is not free.

When not recording, cost is a single Redis GET per request to check the active-session flag — sub-millisecond on local Redis. Users who are not recording pay essentially nothing.

Reports should be read as relative, not absolute. "This step took 5× longer than that step" is accurate. "This step took exactly 4.2 seconds" is inflated by the recording overhead.

Only the user who clicked Start gets recorded. Other users on the same site at the same time are not captured. Cross-session data leaks are prevented at multiple layers:

• Widget role check
• Server-side _require_profiler_user() on every whitelisted endpoint
• api.submit_frontend_metrics has a session-ownership check that prevents users from writing to a session they don't own

Background jobs spawned by the recording user's actions are automatically captured under the same session. ERPNext's submission path enqueues several jobs (GL postings, stock updates) — without this, the report would miss huge chunks of work.

If a session hits the recordings cap, the analyze report shows a warning under analyzer_warnings. Subsequent recordings are silently dropped until the customer restarts.

When a session moves to Ready, the source recordings in Redis (RECORDER_REQUEST_HASH, RECORDER_REQUEST_SPARSE_HASH), the per-session keys (profiler:session:*, profiler:infra:*, profiler:frontend:*), and the pyinstrument tree blobs are deleted. Redis returns to baseline. The Optimus Session DocType row and the attached HTML report files are the durable record.

• safe_report_file — Normalized SQL, redacted URLs/headers/form data, sanitized notes, redacted custom-app function names. Safe to email to a third-party.
• raw_report_file — Full data: raw SQL with literals, request headers, form data, complete stack traces. Gated at two layers:
  1. The "Download Raw Report" button is hidden in the form UI unless the user has System Manager role or recorded the session themselves.
  2. A File.has_permission hook (optimus.permissions.file_has_permission) blocks direct URL access even if the user guesses the file name.

On sites where bench disable-scheduler is in effect — common on dev, demo, and Frappe Cloud trial instances — the analyze RQ queue has no worker consuming it. v0.5.0+ detects this via frappe.utils.scheduler.is_scheduler_disabled() and falls back to frappe.enqueue(now=True), which runs analyze synchronously inside the stop request.

Consequences:

• The stop API blocks for the analyze duration (typically 2–20 seconds). The widget transitions from "Stopping…" directly to "Report ready" or "Analyze failed" — skipping the intermediate "Analyzing…" state — because the session is already finalized by the time the stop response arrives.
• A safety cap (optimus_inline_analyze_limit, default 50) refuses inline analyze on huge sessions to avoid gunicorn's 120-second request timeout. When a session exceeds the cap, it's marked Failed with an actionable error pointing the user to bench enable-scheduler and the Retry Analyze button.
• retry_analyze and the janitor's auto-stop path also use the scheduler-aware enqueue — you can't accidentally get stuck with a Failed session that won't retry.

Almost every knob a regular admin needs lives in the Optimus Settings Single doc (go to Desk → search "Optimus Settings", or /app/optimus-settings). Three tabs: General, Analysis, AI Fix Suggestions. The two ops-only knobs not in the UI (memory caps, lock behaviour, etc.) live in site_config.json — see the next section.

Resolution order for any field with both a DocType row and a site_config fallback (n+1, redundant-call, sampler-interval): DocType row → site_config.json → hardcoded default. The DocType wins if populated.

Two child tables that control which Frappe apps Optimus treats as "user code" (actionable) vs framework noise.

Patterns and users to exclude from instrumentation entirely (no recording captured in the first place — cheaper than dropping at analyze time).

Optimus redacts sensitive values at capture time — passwords, API keys, tokens, CSRF, cookies, authorization headers never reach Redis or the persisted report. Defaults cover 12 canonical patterns. The fields below extend the defaults — they are never removed. Substring match, case-insensitive.

These shape how reports render — they don't change what's captured or analyzed.

Repetition thresholds for the redundancy + N+1 analyzers. Lower = more findings (and more noise); higher = fewer findings.

Tune what counts as a high-severity finding. Sites with intentionally slow analytical flows want higher numbers (suppress false positives); sites with strict latency budgets want lower numbers.

Defaults for the line-profile picker dialog. The dialog still lets the user override these per run.

Off by default — no traffic leaves your bench until you turn it on.

Three independent on/off switches. Turning any one off is a hard disable — the section is never auto-generated, the matching button is hidden, the API refuses, and re-rendered reports omit the block.

Knobs that don't have a UI yet — usually because they're emergency levers, performance trade-offs, or security hardening that an admin should not be flipping casually. All live in sites/<your-site>/site_config.json; all are optional; defaults are inert.

A handful of them (the threshold ones — optimus_redundant_*_threshold, optimus_n_plus_one_threshold, optimus_sampler_interval_ms) also work as pre-DocType fallbacks. The DocType row wins if both are set.

These are pre-DocType compatibility — the DocType field with the same purpose is the recommended surface. Listed here for sites still tuned through site_config.

Set per session via the widget's start dialog or api.start(...):

Example Python call:

from optimus import api

api.start(
    label="Sales Invoice with 50 items",
    capture_python_tree=True,
    notes="<p>Click New Sales Invoice, add 50 items, hit Save.</p>",
)
# run your flow in another browser tab
api.stop()

Third-party Frappe apps can contribute analyzers without forking. In your app's hooks.py:

optimus_analyzers = [
    "my_app.performance.analyzers.orders.analyze",
    "my_app.performance.analyzers.payments.analyze",
]

Custom analyzers run after the 10 builtins and share the same AnalyzeContext. Each must be a pure function with signature:

def analyze(
    recordings: list[dict],
    context: optimus.analyzers.base.AnalyzeContext,
) -> optimus.analyzers.base.AnalyzerResult:
    ...

Contract:

• No Frappe DB access inside the function — analyzers are pure transformations over the recording data. This makes them unit-testable from JSON fixtures with no running site.
• Exceptions are caught by analyze.run and logged; a failing custom analyzer never halts the pipeline, but any findings it would have emitted are lost for that session.
• Custom analyzers can read earlier analyzers' output from context.actions, context.findings, and context.aggregate.
• A 60-second soft cap per analyzer logs a warning; the 20-minute total budget aborts remaining analyzers with a partial-completion warning.

See optimus/analyzers/base.py for the full type contract and the analyzers under optimus/analyzers/ for working examples (each is a self-contained module — n_plus_one.py, call_tree.py, redundant_calls.py, and infra_pressure.py are good starting points).

After bench migrate, verify in this order:

1. DocTypes exist:

   bench --site <site> mariadb -e "SHOW TABLES LIKE 'tabOptimus%';"

   Should list tabOptimus Session, tabOptimus Action, tabOptimus Finding, tabOptimus Settings, tabOptimus Tracked App, tabOptimus Phase Two Run.

2. Enqueue monkey-patch is active:

   bench --site <site> console
   >>> import frappe
   >>> frappe.enqueue._profiler_patched
   True

3. Version matches the running code:

   bench --site <site> console
   >>> import optimus
   >>> optimus.__version__
   '0.12.26'

   If this returns an older version, bench restart didn't land — workers are stale.

4. Floating widget appears in Desk: log in as a System Manager, open any Desk page, look bottom-right for the red Optimus pill. Hover it — the tooltip should show the current build ID. Open devtools → Console — you should see [optimus] floating_widget.js LOADED build=... at ....

5. Correlation header is set: start a session, open devtools → Network, click any link in Desk, inspect the response headers. You should see X-Optimus-Recording-Id AND Access-Control-Expose-Headers: X-Optimus-Recording-Id (without the second header, browsers hide the custom header from JavaScript — this is the single most common frontend instrumentation failure mode).

6. Full end-to-end smoke test:

   >>> from optimus import api
   >>> api.start(label="smoke", notes="quick verification")
   >>> # in another browser tab, open a Sales Invoice list
   >>> api.stop()
   >>> # wait 5–10 seconds for the analyze worker
   >>> doc = frappe.get_last_doc("Optimus Session")
   >>> doc.status
   'Ready'
   >>> len(doc.actions), len(doc.findings)

7. Safe Report is self-contained: open doc.safe_report_file in a browser with network disabled. It must render fully — no missing fonts, no broken layout. Tested in CI via test_safe_report_self_contained.py.

8. Scheduler-disabled fallback: bench --site <site> disable-scheduler, reload Desk, run a session, click Stop. The widget should transition straight from "Stopping…" to "Report ready" (no intermediate "Analyzing…"). Re-enable: bench --site <site> enable-scheduler.

9. Baseline comparison: pin a Ready session as baseline, record a second session with the same label, verify the second report has three comparison sections at the top.

10. PDF export: open a Ready session, click "Download Safe Report (PDF)". First click generates in ~2 seconds and caches; subsequent clicks are instant.

Most likely cause: browser is serving cached JS. The app_include_js cache-buster rotates on __version__ bumps, and if you've been testing across dev iterations without a full restart, the browser is still running the first version it loaded.

Fix (in order):

1. bench restart — reloads the Python workers so they see the updated __version__.
2. Hard-refresh Desk in the browser: Cmd+Shift+R (Mac) / Ctrl+Shift+R (Windows/Linux).
3. Verify in devtools → Console: you should see [optimus] floating_widget.js LOADED build=<current build> at .... Hover the widget pill — the tooltip should show the same build ID.
4. If the build ID matches and the bug still reproduces, open devtools → Console, click Stop, and check the [optimus] stop callback: {...} log. Paste it with a bug report.

Most likely cause: api.start or api.stop is returning a server error and frappe.call is not invoking the success callback. The widget has explicit error handlers for this case (added in v0.5.1) — they show a red toast in the top-right corner. Look there first. Also check Frappe's error log:

bench --site <site> mariadb -e "SELECT method, error FROM \`tabError Log\` WHERE method LIKE 'optimus%' ORDER BY creation DESC LIMIT 5;"

The session was already cleared server-side — usually because the auto-stop TTL expired (10 minutes of inactivity) or the janitor swept it. v0.5.1 handles this cleanly: the widget resets to inactive with a gray toast "Session already stopped." If you see the widget stuck on "Analyzing…" after this, you're on pre-v0.5.1 JS (see cache troubleshooting above).

Shouldn't happen in v0.5.1 — the analyzer verifies against information_schema before emitting. If you do see this, check the session's analyzer_warnings: suppressed suggestions are reported there with their reason. If a genuinely false-positive finding is still reaching the report, please file a bug with the full technical_detail_json attached.

Shouldn't happen in v0.5.1 — the aggregator now groups by file::function instead of the bare function name, and skips pure plumbing (werkzeug, frappe.handler, frappe.utils). If you still see this, verify the widget build ID is 2026-04-15-stop-fix-v3 or later.

On scheduler-disabled sites, analyze runs inline inside the stop request. A session with many recordings can take 10–30 seconds; the widget shows "Stopping…" the whole time. If it exceeds ~60 seconds, gunicorn's request timeout is at risk — lower optimus_inline_analyze_limit in site_config or re-enable the scheduler.

v0.5.0 caps v5_aggregate_json at 200 timeline entries + 500 XHR matches + 100 orphans with tail-preferring truncation. If you're still seeing slow form loads, check analyzer_warnings for the truncation count and the per-action call_tree_json field — trees larger than 200 KB overflow to a private File attachment rather than inlining.

cd ~/frappe-bench/apps/optimus
python -m pytest optimus/tests/ -v

1820+ unit tests run in ~7 seconds on a laptop. The suite is decoupled from Frappe — most tests use JSON fixtures and mocked frappe.cache / frappe.db, so you can run them without a site. Tests that do need Frappe import guards are gated via pytest.importorskip or stubbed at module level.

A second tier of 39 integration tests under optimus/tests_integration/ exercises a real Frappe v16 bench provisioned by .github/helper/install.sh and runs via bench --site <site> run-tests --app optimus. These cover install-time invariants, scheduler/cron paths, the atomic Lua merge under multi-worker load, and other behaviors that can't be proven from pure-pytest stubs. See optimus/tests_integration/README.md for the local-run recipe.

• tests/test_<analyzer>_*.py — per-analyzer unit tests with JSON fixtures
• tests/fixtures/*.json — recording blobs (sanitized) used across analyzer tests
• tests/test_frontend_assets.py — JS syntax + widget structure regression guards (uses node --check)
• tests/test_*_v5_*.py — v0.5.0 integration tests (infra + frontend end-to-end)
• tests/test_analyze_run_*_wiring.py — source-inspection regression guards for orchestration changes

1. Create optimus/analyzers/my_analyzer.py with a pure analyze(recordings, context) -> AnalyzerResult function.
2. Add it to _BUILTIN_ANALYZERS in analyze.py OR publish a site-config / hooks.py optimus_analyzers entry.
3. Write a test in tests/test_my_analyzer.py using existing fixtures under tests/fixtures/.
4. If the analyzer produces new finding types, add them to the enum in doctype/optimus_finding/optimus_finding.json and write a patch under patches/v0_X_Y/ that reloads the doctype.

See optimus/analyzers/infra_pressure.py for a recent example including the _conf() pattern for site-configurable thresholds.

MIT-licensed Frappe app. Contributions welcome via PR.

Before submitting:

• Run pytest optimus/tests/ -v — all 1820+ unit tests must pass.
• Run node --check on any JS changes.
• Bump __version__ in optimus/__init__.py for any user-visible change so the asset cache-buster rotates.
• Add a CHANGELOG entry under the current unreleased section.
• For new analyzers: see the interface contract in optimus/analyzers/base.py.

Bug reports: please include:

• __version__
• Browser console output (widget is noisy on purpose, look for [optimus] lines)
• Relevant Error Log entries from the site
• If it's an analyzer false positive, attach the technical_detail_json from the finding

MIT — see license.txt.