Bug 443664 - [Performance] Provide user documentation for interactive UI
monitoring plug-in
Change-Id: I4b3b112559fc24055a572a5713ce63610b7882cd
Signed-off-by: Sergey Prigogin <eclipse.sprigogin@gmail.com>
diff --git a/bundles/org.eclipse.platform.doc.user/contexts_Workbench.xml b/bundles/org.eclipse.platform.doc.user/contexts_Workbench.xml
index d1355b2..51d4734 100644
--- a/bundles/org.eclipse.platform.doc.user/contexts_Workbench.xml
+++ b/bundles/org.eclipse.platform.doc.user/contexts_Workbench.xml
@@ -1283,6 +1283,10 @@
<description>The tracing preference page allows you to dynamically change the tracing options of plug-ins and output settings.</description>
<topic label="Tracing preference page" href="reference/ref-tracing_preference_page.htm"/>
</context>
+ <context id="uiresponsiveness_preference_page">
+ <description>The UI Responsiveness Monitoring preference page allows you to enable automatic detection of UI freezes and to modify parameters affecting freeze detection and logging.</description>
+ <topic label="UI Responsiveness Monitoring preference page" href="reference/ref-uiresponsiveness_preference_page.htm"/>
+ </context>
<context id="globalization_preference_page_context">
<description>Allows you to configure Bidi and other globalization preferences.</description>
<topic label="Preferences - Globalization" href="reference/ref-globalizationprefs.htm"/>
diff --git a/bundles/org.eclipse.platform.doc.user/images/uiresponsiveness_preferences.png b/bundles/org.eclipse.platform.doc.user/images/uiresponsiveness_preferences.png
new file mode 100644
index 0000000..361d015
--- /dev/null
+++ b/bundles/org.eclipse.platform.doc.user/images/uiresponsiveness_preferences.png
Binary files differ
diff --git a/bundles/org.eclipse.platform.doc.user/reference/ref-uiresponsiveness_preference_page.htm b/bundles/org.eclipse.platform.doc.user/reference/ref-uiresponsiveness_preference_page.htm
new file mode 100644
index 0000000..2bfe790
--- /dev/null
+++ b/bundles/org.eclipse.platform.doc.user/reference/ref-uiresponsiveness_preference_page.htm
@@ -0,0 +1,50 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html lang="en">
+<head>
+<meta name="copyright" content="Copyright (c) IBM Corporation and others 2014. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page.">
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<meta http-equiv="Content-Style-Type" content="text/css">
+<link rel="STYLESHEET" href="../book.css" type="text/css">
+<script language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js" type="text/javascript"></script>
+<title>UI Responsiveness Monitoring</title>
+</head>
+<body>
+
+<h1>UI Responsiveness Monitoring</h1>
+
+<p>Sometimes you may encounter a long pause when the GUI does not redraw or respond to typing or
+mouse actions. Determining causes of such a UI freeze in most cases requires capturing stack traces
+of Eclipse threads. In case you are experiencing UI freezes and want to report the problem to
+the correct Eclipse project, you can enable <strong>UI Responsiveness Monitoring</strong>, which
+will automatically detect UI freezes, capture stack traces, and write warning or error messages
+containing the collected information to the Eclipse error log.</p>
+
+<p>The <strong>UI Responsiveness Monitoring</strong> preference page allows you to enable automatic
+detection of UI freezes and to modify parameters affecting freeze detection and logging.</p>
+
+<img src="../images/uiresponsiveness_preferences.png" alt="UI Responsiveness Monitoring preference page" border="0">
+
+<p>UI freezes longer than the warning threshold value entered in the preference page are logged to
+the Eclipse error log as warnings. The logged messages include one or more stack traces of
+the UI thread. Longer UI freezes are logged as errors and include stack traces of all threads.
+Please keep in mind that capturing stack traces of all threads involves extra
+overhead, so setting the error threshold below 1 second is not recommended.</p>
+
+<p>A UI freeze is logged at the end of the freeze or after the deadlock threshold has
+expired, whichever comes first. The latter condition facilitates logging of indefinite
+UI freezes caused by deadlocks. If Eclipse becomes completely unresponsive don't kill it until
+the deadlock threshold expires. The message containing stack traces of all threads will be written
+to the Eclipse error log.</p>
+
+<p>It is possible to avoid logging of UI freezes matching a specific pattern. To achieve that, click
+the <strong>Add Filter...</strong> button and type the fully qualified method name of a stack frame
+to use as a filter. UI freezes containing this method in a stack trace of the UI thread will be
+ignored.</p>
+
+<p>Please file bugs for the UI freezes you encounter, describe what you were doing at the time and
+include the messages and the stack traces from the error log related to the freezes. This way
+the corresponding Eclipse project can work on the UI freeze and improve your user experience
+with Eclipse.</p>
+
+</body>
+</html>
diff --git a/bundles/org.eclipse.platform.doc.user/topics_Reference.xml b/bundles/org.eclipse.platform.doc.user/topics_Reference.xml
index 7416ebd..9dcf8ba 100644
--- a/bundles/org.eclipse.platform.doc.user/topics_Reference.xml
+++ b/bundles/org.eclipse.platform.doc.user/topics_Reference.xml
@@ -174,6 +174,7 @@
</topic>
<topic label="Text Editors" href="reference/ref-texteditorprefs.htm"></topic>
<topic label="Tracing" href="reference/ref-tracing_preference_page.htm"></topic>
+ <topic label="UI Responsiveness Monitoring" href="reference/ref-uiresponsiveness_preference_page.htm"></topic>
<topic label="Web Browser" href="reference/ref-42.htm">
<enablement>
<test property="org.eclipse.core.runtime.isBundleInstalled" args="org.eclipse.ui.browser"/>
