search

kubernetes / website

Kubernetes website and documentation repo:
https://kubernetes.io
Creative Commons Attribution 4.0 International
4.46k stars 14.36k forks source link

Mermaid diagrams are broken #31960

Closed NanoSector closed 1 month ago

NanoSector commented 2 years ago

This is a Bug Report

Problem: The graphs on the Ingress page are broken in Firefox, but seem to work properly in Chromium. I am unsure if this happens on other pages as well.

Firefox: Screenshot_20220228_084718

Chromium: Screenshot_20220228_084802

Proposed Solution: The graphs should be working in Firefox, possibly by fixing the unknown "syntax error".

Page to Update: https://kubernetes.io/docs/concepts/services-networking/ingress/

Additional Information:

jihoon-seo commented 2 years ago

For me:

I googled and found some links:

sftim commented 2 years ago

I can reproduce this using Firefox 97.0 on Ubuntu

/triage accepted /priority important-longterm /area web-development

NanoSector commented 2 years ago

I can consistently reproduce this on macOS 12.2.1.

image

This is a fresh Firefox installation without any add-ons.

However, switching to another network seems to fix the issue. Switching to my phone's tethered 4G network causes it to load properly in Firefox on macOS, switching back to our office network breaks it again.

I cannot find any console logs and network requests seem to successfully go through as well. Downloading mermaid.min.js on both networks and comparing hashes results in the same hash for both files.

Artificially throttling the request to "Regular 4G" using Firefox's developer tools seems to fix the issue on our office network. Maybe it is a race condition? Your first link seems to suggest a fix is published, maybe an update of the site generation tools would fix this?

sftim commented 2 years ago

/retitle Mermaid graphs are broken (replicable with Firefox)

sftim commented 2 years ago

/retitle Mermaid diagrams are broken (replicable with Firefox)

chrismetz09 commented 2 years ago

Cannot reproduce using firefox 95.0.2 (64-bit) on mac 10.15.7. Cannot reproduce using firefox 98.0 on mac 10.15.7. Cannot reproduce in mermaid live editor that uses Mermaid 8.14.0

@sftim, thoughts on this?

chrismetz09 commented 2 years ago

/assign @chrismetz09

sftim commented 2 years ago

I can reproduce this reliably but not on first page load.

sftim commented 2 years ago

This is a multihomed PC by the way; 2 IPv4 addresses and 4 IPv6 addresses, so the browser will be using something similar to Happy Eyeballs.

chrismetz09 commented 2 years ago

Random number of reloads DOES produce the error using firefox 98.0 on mac 10.15.7. Random number of reloads DOES produce the error using safari Version 14.1 (15611.1.21.161.7, 15611) on mac 10.15.7.

I was able to reproduce @NanoSector observation describing firefox 4G throttling that seems to mitigate the problem.

chrismetz09 commented 2 years ago

@sftim @NanoSector @jihoon-seo Possible fix (but still testing):

  1. Refreshing page will show Syntax error in mermaid graph sometimes #3232 noted ...If Mermaid.js is loaded from cache, Mermaid will sometimes not pick up the configuration and start processing before one can tell it to not startOnLoad. ...

  2. Looked into Firefox loading pages from cache after latest update.

  3. @sftim observed I can reproduce this reliably but not on first page load. Does this mean initial page load IS NOT from cache? I think so? I can reproduce error after initial page load by hitting multiple subsequent page reloads.

  4. Tried shift + Reload described in Firefox loading pages from cache after latest update. I could not reproduce error.

  5. There is a No-Cache No-Store for Selected Hosts add-on. Have not tested this yet.

Still testing and will report back.

chrismetz09 commented 2 years ago
  1. Tested [No-Cache No-Store for Selected Hosts add-on.). Did not work. Removed add-on then reproduced error.

Do we want to tell users to install add-on before using?

  1. I could not reproduce error using Shift + command/R in Firefox.

@sftim, guidance requested. Options I see are:

a) close the issue with a firefox mitigation note. Also add note in Diagram Guide.

b) Pass it on to web-dev folks?

tx

sftim commented 2 years ago

@chrismetz09 would you be willing to add this to the agenda for the next SIG Docs meeting and / or highlight this via Slack as an issue that needs attention?

chrismetz09 commented 2 years ago

Will do.

chrismetz09 commented 2 years ago

Updated to Mermaid 8.14.0 on test branch.

Replicated previously observed behavior:

  1. Chrome renders okay, although you do see rare mis-renders when pounding the reload button.
  2. FF shows frequent mis-renders. Shift + command R seems to clear the error and correctly renders the diagram.

As mentioined in very rare chrome occurrence and frequent FF reloads, you see the following:

Screen Shot 2022-04-12 at 10 31 43 AM

Verified checksums to ensure downloaded mermaid.min.js file is placed in proper /website/static/js directory. 

➜  ~ curl https://unpkg.com/mermaid@8.14.0/dist/mermaid.min.js | shasum
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100 1080k    0 1080k    0     0  5272k      0 --:--:-- --:--:-- --:--:-- 5298k
bb450af2b99ae0904a7264b06ef9d98017a8f417  -
➜  ~ shasum mermaid.min.js
bb450af2b99ae0904a7264b06ef9d98017a8f417  mermaid.min.js
danieltharp commented 2 years ago

Just noting this persists on Firefox 100.0b3 on the first load, and cleared up after a refresh..

sftim commented 2 years ago

Maybe Mermaid 9.0.0 would help?

chrismetz09 commented 2 years ago

More investigation steps:

  1. Updated to Mermaid 8.14.0 version.
  2. Update FF browser to 99.0.1 (64-bit) on Mac Catalina 10.15.7
  3. Update Chrome to Version 100.0.4896.88 (Official Build) (x86_64) on Mac Catalina 10.15.7
  4. Opened test PR

Observations:

  1. More frequent FF broken diagrams. Do see very occasional Chrome mermaid breakage but only after rapid/repeated reloads.
  2. See same behavior from multiple Mermaid diagrams in Ingress, Diagram Guide and Using services type nodeport
  3. In addition to broken syntax error, I saw new broken diagram renderings.

Screen Shot 2022-04-14 at 12 23 27 PM

chrismetz09 commented 2 years ago

Tested with Mermaid 9.0.0 and observed same behavior.

chrismetz09 commented 2 years ago

Updates:

  1. Tested with clean html file depicting mermaid diagram on local machine. Observed no problems.
  2. Need to test Hugo 0.93.0 diagram support but ran into error failed to render shortcode "api-reference": failed to process shortcode: ... failed: template: shortcodes/api-reference.html:7:17: executing "shortcodes/api-reference.html" at <$page.URL>: can't evaluate field URL in type page.Page. Will need to hack fix in test branch to complete Hugo 0.93.0 test.
  3. Looked over Mermaid code. errorRenderer.js hard codes error messages to the error svg: 
    g.append('text') // text label for the x axis
  .attr('class', 'error-text')
  .attr('x', 1240)
  .attr('y', 250)
  .attr('font-size', '150px')
  .style('text-anchor', 'middle')
  .text('Syntax error in graph');
g.append('text') // text label for the x axis
  .attr('class', 'error-text')
  .attr('x', 1050)
  .attr('y', 400)
  .attr('font-size', '100px')
  .style('text-anchor', 'middle')
  .text('mermaid version ' + ver);

    Wondering if solution could be Mermaid PR to add customized error message to Mermaid config.

    1. Would be curious if javascript could force reload when Mermaid diagram is rendered.
chrismetz09 commented 2 years ago

Used PR #33073 to clear api-reference shortcode problem allowing Hugo 0.93.0 upgrade. Tested with several Mermaid versions (8.11.2, 8.14.0, 9.0.0). Observed same syntax errors with FF (more frequent) and Chrome less frequent.

sftim commented 2 years ago

I suspect that some other JS code that we load might interfere with Mermaid. It also might be that a different way of loading Mermaid would hide the symptoms.

Happy to focus on this during KubeCon with anyone who has time to join in.

chrismetz09 commented 2 years ago

Updates:

  1. Worked correctly 100% time when using disable caching in dev tools. True for chrome and ff. Presumably this emulates what first-time visitor to page will see?
  2. Tried various techniques to reload page from server such as window.location.reload(), history.go(0), appending hash to url, etc. Don't see anything out there in JS land that can emulate empty cache and hard reload. I don't think manipulating web caches is a strategy for success.
sftim commented 2 years ago

I'm minded to try a different technique: drop bits of JavaScript out of the page (by locally editing templates, perhaps) until we find a removal that makes the symptoms disappear. Maybe a similar tactic with simplifying the HTML.

What do folks think, is that a way forward?

chrismetz09 commented 2 years ago

Okay, I'll give that try. In the meantime, we see popular ingress page occasionally rendering syntax error. To help users resolve this quickly, suggest we add note shortcode to perform hard refresh. Ingress diagram would look like this:

Screen Shot 2022-05-23 at 11 21 41 AM

Thoughts?

sftim commented 2 years ago

We could add the note or convert that diagram to SVG (and revert it when we have a fix). Either is fine by me.

chrismetz09 commented 2 years ago

okay I'll go with the note with the note for now.

sftim commented 2 years ago

I can no longer reliably replicate these symptoms for the published site. For the deploy preview, the symptoms still show up.

Firefox 100.0.2 and Chromium 102.0.5005.49 on Ubuntu 20.04

chrismetz09 commented 2 years ago

This one is elusive. If okay, I'll convert to svg to avoid obtrusive message which could cast doubt on mermaid integrity. In the meantime, I have been looking at https://github.com/kubernetes/website/blob/main/layouts/partials/head.html partial where mermaid is loaded per https://github.com/kubernetes/website/blob/0228c5dd50c63be40cbc94261ad452ca0accbf5b/layouts/partials/head.html#L90-L93. The only changed was the mermaid version.

danieltharp commented 2 years ago

Just as a point of clarification, I didn't need to do a hard reload for it to work, any sort of refresh seemed to make it work.

It does seem reasonable that there's maybe a variable or something being reused by another script causing this sporadic issue.

chrismetz09 commented 2 years ago

@danieltharp, we see that same behavior at times but not always. I will be converting the frequently visited Ingress diagrams to SVGs until fix can be identified and tested. One possibility is indeed something like a JS variable that is mucking things up. Any ideas on tracking this strongly welcomed.

chrismetz09 commented 2 years ago

Updates:

  1. Installed docsy-example, coded up mermaid diagram (no shortcode) and all worked fine.
  2. updated bootstrap, popper, jquery, mermaid and Hugo (0.93.0 extended) in the appropriate locations in scripts.html and head.html. Did not work.
  3. Tried loading these packages in different order. Did not work.

Don't see syntax error anymore on reloads. But see the following:

Screen Shot 2022-06-07 at 8 39 01 AM

sftim commented 2 years ago

drop bits of JavaScript out of the page (by locally editing templates, perhaps) until we find a removal that makes the symptoms disappear

A related thing to try: start with our content, plus Docsy and no other JavaScript, and set the the CSS (or SCSS) as simple as we can make it, eg plain Docsy. Add Mermaid. See if that works. Assuming it does, gradually add back more of the page† until we find what's breaking it.

† this could be a binary search, based on adding back half of the CSS at a time and seeing which half causes problems for the Mermaid rendering.

sftim commented 2 years ago

@chrismetz09 folks from the SIG could maybe plan in some time to pair on this, could that be helpful?

chrismetz09 commented 2 years ago

Okay, will systematically run thru the iterations beginning with docsy. Should not take long as I have it all setup.

Yes, pairing would be great. Heading over to slack to request assistance. Tx @sftim

chrismetz09 commented 2 years ago

Also scanned PRs by date range (is:pr merged:2022-02-01..2022-05-01) and nothing stood out that would cause problem.

chrismetz09 commented 2 years ago

Updates:

  1. Created test mermaid k8s repo. Starting with bare docsy-example theme and will incrementally build up to k8s website. Objective is to identify what component causes unpredictable Mermaid rendering.
  2. Have not observed any syntax errors in testing.
  3. devtools shows a multiple force reflow violations (aka layout thrashing) in console. Might this explain the problem? Looking over performance recordings shows force reflows definitely occurring.
sftim commented 2 years ago

PR #34794 looks very promising.

k8s-triage-robot commented 1 year ago

The Kubernetes project currently lacks enough contributors to adequately respond to all issues and PRs.

This bot triages issues and PRs according to the following rules:

You can:

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

k8s-triage-robot commented 1 year ago

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs.

This bot triages issues and PRs according to the following rules:

You can:

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle rotten

k8s-triage-robot commented 1 year ago

The issue has been marked as an important bug and triaged. Such issues are automatically marked as frozen when hitting the rotten state to avoid missing important bugs.

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle frozen

dprotaso commented 1 year ago

I just encoutered this today using Firefox 108.0.2 (64-bit) on macOS Monterey v12.6.2

allan-kg commented 1 year ago

Confirmed for me too, using :

As a plus, earlier today I had created like 5 mermaids to document a code. All of them worked fine (on firefox) using an online processor, like this one.

sftim commented 1 year ago

/retitle Mermaid diagrams are broken

AIUI, we see this in more than one browser

sftim commented 1 year ago

Duplicated by https://github.com/kubernetes/website/issues/39413

YoinkBird commented 1 year ago

Confirmed for me too, using :

* chromium `108.0.5359.94-1~deb11u1`

* firefox-esr `102.6.0esr-1~deb11u1`

* System : debian bullseye

* [Sample page](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/)

  * Chromium
    ![image](https://user-images.githubusercontent.com/3980933/213699054-cc6369cb-3132-4261-805f-ee6808011b8c.png)
  * Firefox
    ![image](https://user-images.githubusercontent.com/3980933/213699245-74b40b67-60c0-47b7-99f0-1e5f2a770812.png)

As a plus, earlier today I had created like 5 mermaids to document a code. All of them worked fine (on firefox) using an online processor, like this one.

Confirmation I encountered this as well; image loads in firefox private window but not a "normal" window. Disabling the "DuckDuckGo Privacy Essentials" extension allowed the SVG to load.

image

Details:

Speculation Not to over-speculate, but as an extra datapoint, "googletagmanager" is blocked by DuckDuckGo Privacy Essentials in a normal firefox window, but not in the private window. So this might be related to googletagmanager not being able to load: image

mrgiles commented 1 year ago

I can confirm that The diagram How does a HorizontalPodAutoscaler work also fails to render in Firefox (112.0.1) in both standard and private modes. Note: I don't have the DuckDuckGo Privacy Essentials extension installed.

sftim commented 1 year ago

If we have duplicates of this issue and either:

then it's OK to close that duplicate issue - not this one - with an explanatory note.

sftim commented 1 year ago

Duplicated by #42625

junktext commented 10 months ago

FYI: I ran into this bug today and for me I figured out that the Privacy Badger v2023.10.31 extension in Firefox was causing issues with mermaid for some reason. Once I disabled Privacy Badger protection, the diagrams loaded up just fine. Privacy Badger was only detecting 3 potential trackers, which even if I manually allowed those connections to go through, the diagrams would still not work properly.

Screenshot from 2023-11-22 16-16-21

I was using Firefox v119.0.1 on Ubuntu Linux 22.04. The Kubernetes documentation page I saw this issue on today was here: https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/

Lastly, for what it's worth when the diagram fails to load it mentions that mermaid v8.13.4 is used, but that was released two years ago on 2021-11-18. As of this writing, mermaid is on v10.6.1 (2023-11-06), so I'm wondering if a version upgrade for mermaid may help fix this bug?