Cache rendered notebook diffs

What does this MR do and why?

Merge request, commit and compare diffs reuse a rendered notebook (.ipynb) diff for 1 hour, instead of running the notebook transform and a diff process for every notebook on every request. Nothing cached the rendered notebook diff, so reloads and repeated requests repeated that work. The cache is behind the cache_notebook_diffs feature flag (gitlab_com_derisk, default off); disabling the flag restores the current behavior.

Design notes

What is cached. Gitlab::Diff::Rendered::Notebook::DiffFile reads three things from the IpynbDiff::Diff:

  • the text diff (to_s(:text)),
  • the transformed text of both notebooks (from.as_text, to.as_text), which becomes the old and new blob data for highlighting,
  • the source line of each transformed block (from.blocks, to.blocks), which the line-position mapping in DiffFileHelper#line_positions_at_source_diff reads.

Gitlab::Diff::Rendered::Notebook::DiffCache stores these and returns CachedDiff and CachedNotebook structs with the same reader methods (CachedDiff#to_s accepts only the text format, which is also the Diffy default), so DiffFile changes only in notebook_diff. A cache miss also returns the structs, so a miss and a hit run the same code (except for a diff too large to cache, below).

Smaller entries. The text diff usually holds every line of both notebooks (context and removed lines form the old text, context and added lines the new one). DiffCache rebuilds both texts from the text diff and stores them only when the rebuilt strings differ from the originals (same bytes and encoding), for example when the text diff is empty or has more than one hunk. This cuts an entry to about a third.

Key. notebook_diff:<VERSION>:<project_id>:<old_blob_id>:<new_blob_id>. The rendered diff depends only on the two blob contents, the transform and its options (DiffFile::IPYNB_DIFF_OPTIONS). VERSION must change with the transform, the options or the layout of the stored entry: gems/ipynbdiff/lib/ipynb_diff/transformer.rb points to it, and a spec in diff_cache_spec.rb fails when the rendered notebooks of a fixture change while VERSION does not. The project ID keeps entries per project. The key has no user, so signed-in and signed-out requests share entries. Repositories without a project (group wikis) skip the cache.

Store. Rails.cache (the Gitlab::Redis::Cache instance), as for Gitlab::BlobEmbed::Renderer (rendered blob snippets keyed by content, 1 hour) and Banzai::Renderer. The data can be regenerated at any time, so the cache instance with eviction fits. RedisCacheStore compresses entries, and its Marshal coder keeps string encodings, so the cached output is byte-identical. Gitlab::Diff::HighlightCache cannot help here: it is keyed by merge request diff and options, and it is read after the diff files are decorated, which is when the notebook is rendered.

TTL. 1 hour, the same as HighlightCache and BlobEmbed::Renderer.

Size ceiling and markers. An entry over MAX_BYTES (2 MB, measured on the serialized entry before compression) is not written. The request that rendered it shows the rendered diff, as without the cache. DiffCache writes a small marker for the key instead, and later requests show the raw .ipynb diff while the marker lives (1 hour). A render that times out also leaves a marker, for 10 minutes, because a timeout can come from a busy host. The marker records whether the render timed out on the web (1.5 s timeout) or in Sidekiq (10 s timeout). Sidekiq ignores a web timeout marker, and caches the diff when its render succeeds. A Sidekiq timeout stops the renders on both. Without markers these renders ran again on every request. Blobs are read up to 512 KB or the highlight limit, whichever is larger (Gitlab::Diff::File#fetch_blob), and most notebooks stay far below the ceiling. Invalid notebooks fail when they are parsed, and truncated blobs are skipped before that, so neither is cached or marked.

Observability. New log events: IPYNB_DIFF_CACHE_HIT (cached diff used), IPYNB_DIFF_CACHE_SKIPPED (marker found, raw diff shown; skip_reason is too_large, foreground_timeout or background_timeout) and IPYNB_DIFF_TOO_LARGE (marker written for size). Renders still log IPYNB_DIFF_GENERATED, and timeouts IPYNB_DIFF_TIMEOUT. A hit replaces a IPYNB_DIFF_GENERATED event, so the log volume does not grow.

Redis calls. One read per notebook file when the file is decorated, plus one write on a miss. Batching the reads would need the file collections to gather blob IDs before decorating. A hit takes 3 to 20 ms against 0.1 to 0.4 s for a render (table below).

Measured locally (pairs of synthetic notebooks):

Notebook pair Miss (render and write) Hit Redis memory per entry
476 KB, 40 PNG outputs 0.094 s 0.003 s 0.30 MB
570 KB, 40 PNG outputs 0.109 s 0.004 s 0.36 MB
327 KB, every line changed 0.385 s 0.019 s 0.18 MB

The cached output was identical to the rendered output in each case.

Request spec. spec/requests/projects/merge_requests/notebook_diff_render_cache_spec.rb counts IpynbDiff.diff calls (each is one transform and one diff process) over two identical requests for a merge request with two notebooks, for diffs_batch.json signed in and signed out, and for diffs_stream. With the flag, the first request renders each notebook once and the second renders none. Without it, the second request renders as many as the first. The assertions do not depend on reduce_notebook_diff_rendering, which changes how often each notebook renders without the cache.

Local spec note. diff_file_spec.rb "computes the first line where the remove would appear" also fails on master on macOS: the Apple diff aligns that hunk differently from GNU diff. CI uses GNU diff.

Related MRs, rollout order, follow-ups, ownership
  • Follow-up, stacked on this branch: !263933 (merged). It stops the diff process at the render timeout, behind its own flag stop_notebook_text_diff_at_timeout, so each change can be rolled back alone.
  • Sibling: !263894 (merged) stops the metadata and stats endpoints from rendering notebooks, behind reduce_notebook_diff_rendering. It changes app/helpers/diff_helper.rb, app/models/merge_request_diff.rb and lib/gitlab/diff/file_collection/base.rb, and no file of this MR, so the merge order does not matter.
  • Rollout order (rollout issue): enable cache_notebook_diffs only after reduce_notebook_diff_rendering is fully on, so endpoints that do not need the rendered diff do not read it from Redis, and after checking the Redis cache load with #g_durability.
  • Follow-ups: bound the size of the rendered notebook inside the transform (see https://gitlab.com/gitlab-org/gitlab/-/issues/607080); batch the cache reads per file collection; the highlight pass of the rendered diff still runs outside the render timeout and is not cached.
  • Ownership: Gitlab::Diff::Rendered::Notebook and gems/ipynbdiff belong to MLOps. The diff endpoints and file collections that call them belong to Code Review (code_review_workflow), so Code Review should co-review.
  • No changelog entry: the flag is off by default.
  • No database changes: no queries change.

References

Screenshots or screen recordings

No UI change. The rendered notebook view is the same with and without the cache.

How to set up and validate locally

  1. In a public GDK project, upload a Jupyter notebook to the default branch (+ > Upload file), then edit one cell's source on a new branch and click "Create merge request".
  2. In a terminal in the GDK gitlab directory, run tail -f log/application_json.log | grep IPYNB_DIFF_.
  3. In the Rails console, run Feature.enable(:cache_notebook_diffs).
  4. Open the merge request's Changes tab. Expect: the rendered notebook, and one IPYNB_DIFF_GENERATED line per changed notebook.
  5. Reload the page, then open it again signed out (private window). Expect: the same rendered notebook, and IPYNB_DIFF_CACHE_HIT lines instead of IPYNB_DIFF_GENERATED.
  6. In the Rails console, run Feature.disable(:cache_notebook_diffs), then reload. Expect: one IPYNB_DIFF_GENERATED line per notebook on every reload.

MR acceptance checklist

Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.

Edited by Eduardo Bonet

Merge request reports

Loading
Loading