Add User Experience docs (elastic#187)

Author: bmorelli25

docs/en/observability/images/js-errors.png

@@ -81,6 +81,9 @@ include::inspect-uptime-duration-anomalies.asciidoc[leveloffset=+2]
 
 include::configure-uptime-settings.asciidoc[leveloffset=+2]
 
+// User experience
+include::user-experience.asciidoc[leveloffset=+1]
+
 // Alerting
 include::create-alerts.asciidoc[leveloffset=+1]
 

docs/en/observability/images/page-load-duration.png

@@ -0,0 +1,196 @@
+// To do: Add a page that talks about how synthetics and UE work together. Passive/Active, etc.
+
+[[user-experience]]
+= {user-experience}
+
+{user-experience} provides a way to quantify and analyze the perceived performance of your web application.
+Unlike testing environments, {user-experience} data reflects real-world user experiences.
+Drill down further by looking at data by URL, operating system, browser, and location --
+all of which can impact how your application performs on end-user machines.
+
+Powered by the APM Real user monitoring (RUM) agent, all it takes is a few lines of code to begin
+surfacing key user experience metrics.
+
+[role="screenshot"]
+image::images/user-experience-tab.png[User experience tab]
+
+[discrete]
+[[why-user-experience]]
+== Why is {user-experience} important?
+
+Search engines are placing increasing importance on user experience when organically ranking websites.
+Elastic makes it easy to view your website data in the context of Google Core Web Vitals --
+metrics that score three key areas of user experience: loading performance, visual stability, and interactivity.
+These Core Web Vitals are set to become the main performance measurement in Google ranking factors.
+If you’re a content-based site that wants to appear in the “Top Stories” section of Google search results,
+you must have good Core Web Vitals.
+
+// We don't support business outcome capture yet. For now, this section should focus on CWV.
+// Saving this, as it might be useful later:
+// --------------------------------------------------------------------------------------------------------------
+// Every website has goals -- some sites want users to buy a product, sign up for a mailing list, download an app,
+// or share something on social media.
+// But no matter how great your product is, a poor {user-experience} can negatively impact your goal completion rate.
+// For example, in one study, 40% of users said they abandon a website if it takes more than three seconds to load.
+// footnote:[Source and more info: https://neilpatel.com/blog/loading-time/[neilpatel.com]]
+// In another, Amazon calculated that a page load slowdown of just one second would cut conversions by
+// 7% -- costing them $1.6B in sales each year.
+// footnote:[Source and more info: https://www.fastcompany.com/1825005/how-one-second-could-cost-amazon-16-billion-sales[fastcompany.com]]
+// In short, a good {user-experience} keeps your users happy and improves your website's odds of success.
+// --------------------------------------------------------------------------------------------------------------
+
+[discrete]
+[[how-user-experience-works]]
+== How does {user-experience} work?
+
+{user-experience} metrics are powered by the {apm-rum-ref}[APM Real User Monitoring (RUM) agent].
+The RUM agent uses browser timing APIs, like https://w3c.github.io/navigation-timing/[Navigation Timing],
+https://w3c.github.io/resource-timing/[Resource Timing], https://w3c.github.io/paint-timing/[Paint Timing],
+and https://w3c.github.io/user-timing/[User Timing], to capture user experience
+metrics every time a user hits one of your pages.
+This data is stored in {es}, where it can be visualized using {kib}.
+
+The RUM agent can be installed as a dependency to your application, or with just a few lines of JavaScript.
+It only takes a few minutes to <<instrument-apps,get started>>.
+
+[discrete]
+[[user-experience-tab]]
+== {user-experience} in {kib}
+
+[discrete]
+[[user-experience-page-load]]
+=== Page load duration
+
+This high-level overview is your analysis starting point and answers questions like:
+How long is my server taking to respond to requests?
+How much time is spent parsing and painting that content?
+How many page views has my site received?
+
+You won't be able to fix any problems from viewing these metrics alone,
+but you'll get a sense of the big picture as you dive deeper into your data.
+
+[role="screenshot"]
+image::images/page-load-duration.png[User experience page load duration metrics]
+
+[discrete]
+[[user-experience-metrics]]
+=== {user-experience} metrics
+
+{user-experience} metrics help you understand the perceived performance of your website.
+For example, first contentful paint is the timestamp when the browser begins rendering content.
+In other words, it's around this time that a user first gets feedback that the page is loading.
+
+[role="screenshot"]
+image::images/user-exp-metrics.png[User experience metrics]
+
+// This is collapsed by default
+[%collapsible]
+.Metric reference
+====
+First contentful paint::
+Focusses on the initial rendering and measures the time from when the page starts loading to when
+any part of the page's content is displayed on the screen.
+The agent uses the https://www.w3.org/TR/paint-timing/#first-contentful-paint[Paint timing API] available
+in the browser to capture the timing information.
+footnote:[More information: https://developer.mozilla.org/en-US/docs/Glossary/First_contentful_paint[developer.mozilla.org]]
+
+Total blocking time::
+The sum of the blocking time (duration above 50 ms) for each long task that occurs between the
+First contentful paint and the time when the transaction is completed.
+Total blocking time is a great companion metric for https://web.dev/tti/[Time to interactive]
+(TTI) which is lab metric and not available in the field through browser APIs.
+The agent captures TBT based on the number of long tasks that occurred during the page load lifecycle.
+footnote:[More information: https://web.dev/tbt/[web.dev]]
+
+`Long Tasks`::
+A long task is any user activity or browser task that monopolize the UI thread for extended periods
+(greater than 50 milliseconds) and block other critical tasks (frame rate or input latency)
+from being executed.
+footnote:[More information: https://developer.mozilla.org/en-US/docs/Web/API/Long_Tasks_API[developer.mozilla.org]]
+
+Number of long tasks::
+The number of long tasks.
+
+Longest long task duration::
+Duration of the longest long task on the page.
+
+Total long tasks duration::
+Total duration of all long tasks
+====
+
+These metrics tell an important story about how users experience your website.
+But developers shouldn't have to become experts at interpreting and acting on these signals;
+they should spend their time reacting to the opportunities that these metrics present.
+For that reason (and many others), Elastic has embraced Google Core Web Vitals.
+
+[discrete]
+[[user-experience-core-vitals]]
+==== Core Web Vitals
+
+https://web.dev/vitals/[Core Web Vitals] is a recent initiative from Google to introduce a new set of
+metrics that better categorize good and bad sites by quantifying the real-world user experience.
+This is done by looking at three key metrics: loading performance, visual stability, and interactivity:
+
+[role="screenshot"]
+image::images/web-dev-vitals.png[Web dev vitals (image source: https://web.dev/vitals)]
+
+Image source: https://web.dev/vitals/[web.dev/vitals]
+
+Largest contentful paint (LCP)::
+Loading performance. LCP is the timestamp when the main content of a page has likely loaded.
+To users, this is the _perceived_ loading speed of your site.
+To provide a good user experience, Google recommends an LCP of fewer than 2.5 seconds.
+footnote:[Source: https://web.dev/lcp/[web.dev]]
+
+First input delay (FID)::
+Load responsiveness. FID measures the time between a user's first interaction with a page, like a click,
+and when the page can respond to those interactions.
+To provide a good user experience, Google recommends a FID of less than 100 milliseconds.
+footnote:[Source: https://web.dev/fid/[web.dev]]
+
+Cumulative layout shift (CLS)::
+Visual stability. Is content moving around because of async resource loading or dynamic content additions?
+CLS measures these frustrating unexpected layout shifts.
+To provide a good user experience, Google recommends a CLS score of less than `.1`.
+footnote:[Source: https://web.dev/cls/[web.dev]]
+
+TIP: Beginning in 2021, Google will start using Core Web Vitals as part of their ranking algorithm
+and will open up the opportunity for websites to rank in the "top stories"
+position without needing to leverage https://amp.dev/[AMP].
+footnote:[Source: https://webmasters.googleblog.com/2020/05/evaluating-page-experience.html[webmasters.googleblog.com]]
+
+[discrete]
+[[user-experience-distribution]]
+=== Load/view distribution
+
+Operating system, browser family, and geographic location can all have a massive impact on how visitors
+experience your website.
+This data can help you understand when and where your users are visiting from, and can help you
+prioritize optimizations -- for example, prioritizing improvements for the most popular browsers visiting your site.
+
+Don't forget, this data also influences search engine page rankings and placement in top stories for content sites --
+without requiring the use of AMP.
+
+[role="screenshot"]
+image::images/visitor-breakdown.png[User experience visitor breakdown]
+
+[discrete]
+[[user-experience-errors]]
+=== Error breakdown
+
+JavaScript errors can be detrimental to a users experience on your website.
+But variation in users' software and hardware makes it nearly impossible to test for every combination.
+And, as JavaScript continues to get more and more complex,
+the need for user experience monitoring and error reporting only increases.
+Error monitoring removes this blindspot by surfacing JavaScript errors that are
+occurring on your website in production.
+
+[role="screenshot"]
+image::images/js-errors.png[User experience javascript errors]
+
+Open error messages in APM for additional analysis tools,
+like occurrence rates, transaction ids, user data, and more.
+
+[discrete]
+[[user-experience-references]]
+==== References