feat(guides): document JFR Metrics and Diagnostics dashboard cards (#206

)

guides/_subsections/configure-feature-level.md

@@ -0,0 +1,19 @@
+### [Configure Feature Level](#configure-feature-level)
+Some features in the **web-client** UI are *Beta*-level features. This indicates that they are still underdoing design and development, and may have significant limitations, or be redesigned or even removed in the future.
+
+For those reasons, *Beta* features are hidden by default in the **Cryostat** UI. They can be enabled by following the steps below.
+
+<ol>
+  <li>
+    {% include_relative _subsections/common/navigate-to-settings.md %}
+  </li>
+  <li>
+    {% include howto_step.html
+      summary="Locate the Advanced settings"
+      image-name="4.0.0/advanced-setting.png"
+      text="
+        The <i>Advanced</i> tab within this view contains a control to set the <b>Feature Level</b> of the UI. This is set to <i>Production</i> by default. You can enable additional features by setting this to <i>Beta</i>, with the aforementioned caveats in mind. Once this is set, a <i>Beta</i> badge will appear on the <b>Cryostat</b> application titlebar. Additional features enabled by this setting, such as <b>Dashboard</b> cards, will be labelled with a similar badge to indicate the feature level. If you set the feature level back to <i>Production</i> then any <i>Beta</i>-level features will be hidden from the UI again.
+      "
+    %}
+  </li>
+</ol>

guides/_subsections/navigate-the-dashboard.md

@@ -5,7 +5,7 @@ The *Dashboard* is the first view you will see when you log into **Cryostat**. I
 
 ### [Dashboard Cards](#dashboard-cards)
 
-`Dashboard cards` are widgets that display information about your **Cryostat** instance and the `target` **JVM** applications it is monitoring. Let's walk through the available `cards` and how to add them to your *Dashboard*.
+`Dashboard cards` are widgets that display information about your **Cryostat** instance and the `target` **JVM** applications it is monitoring, or allow you to perform diagnostic actions against the `targets`. Let's walk through the available `cards` and how to add them to your *Dashboard*.
 
 {% include_relative _subsections/common/card-catalog.md %}
 
@@ -214,7 +214,7 @@ The *Dashboard* is the first view you will see when you log into **Cryostat**. I
       text=mbean-metrics-chart-text
     %}
   </li>
-    <li>
+  <li>
     {% capture configure-mbean-metrics-chart %}
     <p>
       In the next steps of the card creation, you can configure the details of the chart card.
@@ -245,6 +245,115 @@ The *Dashboard* is the first view you will see when you log into **Cryostat**. I
   </li>
 </ol>
 
+#### [JFR Metrics Chart Card](#jfr-metrics-chart-card)
+
+<ol>
+  <li>
+    {% capture jfr-metrics-chart-text %}
+    <p>
+      The <i>JFR Metrics Chart</i> <code>card</code> displays performance metrics about the <code>target</code> <b>JVM</b> by visualizing <b>JFR</b> data snapshots via embedded <b>Grafana</b> visualization panels as <i>Dashboard</i> cards. This <a href="#configure-feature-level"><i>Beta</i>-level feature</a>. A significant limitation of this card is that it depends upon the stateful <code>jfr-datasource</code> backend component, which only converts one <b>Flight Recording</b> file at a time to <i>Grafana</i> data. Therefore, this card does not behave well if multiple <b>web-client</b> instances are open at the same time, whether used by one user or multiple human users.
+    </p>
+    <p>
+      <b>Cryostat</b> gathers typical <b>JFR</b> data from the selected <b>Target</b>and periodically updates the <b>Grafana</b> visualizations. You can customize each <code>card</code> by going through the card creation wizard. The wizard will guide you through the process of selecting the metrics you want to display, how you want to display them, and other various configuration options. Some examples of <code>Performance Metrics</code> that can be displayed are:
+    </p>
+    <ul>
+        <li><i>CPU Load</i></li>
+        <li><i>Memory Usage</i></li>
+        <li><i>Heap Usage</i></li>
+        <li><i>Network Utilization</i></li>
+        <li><i>File I/O</i></li>
+        <li><i>Exception Statistics</i></li>
+        <li>...</li>
+    </ul>
+    {% endcapture %}
+    {% include howto_step.html
+      summary="Add the <i>JFR Metrics Chart</i> <code>Card</code>"
+      image-name="4.0.0/dashboard/jfrmetrics-preview.png"
+      caption="Click on the <i>JFR Metrics Chart</i> <code>card</code>. No preview is available."
+      text=jfr-metrics-chart-text
+    %}
+  </li>
+  <li>
+    {% capture jfr-mbean-metrics-chart %}
+    <p>
+      In the next steps of the card creation, you can configure the details of the chart card.
+    </p>
+    <p>
+      Configure the metric data by clicking the <i>Performance Metric</i> dropdown and selecting a metric. You can also configure the <i>Data Window</i> to display a specific time range of data and the <i>Refresh Period</i> to control how often the chart is updated.
+    </p>
+    {% endcapture %}
+    {% include howto_step.html
+      summary="Configure the <i>JFR Metrics Chart</i> <code>Card</code>"
+      image-name="4.0.0/dashboard/jfrmetrics-configuration.png"
+      caption="Click <i>Next</i> to provide <code>card</code> configuration."
+      text=jfr-mbean-metrics-chart
+    %}
+  </li>
+  <li>
+    {% capture jfr-metrics-chart-created %}
+    <p>
+        After clicking <i>Finish</i>, the <code>card</code> will be added to the dashboard. Initially the card will have no <i>source Recording</i> and display no data.
+    </p>
+    {% endcapture %}
+    {% include howto_step.html
+      summary="Finish <code>Card</code> Creation"
+      image-name="4.0.0/dashboard/jfrmetrics-no-source.png"
+      caption="The <i>JFR Metrics Chart</i> <code>card</code> created with no source recording."
+      text=jfr-metrics-chart-created
+    %}
+  </li>
+  <li>
+    {% capture jfr-metrics-chart-finish %}
+    <p>
+        Click <i>Create</i> on the card to create a <i>source Recording</i>. <b>Cryostat</b> will walk you through creating the <b>Recording</b>. You can simply click through the form and accept the suggested default settings. This will begin a <b>Flight Recording</b> on the selected <b>Target</b> and send you to the <i>Recordings</i> view. Once you return to the <b>Dashboard</b> and the recording is available then <b>Cryostat</b> will begin to process and update the <b>Recording</b> to update the card visualization.
+    </p>
+    {% endcapture %}
+    {% include howto_step.html
+      summary="Start source <b>Flight Recording</b>"
+      image-name="4.0.0/dashboard/jfrmetrics.png"
+      caption="The <i>JFR Metrics Chart</i> <code>card</code> displayed with the <i>Memory Usage</i> metric."
+      text=jfr-metrics-chart-finish
+    %}
+  </li>
+</ol>
+
+#### [Diagnostic Actions Card](#diagnostic-actions-card)
+
+<ol>
+  <li>
+    {% capture diagnostics-card-text %}
+    <p>
+      The <i>Diagnostics</i> <code>card</code> allows you to perform non-metrics diagnostic actions against the selected <b>Target</b>. This <a href="#configure-feature-level"><i>Beta</i>-level feature</a>
+    </p>
+    <p>
+      The following diagnostic actions are available:
+      <ul>
+        <li><i>Request JVM to perform Garbage Collection</i></li>
+      </ul>
+    </p>
+    {% endcapture %}
+    {% include howto_step.html
+      summary="Add the <i>Diagnostics</i> <code>Card</code>"
+      image-name="4.0.0/dashboard/diagnostics-preview.png"
+      caption="Click on the <i>Diagnostics</i> <code>card</code>. No preview is available."
+      text=diagnostics-card-text
+    %}
+  </li>
+  <li>
+    {% capture diagnostics-card-created %}
+    <p>
+        After clicking <i>Finish</i>, the <code>card</code> will be added to the dashboard.
+    </p>
+    {% endcapture %}
+    {% include howto_step.html
+      summary="Finish <code>Card</code> Creation"
+      image-name="4.0.0/dashboard/diagnostics.png"
+      caption="The <i>Diagnostics</i> <code>card</code>."
+      text=diagnostics-card-created
+    %}
+  </li>
+</ol>
+
 ### [Configuring the Dashboard](#configuring-the-dashboard)
 The <i>Dashboard</i> is highly customizable and can be configured to display the <code>cards</code> you want to see. You can customize the layout of the <code>cards</code> on the dashboard by <i>Moving, Resizing</i>, and <i>Removing</i> <code>cards</code>.
 

guides/index.md

@@ -11,6 +11,8 @@ common actions and workflows of interest and why they are useful.
 
 {% include_relative _subsections/getting-help.md %}
 
+{% include_relative _subsections/configure-feature-level.md %}
+
 {% include_relative _subsections/navigate-the-dashboard.md %}
 
 {% include_relative _subsections/use-topology-view.md %}