From 938bc9e999ae1126205bdfa6de3875adbde5b986 Mon Sep 17 00:00:00 2001 From: Garrick Aden-Buie Date: Tue, 6 Oct 2026 18:35:24 -0400 Subject: [PATCH 01/16] Add shiny-optimize skill (first draft, full research dump) Comprehensive performance-optimization skill for Shiny for R apps: SKILL.md diagnostic workflow + 7 reference files distilled from the Posit Conf 2024 Level-Up Shiny workshops, the official shiny.posit.co performance articles, and broader ecosystem research (Mastering Shiny, promises/mirai, Appsilon, shinyloadtest). Intentionally oversized (~17k tokens) as a first draft; a review pass will trim to a leaner, more prescriptive version. - Register in shiny plugin - Category README entry - Eval workspace kept uncommitted (shiny/shiny-optimize-workspace/) --- .claude-plugin/marketplace.json | 3 +- shiny/README.md | 21 +- shiny/shiny-optimize/SKILL.md | 242 +++++++++++++++ .../shiny-optimize/references/async-tasks.md | 191 ++++++++++++ shiny/shiny-optimize/references/caching.md | 171 +++++++++++ .../shiny-optimize/references/data-loading.md | 160 ++++++++++ shiny/shiny-optimize/references/diagnosis.md | 182 +++++++++++ .../references/reactive-graph.md | 287 ++++++++++++++++++ .../shiny-optimize/references/rendering-ui.md | 138 +++++++++ .../references/scaling-users.md | 73 +++++ 10 files changed, 1466 insertions(+), 2 deletions(-) create mode 100644 shiny/shiny-optimize/SKILL.md create mode 100644 shiny/shiny-optimize/references/async-tasks.md create mode 100644 shiny/shiny-optimize/references/caching.md create mode 100644 shiny/shiny-optimize/references/data-loading.md create mode 100644 shiny/shiny-optimize/references/diagnosis.md create mode 100644 shiny/shiny-optimize/references/reactive-graph.md create mode 100644 shiny/shiny-optimize/references/rendering-ui.md create mode 100644 shiny/shiny-optimize/references/scaling-users.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 6f82e40..76dc700 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -79,7 +79,8 @@ "skills": [ "./brand-yml", "./shiny/shiny-bslib", - "./shiny/shiny-bslib-theming" + "./shiny/shiny-bslib-theming", + "./shiny/shiny-optimize" ] }, { diff --git a/shiny/README.md b/shiny/README.md index 331db31..730fe64 100644 --- a/shiny/README.md +++ b/shiny/README.md @@ -76,6 +76,25 @@ Comprehensive theming for Shiny apps using bslib and Bootstrap 5. Use when custo - [Bootswatch themes](https://bootswatch.com/) - [thematic package](https://rstudio.github.io/thematic/) +### `shiny-optimize` + +Diagnose and fix performance problems in existing Shiny for R apps — slow startup, sluggish interactions, blocking operations, and apps that need to support more users. Use when an app is slow, hangs, recomputes too much, or must scale beyond prototyping. + +**Organization**: SKILL.md provides the diagnostic workflow (understand the complaint → read the app → measure → classify the bottleneck → fix cheapest-first → verify), a quick-wins triage scan, and a symptom-to-fix table. Reference files provide the depth: +- `diagnosis.md` - Profiling with profvis, reactive-graph inspection with reactlog, micro-benchmarks (bench), and load testing (shinyloadtest/shinycannon) +- `reactive-graph.md` - Narrowing reactive dependencies: shared reactives, req(), isolate(), bindEvent(), freezeReactiveValue(), debounce()/throttle(), timers +- `caching.md` - bindCache() keys and scopes, caching data vs. plots, memoise(), cachem backends, deployment caveats +- `async-tasks.md` - The flush cycle, ExtendedTask, future_promise/mirai/crew, and the hard rules for worker code +- `data-loading.md` - Load-once patterns, fast file formats (fread/feather/parquet/DuckDB), pool + dbplyr, downloads and uploads +- `rendering-ui.md` - Output suspension via tabs, gating with req(), renderUI alternatives, plot/table rendering costs, perceived performance +- `scaling-users.md` - Brief multi-process model overview, Connect and shinyapps.io scheduler knobs + +**Resources**: +- [Shiny performance articles](https://shiny.posit.co/r/articles/improve/) +- [Mastering Shiny: Performance](https://mastering-shiny.org/performance.html) +- [promises documentation](https://rstudio.github.io/promises/) +- [shinyloadtest](https://rstudio.github.io/shinyloadtest/) + ## Potential Skills This category could include skills for: @@ -83,7 +102,7 @@ This category could include skills for: - Shiny app architecture and best practices - Reactive programming patterns - UI/UX design for Shiny apps -- Performance optimization +- ~~Performance optimization~~ (covered by `shiny-optimize`) - Testing Shiny applications - Deployment strategies - Module development diff --git a/shiny/shiny-optimize/SKILL.md b/shiny/shiny-optimize/SKILL.md new file mode 100644 index 0000000..0ad0428 --- /dev/null +++ b/shiny/shiny-optimize/SKILL.md @@ -0,0 +1,242 @@ +--- +name: shiny-optimize +description: > + Diagnose and fix performance problems in Shiny for R apps — slow startup, + sluggish interactions, long-running blocking operations, and apps that + struggle beyond a handful of concurrent users. Use when a Shiny app is slow, + hangs, recomputes too much, times out, or needs to support more users; when + the user asks to "speed up", "optimize", or "make faster" an existing Shiny + app; or when preparing a prototyped app for real-world traffic. +metadata: + author: Garrick Aden-Buie (@gadenbuie) + version: "0.1" +license: MIT +--- + +# Optimizing Shiny App Performance + +Help Shiny for R app authors find and fix performance bottlenecks in **existing +apps** — without changing what the app does. The typical user has an app that +worked fine for one or two developers during prototyping and is now too slow, +too fragile, or unable to support the number of users who actually need it. + +Two principles govern everything in this skill: + +1. **Measure before changing anything.** Human intuition is a notoriously bad + profiler. A "slow app" is usually slow because of one or two specific + operations, and they are rarely the ones the user suspects. Profile first, + then fix what the profile shows, then re-profile to confirm. +2. **Do less work before doing work faster.** The cheapest computation is the + one that never runs. In order of preference: + 1. **Eliminate** work that isn't needed (don't compute outputs nobody is + looking at; don't compute with inputs that aren't ready). + 2. **Reuse** work that repeats (share reactives, cache results). + 3. **Accelerate** unavoidable work (faster data access, vectorized code). + 4. **Relocate** work that blocks others (async / background tasks) — this is + the last resort and mostly buys *concurrency*, not raw speed. + +The goal is surgical: keep all app logic and behavior the same, make the app +perceptibly faster and able to handle more users. Resist rewrites. + +## The workflow + +Follow these steps in order. Don't skip measurement — most "obvious" fixes +turn out to be aimed at the wrong target. + +### Step 1 — Understand the complaint + +Before touching code, pin down what "slow" means. Ask the user (or infer from +context) and write it down as a benchmark to beat: + +- **What feels slow?** Initial page load? Every interaction? One specific + action (e.g. clicking "Run analysis")? Everything, once more than N people + use it at once? +- **How many concurrent users** does it need to support? (1–5, ~20, hundreds?) +- **Where does it run?** Locally, shinyapps.io, Posit Connect, Shiny Server? + (Deployment matters for multi-user problems, less for single-user slowness.) +- **How big is the data?** Where does it live (CSV, database, API) and how + often does it change? + +Each answer selects a different diagnosis path — see the symptom table below. + +### Step 2 — Read the app with performance eyes + +Read the app source (`app.R` / `server.R` / `ui.R` / modules) before running +anything. Look for the classic smells: + +| Smell (search for) | Why it hurts | Fix | +|---|---|---| +| `read.csv`/`read_csv`/DB queries **inside** `server()` or render functions | Re-runs per session or per invalidation | Load once in global scope; see [data-loading.md](references/data-loading.md) | +| The same subsetting/aggregation repeated in several outputs/reactives | Duplicate computation on every change | Extract one shared `reactive()`; see [reactive-graph.md](references/reactive-graph.md) | +| Renderers defined **inside** `observeEvent()`/`observe()` | Re-creates outputs; fights the reactive model | Define once at server top level; see [reactive-graph.md](references/reactive-graph.md) | +| Expensive `render*` expressions with no `req()`/guard | Computes on empty or half-ready inputs at startup | Gate with `req()`; see [reactive-graph.md](references/reactive-graph.md) | +| Many heavy outputs on the landing view | All must compute to load the page | Tabs/navs/conditional gating; see [rendering-ui.md](references/rendering-ui.md) | +| No `bindCache()` anywhere, but repeated identical expensive calls | Everyone re-pays the same cost | See [caching.md](references/caching.md) | +| Sliders/text inputs feeding expensive chains directly | One drag = dozens of recomputations | `debounce()`/`throttle()`/`bindEvent()`; see [reactive-graph.md](references/reactive-graph.md) | +| `Sys.sleep`, long model fits, slow API/DB calls inline in reactives/renders | Blocks the whole R process for all users | `ExtendedTask`; see [async-tasks.md](references/async-tasks.md) | +| `renderUI()` used for routine value updates | DOM rebuild + input rebinding per update | `update*Input()`; see [rendering-ui.md](references/rendering-ui.md) | +| `eventReactive`/`observeEvent` containing `isolate()`-free wide reads | Invalidates more than necessary | Narrow dependencies; see [reactive-graph.md](references/reactive-graph.md) | + +This static read gives hypotheses — not conclusions. The next step confirms +which smells actually cost time. + +### Step 3 — Measure + +Run the app and measure the complaint. Details, commands, and how to read the +output are in [diagnosis.md](references/diagnosis.md); the short version: + +```r +# Where does the time go? (CPU/memory profile) +profvis::profvis(shiny::runApp("app.R")) + +# Why do outputs keep recomputing? (reactive graph) +reactlog::reactlog_enable() +shiny::runApp("app.R") # interact, then shiny::reactlogShow() + +# Is implementation A faster than B? (micro-benchmark) +bench::mark(A(x), B(x), check = FALSE) + +# Does it hold up with N simultaneous users? (load test) +shinyloadtest::record_session("http://localhost:8100/") +# then replay with shinycannon at 1 user and N users +``` + +Use **profvis** when the question is "which code is slow" and **reactlog** when +the question is "why does so much code run". Use **bench** to compare two +implementations of one step. Use **shinyloadtest** only when the problem is +multi-user capacity, not single-session speed. + +Record concrete numbers (seconds per load, per interaction, evaluations per +slider move). You will need them to prove each fix worked. + +### Step 4 — Diagnose: classify the bottleneck + +| Symptom | Most likely causes | Start here | +|---|---|---| +| First page load is slow (every session) | Data loading or prep inside `server()`; outputs computing at startup on empty inputs; heavy `library()`/setup per session | [data-loading.md](references/data-loading.md), [reactive-graph.md](references/reactive-graph.md) | +| One interaction recomputes far too much | Over-broad reactive dependencies; duplicate computation; no caching; chatty inputs | [reactive-graph.md](references/reactive-graph.md), [caching.md](references/caching.md) | +| A specific action takes seconds and the app freezes | Long synchronous operation inside the flush cycle | [async-tasks.md](references/async-tasks.md) | +| Fast for one user, degrades with several | Blocking operations tie up the R process; repeated identical computation; per-user data reloads | [caching.md](references/caching.md), [async-tasks.md](references/async-tasks.md), [scaling-users.md](references/scaling-users.md) | +| Plots/tables are slow to appear or update | Heavy rendering; full redraws; `server = FALSE` DT on big data | [rendering-ui.md](references/rendering-ui.md) | +| Downloads/uploads misbehave or recompute | `downloadHandler` recomputing; `maxRequestSize` cap | [data-loading.md](references/data-loading.md) | +| Slower only when deployed | Multi-process behavior (globals, caches); scheduler settings | [scaling-users.md](references/scaling-users.md) | + +### Step 5 — Fix, cheapest change first + +Work through the fix ladder for the diagnosed category. Each ladder is ordered +from least to most invasive; stop as soon as measurements say you're fast +enough. All ladders keep app logic intact. + +**Reactive recomputation** → [reactive-graph.md](references/reactive-graph.md) +1. Add `req()` guards so nothing computes on not-ready inputs. +2. Extract shared `reactive()`s so each derived value is computed once. +3. Narrow dependencies: `bindEvent()`/`eventReactive()`, `isolate()`, + `freezeReactiveValue()` for update loops. +4. Rate-limit chatty inputs with `debounce()`/`throttle()`. +5. Fix timer patterns (`on.exit(invalidateLater(...))`, `reactivePoll()`). + +**Repeated identical work** → [caching.md](references/caching.md) +1. `bindCache()` the expensive reactive or renderer (keys must cover all + reactive reads in the body). +2. Prefer caching data over caching plots when downstream work benefits. +3. `memoise()` expensive pure functions (DB queries, model fits). +4. Choose cache scope deliberately: `"app"` to share across users (mind + information leakage), `"session"` for user-specific data, `cachem::cache_disk()` + to persist across restarts. + +**Blocking operations** → [async-tasks.md](references/async-tasks.md) +1. Only after caching/elimination are exhausted: move the operation into an + `ExtendedTask` with `future_promise()` (or `mirai`), `bind_task_button()`. +2. `future::plan(multisession)` (or mirai daemons) is required — a promise + without workers still blocks. +3. No reactive reads inside the worker; pass values as arguments to `invoke()`. + +**Data access** → [data-loading.md](references/data-loading.md) +1. Move loads to global scope; never read data inside render functions. +2. Faster formats: `fread`/`vroom` over `read.csv`; `feather`/`qs`/`fst` over + CSV/RDS round-trips. +3. DuckDB (+ parquet) or push-down-to-database (`pool` + `dbplyr`) when data + outgrows RAM or only slices are needed. + +**Rendering & UI** → [rendering-ui.md](references/rendering-ui.md) +1. Put heavy outputs on tabs/navs so hidden outputs don't compute. +2. Gate speculative outputs behind buttons/checkboxes (`req()` + `bindEvent`). +3. Use `DT` server-side processing, `replaceData()` updates, WebGL/bundles for + big plotly, busy indicators while work runs. + +### Step 6 — Verify and iterate + +Re-measure after **each** change, one change at a time, and compare against the +numbers from step 3. Performance work done blind tends to shuffle +complexity around instead of removing it. Keep the app's observable behavior +identical — a "faster" app that dropped a feature is not faster. + +## Quick-wins scan + +When the user wants immediate improvements and the app is small-to-medium, run +this triage first. These ten changes fix the large majority of slow Shiny apps +and rarely require refactoring: + +1. **Load data once, globally** — not in `server()`, never in renderers. +2. **Share one `reactive()`** among outputs that need the same derived data. +3. **`req()` at the top of expensive outputs** — no computing on empty inputs. +4. **Put heavy outputs on separate tabs** — hidden outputs don't compute. +5. **`bindCache()` the most expensive repeated computation.** +6. **`debounce()` sliders and search boxes** that drive expensive chains. +7. **Move multi-second operations into an `ExtendedTask`.** +8. **Switch slow data reads** to `fread`/`feather`/DuckDB. +9. **Replace `renderUI` updates with `update*Input()`.** +10. **Add busy indicators** (`bslib::useBusyIndicators()`) so remaining waits + feel shorter. + +## Ground rules + +- **One change at a time, then re-measure.** Batching changes makes it + impossible to know what helped. +- **Preserve behavior.** The user wants the same app, faster — not a redesign. + UI changes are limited to perceived-performance aids (spinners, task buttons, + tabs) and must be flagged to the user. +- **Prefer modern APIs**: `bindCache()`/`bindEvent()` over `renderCachedPlot()` + and raw `eventReactive` composition; `ExtendedTask` over hand-rolled promises; + `mirai`/`future` for workers. Mention legacy equivalents only when the app + already uses them. +- **Caching before async.** Caching often yields 10–100× improvements; + async only adds concurrency and carries serialization and debugging costs. +- **Profile before and after.** Capture timings in the issue/PR so the + improvement is provable. +- **Ask before adding dependencies** (duckdb, data.table, mirai, ...). Each new + package is a real cost for the user. + +## Reference map + +Read a reference only when the workflow points there: + +- [diagnosis.md](references/diagnosis.md) — profiling (profvis), reactive-graph + inspection (reactlog), micro-benchmarks (bench), and load testing + (shinyloadtest/shinycannon) with reading guides for each tool's output. +- [reactive-graph.md](references/reactive-graph.md) — why Shiny recomputes, + and every tool for narrowing the graph: shared reactives, `req()`, + `isolate()`, `bindEvent()`, `freezeReactiveValue()`, `debounce()`/`throttle()`, + timers, and circular-dependency fixes. +- [caching.md](references/caching.md) — `bindCache()` keys and scopes, caching + data vs. plots, `memoise()`, `cachem` backends, deployment caveats. +- [async-tasks.md](references/async-tasks.md) — the flush cycle, why blocking + hurts every user on the process, and the `ExtendedTask`/`future_promise`/`mirai` + patterns with their hard rules and pitfalls. +- [data-loading.md](references/data-loading.md) — load-once patterns, file + format choices (with benchmark numbers), DuckDB/parquet, databases with + `pool`/`dbplyr`, downloads and uploads. +- [rendering-ui.md](references/rendering-ui.md) — output suspension via + tabs/conditional panels, `outputOptions`, `renderUI` alternatives, plot and + table rendering costs, and perceived performance. +- [scaling-users.md](references/scaling-users.md) — brief: what changes when + multiple R processes serve the app, load-factor knobs on Connect and + shinyapps.io, and when to hand off to deployment tuning. + +**Shiny for Python:** this skill targets Shiny for R. If the app is Python, +translate concepts rather than code: `@reactive.extended_task` ≈ `ExtendedTask`, +`@reactive.event` ≈ `bindEvent`, `reactive.isolate()` ≈ `isolate()`, +`reactive.poll` ≈ `reactivePoll`, `functools.lru_cache` ≈ `memoise()`. There is +no `bindCache()` in Python — caching is DIY with `lru_cache`/`diskcache`. Note +that `async def` reactives do **not** make Python Shiny faster; use extended +tasks for background work. diff --git a/shiny/shiny-optimize/references/async-tasks.md b/shiny/shiny-optimize/references/async-tasks.md new file mode 100644 index 0000000..11bf655 --- /dev/null +++ b/shiny/shiny-optimize/references/async-tasks.md @@ -0,0 +1,191 @@ +# Non-Blocking Operations: ExtendedTask, future, mirai + +This is the **last** tool to reach for, not the first. Async doesn't make any +single computation faster — it changes *who waits*. Its two real benefits: +(1) the R process can keep serving **other sessions** while a long task runs, +and (2) with `ExtendedTask`, the **same session** stays interactive while the +user's own task runs. Before anything in this file, make sure elimination +(reactive-graph.md) and caching (caching.md) are exhausted: caching often gives +10–100×; async gives concurrency at the cost of serialization overhead, harder +debugging, and invisible profiling. + +## Why blocking hurts: the flush cycle + +Shiny's event loop per R process is, roughly: + +``` +while (TRUE) { + changes <- get_output_changes() + changed_outputs <- recompute_all_affected_things(changes) + send_outputs(changed_outputs) +} +``` + +- While a session's outputs are executing, **no new input is processed for that + session**. +- **No output is sent until all outputs in the flush complete** — one slow + output delays every output in that flush, so the page "hangs" even if only + one panel is slow. +- R is single-threaded per process: without async, one session's 5-second + computation blocks **every other user on the same R process** — their clicks + queue behind it. This is why an app can be fine in dev (one user) and fall + apart with three. + +## The decision path + +1. Can the operation be **eliminated** (don't compute what isn't shown)? +2. Can it be **cached** (`bindCache`/`memoise`) so it runs at most once per + unique input? +3. Can it be **precomputed** offline (data-loading.md)? +4. Is it genuinely a request-time, multi-second, user-specific computation + (e.g. fitting a model on user-uploaded data, querying an external API)? + → **Then** async is appropriate. + +Rule of thumb: async pays off for "a few big hotspots" — heavy API downloads, +slow DB queries, long model fits. Diffuse small slowness gets *worse* with +async (every task has fixed communication/serialization overhead). + +## `ExtendedTask` (Shiny ≥ 1.8.1): the recommended pattern + +`ExtendedTask` splits a reactive computation into "decide when to run with what +parameters" and "receive the result", running the work in a background process +so the reactive graph reaches equilibrium each tick and the session stays +responsive. + +The complete pattern (with `bslib::input_task_button`): + +```r +library(shiny) +library(bslib) +library(future) # or library(mirai) — see backends below + +future::plan(multisession) # REQUIRED: promises without workers still block + +ui <- page_fluid( + input_task_button("fetch", "Fetch data"), + plotOutput("plot") +) + +server <- function(input, output, session) { + # 1. Declare the task: a function that RETURNS a promise. + # Nothing reactive can happen inside the worker body! + task_fetch <- ExtendedTask$new(function(data_type) { + future_promise({ + fetch_from_slow_api(data_type) # runs in a worker process + }) + }) |> + bind_task_button("fetch") # 3. bind to the task button + + # 2. Invoke from an observer — values are snapshotted here, at invoke time + observeEvent(input$fetch, { + task_fetch$invoke(input$data_type) + }) + + # 3. Consume the result reactively — re-executes when the task finishes + data <- reactive({ + task_fetch$result() + }) + + output$plot <- renderPlot({ plot(data()) }) +} +``` + +Semantics worth knowing cold: + +- `ExtendedTask$new(fn)` — `fn` must **return a promise** and must **not read + reactive values** (Shiny throws if it tries). Everything the task needs is + passed to `$invoke(...)` and eagerly snapshotted at that moment — inputs may + have changed by the time the worker starts. +- `$invoke()` does **not** overlap with itself: invoking while running + **queues** the second call. `input_task_button` prevents accidental + double-clicks (it disables itself while running); plain `actionButton` does + not integrate with `bind_task_button()`. +- `$status()` — reactive read: `"initial" | "running" | "success" | "error"`. +- `$result()` — reactive read for consumers: blank (silent exception) before + the first run; a special "in progress" state while running (this drives the + busy indicators); the resolved **value** on success (not a promise); the + error is re-raised in the consuming output on failure. **Don't wrap + `result()` in `observeEvent`/`eventReactive`/`bindEvent`/`isolate()`** — its + invalidations are the mechanism. +- Declare the task at the **top level of the server function** → one task + instance per session. Declare at the top level of `app.R` → **shared across + all visitors** (rarely what you want; also means one user's invocation state + is everyone's). +- Multiple distinct ExtendedTasks run concurrently with each other and with + reactive code. +- `bind_task_button(task, "btn")` can also drive an arbitrary button's busy + state; `bslib::busyIndicatorOptions()` styles it. + +## Worker backends: `future` and `mirai` + +- **future + promises** (classic): `future::plan(multisession)` spawns worker + R processes; `future_promise({...})` runs the body there and returns a + promise. Worker count = concurrent long tasks; each worker is a full R + process (RAM!). `plan(sequential)` (the default if you forget) runs the task + synchronously — the "async" is fake and everything still blocks. +- **mirai** (newer, recommended for new work): event-driven promises — + resolution triggers immediately on completion instead of being polled, for + lower latency and much higher scalability (thousands of simultaneous + promises). Drop-in where `future_promise()` is accepted: + ```r + library(mirai) + daemons(4) # 4 local workers, top of app.R + onStop(function() mirai::daemons(0)) # clean shutdown + + task <- ExtendedTask$new(function(x) mirai({ slow(x) }, x = x)) |> + bind_task_button("go") + ``` + Daemons can also be remote hosts for true horizontal scaling. +- **crew** builds on mirai: managed worker pools with auto-scaling — reach for + it when tasks need lifecycle management beyond simple daemons. + +## Hard rules for worker code + +1. **No reactive reads inside the worker body.** Read reactives in the main + process and pass values as named arguments: + ```r + # Wrong: reactive reads can't cross processes + future_promise({ filter(data(), state == input$state) }) + # Right + st <- input$state + future_promise({ filter(data(), state == st) }, st = st, data = data) + ``` + (In ExtendedTask this is enforced — pass via `$invoke()`.) +2. **`session` is off-limits in workers** for the same reason. +3. **Plotting/printing happens in the main process**, in a `then()` handler — + graphics devices in workers go nowhere: + ```r + output$plot <- renderPlot({ + mirai({ prep_data(df) }, df = df()) |> + then(\(d) ggplot(d, aes(x, y)) + geom_point()) + }) + ``` +4. **The promise (or its pipeline) must be the last expression** of the + reactive/observer/render body — that's how Shiny knows when the work is done. +5. **Observers mutate reactive values inside handlers**: `mirai(...) |> then(\(d) + rv$done(d))`, never inside the worker. +6. **Serialization costs are real**: arguments and results are copied + to/from workers. Don't ship 2 GB data frames to a worker to add a column; + restructure or use a database instead. +7. **Async reactives cache the promise**; downstream consumers chain `then()`. +8. profvis can't see inside workers — profile synchronous code first, convert + the proven hotspot after. + +## Async reactives/observers (pre-ExtendedTask style) + +`reactive({ future_promise({...}) |> then(...) })` still works (Shiny ≥ 1.1.0) +and unblocks **other sessions** — but not the current one, because the +session's flush waits for the promise's dependent outputs. It remains useful +when the result must live in the reactive graph but no user-facing task button +makes sense. ExtendedTask is the better default; go raw-promises only when +ExtendedTask can't express the flow. + +## UI expectations to set with the user + +- `input_task_button` shows a busy state and disables itself — users get + feedback instead of a frozen app. +- While a task runs, the rest of the app (sliders, other tabs, even a ticking + clock output) stays live. Verify with an `invalidateLater(1000)` clock if + unsure. +- Busy indicators for *outputs* (see rendering-ui.md) complement task buttons: + buttons for triggered work, spinners for render-time work. diff --git a/shiny/shiny-optimize/references/caching.md b/shiny/shiny-optimize/references/caching.md new file mode 100644 index 0000000..cc63712 --- /dev/null +++ b/shiny/shiny-optimize/references/caching.md @@ -0,0 +1,171 @@ +# Caching: Stop Paying Twice for the Same Work + +Caching is the highest-leverage code-level fix for Shiny apps that serve +repeated identical computations — dashboards where many users look at the same +data, or one user toggling between the same few views. It matters because a +plain `reactive()` remembers only its **latest** value: revisit a previous +state and the expensive computation runs again. Scaling an app means either +adding compute or reducing the compute needed — caching reduces it, often by +10–100× ("a few lines of precomputation or caching logic can often lead to +10X–100X better performance" — Joe Cheng). Profile first (diagnosis.md) and +aim caches at computations the profile shows repeating. + +## `bindCache()`: cache any reactive or renderer + +Shiny ≥ 1.6.0. Works on `reactive()` and on `renderTable`, `renderPlot`, +`renderText`, `renderUI`, `renderPlotly`, etc.: + +```r +# Before +city_data <- reactive({ fetchData(input$city) }) + +# After +city_data <- reactive({ fetchData(input$city) }) |> + bindCache(input$city) +``` + +```r +# Renderers work the same way — list every reactive value the body reads +output$slow_plot <- renderPlot({ + data() |> + why_does_this_take_so_long(input$plot_type) +}) |> + bindCache(data(), input$plot_type) +``` + +How it works, and why the keys matter: + +- The **cache-key expressions become the reactive dependencies**; the original + body runs inside `isolate()`. When an input changes, Shiny re-runs only the + cheap key expressions, hashes their values, and looks them up — the expensive + body runs **only on a miss**. +- Shiny automatically appends the function body + result type to the key, so + `reactive({input$x * 2})`, `reactive({input$x * 4})`, and + `renderText({input$x * 4})` with the same `bindCache(input$x)` never collide. +- **The keys must capture everything the body reads.** A missing key = wrong + results served from cache (not an error!). When the body reads `data()`, + either include `data()` as a key or key on the upstream inputs that uniquely + determine `data()` — only if they truly do. +- First request computes and stores; same-key requests (from **any session** + with `cache = "app"`) return instantly. "It's still slow, but at least it's + only slow once." + +Key hygiene: + +- Keys must be **cheap to hash**: scalars, short strings, small vectors. + Hashing a 500k-row data frame takes ~1 ms (`system.time(rlang::hash(x))` — + measure before assuming it matters); avoid making big data frames keys when + a scalar surrogate exists: + ```r + # Surrogate key: still takes the dependency on bigData(), hashes cheaply + reactive({ summarize(bigData(), x = mean(x)) }) |> + bindCache({ max(bigData()$time) }) + ``` +- Reference-semantics objects (environments, R6, external pointers, functions, + reactive expressions) may not survive the round-trip. `cache_disk(warn_ref_objects + = TRUE)` warns on these — it catches the classic bug `bindCache(r)` (caching + the *reactive object*) where `bindCache(r())` (its value) was meant. + +## What to cache: data vs. plots + +- Cache the **data** (the shared reactive) when multiple outputs derive from + it — one cache entry serves many outputs, and downstream cheap steps stay + uncached and flexible. +- Cache the **plot** (the renderer) when the rendering itself is the expensive + part (big ggplot builds, plotly serialization) and the plot is what users + request repeatedly. +- Caching data is usually the better default; cache plots when profiling shows + render time dominating or when the same plot is re-requested across sessions. + +## Cache scopes + +`bindCache(x, ..., cache = "app")`: + +- **`cache = "app"`** (default): shared across all sessions in the R process. + This is what makes caching a *scaling* tool — the first user computes, + everyone else hits the cache. Caveat: values can **leak information between + sessions** if keys are incomplete or via timing side channels. Don't cache + user-private computations app-level. +- **`cache = "session"`**: private per session; no cross-session benefit, no + leakage. Use for user-specific data. +- **A cache object** (see below) for custom size/expiry/backends. + +Defaults and configuration (cachem-backed, LRU eviction): + +- Default app-level *and* session-level caches: `cachem::cache_mem(max_size = + 200e6)` — 200 MB each. +- Configure globally: `shinyOptions(cache = cachem::cache_mem(max_size = 500e6))` + at the top of `app.R`/`global.R`. +- Per-session: `session$cache <- cachem::cache_mem(max_size = 100e6)` inside + the server function. +- Expiry: `cachem::cache_mem(max_size = Inf, max_age = 300)` (5 minutes), or + per-object `max_age`/`max_n`. + +## Backends: `cachem`, and when disk/Redis matter + +- `cachem::cache_mem()` — in-process memory (the default). +- `cachem::cache_disk("./app_cache/cache/")` — shared across R processes on + the machine and persists across restarts. This is how a **multi-process + deployment** (Connect, Shiny Server Pro) still gets cross-session cache hits: + `shinyOptions(cache = cachem::cache_disk("./app_cache/cache/"))` at the top + of the app. rsconnect excludes `app_cache/` from deployments; keep a `cache/` + subdir to avoid colliding with `app_cache/sass/`. **Clear it when you redeploy + the app or upgrade R/packages** — stale caches outlive code changes, and + Connect redeploys otherwise start empty anyway. +- shinyapps.io: disk caches are shareable within an instance only; nothing + persists past instance shutdown. +- Multiple machines / huge shared caches: implement a custom backend — any + object with `$get(key)` (missing key returns `structure(list(), class = + "key_missing")`) and `$set(key, value)`. The caching article includes full + Redis (`redux::hiredis`) and `storr` examples with a 20 MB `allkeys-lru` + Redis config. + +## `memoise()`: cache plain functions outside the reactive system + +For expensive **pure functions** — DB queries, model fits, API calls with +stable parameters — memoise works at the function level, independent of +reactivity: + +```r +library(memoise) +m_get_query <- memoise(DBI::dbGetQuery) # in-memory +m_get_query <- memoise(DBI::dbGetQuery, + cache = cachem::cache_disk("app_cache/q")) # persistent +``` + +- Cache key = function identity + argument values. Repeat calls are instant + (real example: a repeated SQL query 1.25 s → 0.005 s). +- Call the memoised function from inside reactives/renderers as usual. Because + memoise ignores reactivity, **include data-version information in the + arguments** (a timestamp, a max(id), a config value) or the result goes stale + when the underlying data changes; memoise also supports `timeout` and manual + `cache$prune()`/`drop_cache()`. +- To share Shiny's cache with memoised functions: + `memoise(fn, cache = getShinyOption("cache"))`, or per-session + `memoise(fn, cache = session$cache)`. +- Only memoise *pure* functions — memoising a function that reads `input$` + doesn't work (inputs aren't serializable keys) and memoising one with side + effects is a correctness bug. + +## Plot caching specifics + +`renderPlot(...) |> bindCache(...)` keys plots on their **pixel size** as well +as your keys, so two users with slightly different window sizes don't share +entries. Widths are rounded to ~20% growth steps (400, 480, 576, 691…) and the +browser scales the delivered image down — a 450 px div gets the 480 px plot. +This is controlled by `sizePolicy` (`sizeGrowthRatio(width = 400, height = +400, growthRate = 1.2)` is the default) and inherited from `renderCachedPlot()` +(Shiny 1.2.0, superseded by `bindCache()` in 1.6.0 but still the source of the +mental model and the `cacheKeyExpr`/`sizePolicy` vocabulary). + +## Checklist before adding a cache + +1. Did the profile show this computation repeating? (Don't cache speculatively.) +2. Do the keys capture **every** reactive read in the body? +3. Are the keys cheap to hash? +4. Is the result serializable (no environments/R6/live connections)? +5. Is `cache = "app"` safe here — could one user's result leak to another? +6. Does the underlying data change? If yes, the key needs a version/timestamp + component, or use `max_age`. +7. On Connect/Shiny Server Pro with `cache_disk`: is the cache directory + excluded from deployment and cleared on upgrades? diff --git a/shiny/shiny-optimize/references/data-loading.md b/shiny/shiny-optimize/references/data-loading.md new file mode 100644 index 0000000..7fdfe29 --- /dev/null +++ b/shiny/shiny-optimize/references/data-loading.md @@ -0,0 +1,160 @@ +# Data Loading and Access: Get the Right Bytes, Once + +Data movement is the most common root cause of slow Shiny apps: data read per +session (or per invalidation!), re-read in renderers, or loaded wholesale when +only a slice is needed. The rules in this file preserve app behavior — same +data, same app — while cutting load times by 10–250× in realistic benchmarks. + +## Rule 1: Load once per process, not per session + +Code in `app.R`/`global.R` **outside** `server()` runs **once per R process** +and is shared by every session; code inside `server()` runs **once per +session**; code inside renderers runs **on every invalidation**. + +```r +# BAD: re-reads the CSV for every session +server <- function(input, output, session) { + scorecard <- read_csv("scorecard.csv") + # ... +} + +# GOOD: loaded once at process start, shared across sessions +scorecard <- read_csv("scorecard.csv") + +server <- function(input, output, session) { + # ... +} +``` + +- Anything **session-invariant** (reference data, lookup tables, model objects) + belongs in global scope. Anything user-specific stays in `server()`. +- Watch the console while the app runs: packages attaching or services + starting *mid-session* mean heavy setup is in the wrong scope. +- Diagnose with profvis: expensive work during the "Start session" phase is + per-session work that should move up (or be precomputed — below). +- Caveat: global data is **read-only shared state**. Don't let sessions mutate + it (`<<-` from a session works within one process but breaks under multiple + processes and risks cross-user corruption). For sharing *writable* state, + use a database or an app-level cache (caching.md). + +## Rule 2: Never read data inside render functions + +Reading/processing data inside `render*` re-runs on every invalidation of that +output. Load once (Rule 1), derive in a `reactive()`, and let renderers +consume the reactive. If the derivation is expensive and repeats, that's a +caching.md problem. + +## Rule 3: Choose formats that are fast to read + +Benchmark numbers for a 338 MB CSV (`bench::mark(..., check = FALSE)`): + +| Format | On disk | Read time | Notes | +|---|---|---|---| +| `readr::read_csv()` | 338 MB | ~1.55 s | 674 MB allocated | +| `readr::read_rds()` | 668 MB | ~0.94 s | general R objects | +| `data.table::fread()` | 338 MB | ~3× faster than read_csv | drop-in for most CSVs | +| `vroom::vroom()` | 338 MB | lazy — reads columns on demand | great when only some columns are used | +| `arrow::read_feather()` | — | very fast for data frames | columnar, cross-language | +| `qs::qread()` | — | ~3–5× faster than readRDS | general R objects | +| `fst` | — | 457 ms vs 1577 ms readRDS (10M rows) | also ~3× smaller | +| DuckDB over CSV | 338 MB | **~51 ms** (lazy `tbl_file`) | 52 KB allocated | +| DuckDB over parquet | 120 MB | **~5.8 ms** | "an unbeatable combo" | + +Practical ladder for a slow-loading data file: + +1. `fread()`/`vroom()` — one-line change, no pipeline change. +2. Convert to **parquet** + **DuckDB** for anything bigger than tens of MB or + used by many sessions: + ```r + library(duckdb) + con <- DBI::dbConnect(duckdb(), ":memory:") + scorecard <- duckdb::tbl_file(con, "scorecard.csv") # lazy over the CSV + # better: write once to parquet, then + scorecard <- dplyr::tbl(con, "read_parquet('scorecard.parquet')") + ``` + Normal dplyr verbs work **lazily** — `filter()`/`summarise()` compile to + SQL and only the small result crosses into R. One workshop benchmark: full + CSV read 1.5 s/670 MB vs DuckDB query 51 ms/52 KB — and every session + against the same `con` shares the work. +3. Precompute the exact analysis artifact offline when the derivation is + deterministic (next rule). + +Don't swap in heavy dependencies without asking — but for large-data apps, +DuckDB+parquet is usually the single biggest win available. + +## Rule 4: Precompute offline what doesn't need computing online + +Anything deterministic — joins, cleaning, derived columns, pre-aggregated +summaries — should be computed **before the app runs** (a script, a scheduled +job, a scheduled Quarto/report), and the app reads the finished artifact. The +restaurant metaphor from Mastering Shiny: hire a prep chef who comes in at +3am, don't chop vegetables during the dinner rush. This also removes the +"app is slow for the *first* user after each restart" class of problems. + +## Databases: `pool` + `dbplyr`, push compute to the data + +```r +pool <- pool::dbPool(RSQLite::SQLite(), dbname = "app.db") +onStop(function() pool::poolClose(pool)) # clean shutdown + +output$tbl <- renderTable({ + pool |> dplyr::tbl("mtcars") |> + dplyr::filter(cyl == .env$input$cyl) |> + dplyr::head(input$nrows) +}) +``` + +- **Why pool**: opens/returns connections per query, preventing the leaked + connections that crash long-running apps; works transparently with `tbl()`. +- **Push filtering/aggregation to the database**: keep verbs lazy (no + `collect()` until the end) so `filter()`/`summarise()` become SQL and only + the small result crosses into R. +- Cache frequent identical queries with `memoise()` or `bindCache()` + (caching.md). +- For data that changes while the app runs, poll with a **cheap check query** + (`SELECT MAX(updated_at)`) via `reactivePoll()` rather than re-reading on a + timer (reactive-graph.md). +- Big data that doesn't fit in RAM: compute in the database, DuckDB-over- + parquet, or arrow datasets — don't try to swap your way out of it. + +## `downloadHandler` shouldn't recompute the dataset + +`content(file)` runs on **every download click**. Precompute the data in a +reactive; only serialize inside `content`: + +```r +filtered_data <- reactive({ prep_data(input$year, input$region) }) + +output$download <- downloadHandler( + filename = function() "data.csv", + content = function(file) write.csv(filtered_data(), file, row.names = FALSE) +) +``` + +If the exported artifact itself is expensive to build (big Excel workbooks, +zip files), consider `bindCache()` on the data reactive, or generate the file +in an ExtendedTask for very large exports (async-tasks.md). + +## Uploads: the 5 MB cap + +Uploads silently fail above **5 MB** by default. If the app accepts data +files: + +```r +options(shiny.maxRequestSize = 30 * 1024^2) # 30 MB — set at app top level +``` + +Parse uploads **once** into a cached reactive, not inside renderers; heavy +parsing of large uploads belongs in an ExtendedTask. + +## Startup experience + +When heavy init is unavoidable (model warm-up, big load at process start): + +- Keep `server()` bodies cheap — they should mostly *define* the reactive + graph; expensive eager work belongs in globals or lazily-triggered reactives. +- Let the UI appear before heavy work streams in (perceived performance: + rendering-ui.md) rather than showing users a grey screen. +- On multi-process deployments, **every** R process repeats global-scope + loads — this is where lean startup and shared disk caches pay off + (scaling-users.md, caching.md). diff --git a/shiny/shiny-optimize/references/diagnosis.md b/shiny/shiny-optimize/references/diagnosis.md new file mode 100644 index 0000000..144aff7 --- /dev/null +++ b/shiny/shiny-optimize/references/diagnosis.md @@ -0,0 +1,182 @@ +# Diagnosing Shiny Performance: Profiling and Measurement + +Every optimization in this skill starts and ends with measurement. This file is +the how-to for the four measurement tools and how to interpret what they show. +Rule of thumb for choosing: **profvis** answers "which code is slow", **reactlog** +answers "why does so much code run", **bench** answers "which implementation of +one step is faster", and **shinyloadtest** answers "how many users can this +app support". + +Intuition is a bad profiler: the code that *looks* expensive is often fine, +while an innocent-looking loop or an over-broad reactive invalidation dominates. +Measure, fix, re-measure, one change at a time. + +## profvis — profile where the time goes + +`profvis` wraps R's sampling profiler (stop execution every ~10 ms, record the +call stack) in an interactive flame graph. It is Shiny-aware: internal Shiny +functions are hidden and each output's re-execution is colored blue, which +makes it excellent for *seeing reactive dependencies in action*. + +```r +library(shiny) +profvis::profvis( + shiny::runApp("app.R") # runApp() must be explicit inside profvis() +) +``` + +Interact with the app to reproduce the slowness, then close it — the flame +graph appears. Reading it: + +- **Bar width = time**, stack depth = height. Your code appears nested under + `eventReactiveHandler()` / render-function internals under `runApp()`. +- Ignore tall narrow "towers" (byte-code compilation, one-time setup) — they + cost little wall-clock time. +- Find the **widest blocks** and the repeated blocks — those are the targets. +- Gray `` blocks = garbage collection pressure, usually a symptom of + allocating-and-discarding large objects in a loop. +- Click a bar to see the source line (needs source refs; packages installed + with `--with-keep.source` or `R_KEEP_PKG_SOURCE=yes`). + +**Classifying the slowness from the profile timeline:** + +- "Start session" phase dominates → expensive work in the server function body + or global scope runs per session. Move it out (see data-loading.md). +- "Calculate" phases dominate → a reactive/observer/output is the bottleneck; + the flame graph shows which. + +**Classic R-level findings** (worth knowing because they show up constantly): + +- `df[i, "col"] <- value` / `$<-.data.frame` in a loop copies the whole data + frame each iteration — one real case went from 2.5 s to 10 ms (~250×) by + restructuring. Pre-allocate (`x <- numeric(n)`) instead of growing `x <- c(x, ...)`. +- Growing a **vector** is cheap since R 3.4 (with a single reference); growing + a **data frame** still copies everything. +- `apply(df, 2, mean)` pays for `as.matrix` + `aperm`; `colMeans()` is ~3× + faster, `vapply`/`lapply` over columns ~10×, restructuring the data ~6× total. + +**Limitations:** sampling below ~5 ms is unreliable; it can't see inside C +functions that don't check interrupts, `Sys.sleep()` (use `profvis::pause()` in +test code), or work in other processes — **profvis cannot see inside async +workers (futures/mirai)**, so profile *before* converting code to async. + +**Profiling a deployed app:** add the profvis module (UI: +`profvis_ui("profiler")`, server: `profvis_server("profiler")`) to get +start/stop buttons and downloadable `.Rprof` files, or profile manually with +`Rprof("out.Rprof", interval = 0.01, line.profiling = TRUE, gc.profiling = TRUE, +memory.profiling = TRUE)` … `Rprof(NULL)` … `profvis(prof_input = "out.Rprof")`. + +## reactlog — inspect the reactive graph + +reactlog records every reactive event and renders the graph as an interactive +timeline. Use it when outputs recompute more than they should, when you suspect +hidden/accidental dependencies, or when a small input change causes a big storm. + +```r +reactlog::reactlog_enable() # before the app starts; or options(shiny.reactlog = TRUE) +shiny::runApp("app.R") +``` + +- **Cmd/Ctrl + F3** (or Cmd/Ctrl + Shift + F3 for a marked time point) opens + the graph while the app runs; **Cmd/Ctrl + F4** drops a "user mark" so you can + jump straight to an interesting interaction. After closing the app, + `shiny::reactlogShow()` renders the full timeline. +- Embedding live in an app for demos: `reactlog::reactlog_module_ui()` in the + UI and `reactlog::reactlog_module_server()` in the server. + +Reading the graph: + +- Nodes: inputs (left), reactive expressions (middle), observers/outputs + (right). Green = up to date, gray = invalidated, orange = executing. +- Step through one user interaction with the arrow keys and **count the steps + until the app is idle again**. A single slider move should invalidate a narrow + slice. If large swaths go gray, dependencies are too broad. +- The graph shows **evaluation counts per node** — a reactive evaluated many + times per interaction signals duplicated work (often two outputs independently + re-deriving the same value instead of sharing one reactive). +- Dependency arrows are discovered at execution time and erased on + invalidation, so the graph shows *actual* dependencies — which is exactly why + it reveals accidental ones (e.g. a conditional `input$x` read that only + registers when a switch is on). + +What you're hunting for, concretely: outputs or observers that re-execute +without their inputs having changed meaning; reactives evaluated several times +per interaction; invalidations cascading into graph regions unrelated to the +user's action. Every finding here maps to a fix in reactive-graph.md. + +## bench — compare two implementations + +When the profile says "this one function", benchmark alternatives before +rewriting: + +```r +res <- bench::mark( + first_try(1e4), + second_try(1e4), + check = FALSE # needed when results differ (random, timestamps, row names) +) +plot(res) # visual comparison of time + memory +``` + +- `check = FALSE` silences the "each result must equal the first result" error + for stochastic code. +- Read **memory allocation** alongside time — `bench::mark` reports both, and a + version that allocates 100× less is usually both faster and more scalable. +- Typical wins, in order of size: do the operation once instead of N times + (hoist out of loops/reactives) > vectorize > pre-allocate > micro-optimize. + +## In-app timers and regression tracking + +- **shiny.tictoc** (Appsilon): one `