Clarify desired chart behavior for downloaded HTML reports

[MichaelSpece]

Prerequisites

• I am using the latest version of Locust
• I am suggesting a new feature, not asking a question

Description

This issue is to agree on the desired behavior before continuing implementation work around charts in downloaded HTML reports.

Current behavior, as I understand it:

• The downloaded HTML report renders interactive charts.
• The chart toolbox can export charts as PNGs from the report/charts view.
• The existing Download Report path gives users an interactive report artifact rather than a static snapshot.

Potential user need:

There may be value in an archival/shareable report mode that preserves the chart visualization as it appeared at report-generation time, without requiring a separate manual PNG export. At the same time, replacing interactive charts with a static image would be a regression for users who rely on hover, zoom, and toolbox behavior.

Open decisions before implementation:

• Is there a user need beyond the existing interactive report plus chart-toolbox PNG export?
• If so, should the behavior be an explicit option, such as interactive report vs. static/snapshot report, rather than changing the current Download Report behavior?
• Should a report include both interactive chart data and a static image, or should it avoid duplicating those payloads?
• Should any solution live in the browser download flow, server-side report generation, or documentation?

Alternatives considered:

• Keep the current behavior and rely on the existing chart toolbox PNG export.
• Add an explicit static/snapshot report option while preserving the current interactive report.
• Improve a specific report-chart rendering bug separately if one is identified.

Related context: PR #3400 explored embedding a static chart snapshot, but the review discussion showed that the desired user behavior should be agreed before choosing an implementation.

[MichaelSpece]

I want to sharpen the case for a static/snapshot report mode, because I agree the current PR should not silently remove useful interactivity from the existing report behavior.

My proposal would be: make the report mode explicit, and consider making the archival/static report the default downloaded artifact while keeping interactive charts as an opt-in mode. In other words, not "replace interactive charts because they are bad", but "separate the archival report use case from the exploratory report use case."

Why I think this may be worth considering:

• Optionality: Users who need hover/zoom/legend/toolbox behavior should still have it. Users who need a stable report artifact should not have to manually export charts one by one or remember which chart toolbar action corresponds to the report they are sharing.
• Consistency of behavior: Several historical issues are really about report/live/chart discrepancies or surprise: charts not persisting (Persist charts #1294), report charts extending after a test stopped (Report charts plot data points after the test has ended #1677), missing/different report chart data vs CSV (New HTML reports are missing data #1693), missing/empty HTML report charts in headless mode (cant show html chart version locust 2.4.0 #1908, Charts are not available in the HTML report when running in headless mode #2097), live/report time inconsistency (time display in live charts switches to the local time upon refresh #1835, The time of the downloaded html report is not correct #2691), report chart rendering problems (The Charts presentation in the report downloaded by locust is problematic #2706), chart/live stat mismatches (HTML report uses current_rps instead of total_rps for req/s column #3355), and delayed chart updates (Charts Update Is Delayed #2771). There is also a CLI-vs-library consistency wrinkle: the CLI starts the stats-history collection path for users before writing --html, while library callers have historically had to know which background setup to reproduce. A snapshot mode gives the report a clear invariant: it shows the chart state captured for that report, rather than rehydrating an interactive chart that may differ by browser, timing, timezone, mode-specific setup, or later rendering behavior.
• Consistency of design: The Download Data area already produces artifacts: CSVs and the report. A static report is closer to the normal expectation of a downloadable artifact, while an interactive chart view is closer to an analysis UI. Naming those modes explicitly would reduce surprise.
• Consistency with chart-tab downloads: The chart tab already exposes an explicit chart-download affordance on each interactive chart. A static report mode would be the report-level consolidation of that same user-visible capability: the user still clicks in both cases, but one report download captures the standard charts for a complete artifact instead of requiring separate per-chart exports. That keeps the same chart design, same ECharts rendering path, and same expectation that a downloaded chart is a fixed artifact, without introducing a separate chart behavior.
• Consistency of implementation: A snapshot can still reuse the existing ECharts/SwarmCharts rendering path and the same visual design. It does not require introducing a separate server-side chart renderer or a second chart design system.
• Library and CI ergonomics: Related requests have asked for persisted/exported charts (Persist charts #1294) and graph output in CLI/no-web/CI use cases (Graph capabilities export in no web UI mode (CLI)  #1321). There has also been confusion around reproducing CLI/WebUI behavior in library mode: for example, use_as_lib.py example getting stuck when running #1542 specifically turned on the exact call shape for history collection, gevent.spawn(stats_history, env.runner), and Locust as library: Web GUI doesn't show the spawned users over time and stucked at 1 user #1599/UI not getting updated with Locust library usage #1798 show users manually wiring WebUI, stats printing, and history setup to get library-mode behavior comparable to the CLI. That setup is not the same as CSV output, but CSV appears in user workarounds and questions because it is the visible artifact people can reason about when report charts are missing or inconsistent (New HTML reports are missing data #1693, Charts are not available in the HTML report when running in headless mode #2097). A built-in snapshot report mode would cover the lightweight generated-report case without requiring users to understand which internal chart-history setup the CLI already handles.
• Rendering cost: Static images should be faster and more deterministic to open than booting the JS charting stack and re-rendering multiple canvases. That should be measured, but the direction seems especially relevant for archived reports, CI artifacts, and long runs with larger chart payloads.

So the decision I would propose is something like:

1. Keep an interactive report mode for users who want exploration.
2. Add or make default a static/snapshot report mode for downloaded/shareable artifacts.
3. Ensure the UI labels make the distinction obvious, such as Download static report vs. Open interactive report / Download interactive report.
4. Reuse the existing chart component/export path so the snapshot has the same visual design as the interactive charts.

If the maintainers prefer the current interactive HTML report as the default, I still think an explicit static/snapshot option is useful. But from the consistency angle, I would lean toward interactive charts being opt-in for downloaded reports rather than the implicit default.

[andrewbaldwin44]

Thanks for the detailed response @MichaelSpece.

I'll let @cyberw weigh in here but there has been already some talk about adding a PDF download option for all the reasons you mentioned above and more (consistentcy, file size, static file, etc.). I think the idea of the HTML file is more like an offline/persisted version of your load test. The idea of sharing an HTML is already a bit weird, and I don't think changing the charts to a PNG image makes it any more shareable.

That being said, I don't know if PDF downloads are something we're currently interested in adding and maintaining. I know a lot of focus is currently being put into making a "next-gen" locust, so it's up to you @cyberw

[MichaelSpece]

Thanks, that framing makes sense to me. I agree that if the goal is a shareable/static artifact, PDF may be the more natural container than HTML-with-static-charts.

One consistency caveat, though: switching the container from HTML to PDF would not remove the core chart question. If the PDF includes static chart images, we still need to decide what those images are a snapshot of: the same ECharts rendering path and same stats-history source as the live/report charts, or a separate renderer/data path. The latter is where I would worry about reintroducing the same class of surprises: chart-tab download vs report output vs live chart vs CLI/library generated artifact all looking or sampling slightly differently. So, even for PDF, I think the useful invariant is still: the downloaded artifact captures the same chart design and data interpretation users saw in the Web UI, just in a static/report-oriented form.

If PDF is the direction maintainers would prefer, I would be happy to take that on instead of the current HTML snapshot PR. I can either retarget this draft PR or close/supersede it with a smaller PDF/static-report proposal, whichever is easier for review.

I also do not want to build against the wrong generation of the UI. Is there a public branch/issue/design doc for the next-gen Locust work where report/export behavior should be discussed, or should this stay scoped to the current Web UI until that work is ready for outside contributions?

[cyberw]

Calling it next-gen Locust is perhaps a little premature :)

I'm putting a lot of my spare time into https://github.com/cyberw/aiolocust , which is basically a complete rewrite with a much smaller scope than Locust. It doesn't even have a UI (and might never really get one), but it has at least reached a state where I'm no longer ashamed to have people use it :)

If you did want to look into generating reports for that I would be very interested! On the plus side, you can basically choose any implementation you prefer, as there's no legacy, on the minus side is you'd have to build everything from scratch (and I'd probably prefer making any dependencies you add optional, because it is primarily a command line tool).

I can see you've put in a lot of work writing the PR and these comments @MichaelSpece , but I'm going to need a TL;DR? If PDF or single file/.mhtml can be done easily (keeping any extra dependencies as optional), that's of interest. 100 (real) lines of code/changes or less :)

[MichaelSpece]

TL;DR: I’d separate this into two tracks.

For Locust, I would not remove the existing interactive HTML report capability. But I do think the static/shareable artifact idea is not completely separate from the current report UX: it might not replace the HTML report itself, but it could replace or split the current Download Report link. For example, the UI could distinguish Download static report from Download interactive report / Open interactive report.

If there’s interest later, the cleaner static direction sounds like PDF or single-file/MHTML, while reusing the same chart rendering/data path so report output does not diverge from the Web UI.

For aiolocust, I opened a small first pass here: cyberw/aiolocust#26.

That PR adds --html-report, adds no new dependency, uses Rich’s existing HTML export path, and keeps the feature opt-in. Happy to treat that as the exploratory path and leave the Locust-side PR alone unless you want a separate PDF/MHTML proposal there.

[github-actions]

This issue is stale because it has been open 60 days with no activity. Remove stale label or comment or this will be closed in 20 days.

[yukha-dw]

+1

My use case is parse the downloaded HTML report using jsdom. However, because new report is interactive, I need to use runScripts argument with additional dependency, canvas