Add and update new, improved widgets & aggregations (#1172)

* Updates Rows-Columns to Group, edits to description * Updates log view create window image * Typo fix * Correct location of image * Remove old image * Commits previously untracked image * Adds new index item, shifts files in appropriate area * Fixes index with new entry * Attempt to restructure log view * Testing to see if change shows up in TOC * Get rid of unnecessary directory * Attempt to add file * Adds some content to the section * Minor updates * Build a new directory so index can reference it * Update log view page * Correct directory structure * Add lotsa text and pictorals * More images and narrative * Ensure log view page gets properly added * Commit latest changes to log view chapter * Updates index * Remove old forwarder doc * Updates to Log View and Widgets pages * Change wording of log view wording * Adds new updates and images to Log View chapter * Attempts to correct issue with directory * Fixes underline title, previously too * Minor word changes, typos caught by Dennis O
Graylog2 · Jul 2, 2021 · 23d7766 · 23d7766
1 parent f209aa3
commit 23d7766
Show file tree

Hide file tree

Showing 20 changed files with 156 additions and 23 deletions.
diff --git a/images/searching/aggregation_view.png b/images/searching/aggregation_view.png
diff --git a/images/searching/log_view_addl_values.png b/images/searching/log_view_addl_values.png
diff --git a/images/searching/log_view_default.png b/images/searching/log_view_default.png
diff --git a/images/searching/log_view_expand_arrow.png b/images/searching/log_view_expand_arrow.png
diff --git a/images/searching/log_view_expand_arrows.png b/images/searching/log_view_expand_arrows.png
diff --git a/images/searching/log_view_export_chevron.png b/images/searching/log_view_export_chevron.png
diff --git a/images/searching/log_view_field_selection_alternate.png b/images/searching/log_view_field_selection_alternate.png
diff --git a/images/searching/log_view_left_menu.png b/images/searching/log_view_left_menu.png
diff --git a/images/searching/log_view_select_fields.png b/images/searching/log_view_select_fields.png
diff --git a/images/searching/log_view_widget_focus_UI.png b/images/searching/log_view_widget_focus_UI.png
diff --git a/images/searching/log_view_widget_focus_icon_cu.png b/images/searching/log_view_widget_focus_icon_cu.png
diff --git a/images/searching/log_view_window.png b/images/searching/log_view_window.png
diff --git a/images/searching/views_empty_aggregation_edit.png b/images/searching/views_empty_aggregation_edit.png
diff --git a/images/searching/views_widget_create.png b/images/searching/views_widget_create.png
diff --git a/images/searching/widget_repositioning_resizing.png b/images/searching/widget_repositioning_resizing.png
diff --git a/index.rst b/index.rst
@@ -46,6 +46,7 @@ NOTE: There are multiple options for reading this documentation. See link to the
 
    pages/enterprise/intro
    pages/enterprise/setup
+   pages/enterprise/log_view_widget
    pages/archiving
    pages/auditlog
    pages/enterprise/forwarder

diff --git a/pages/enterprise/.DS_Store b/pages/enterprise/.DS_Store
diff --git a/pages/enterprise/log_view_widget.rst b/pages/enterprise/log_view_widget.rst
@@ -0,0 +1,121 @@
+###############
+Log View Widget
+###############
+
+********
+Overview
+********
+
+Log View is a widget that presents your log data in a format similar to Common Log Format. 
+In other terms, it has the look and feel of a console output. In addition, the Log View widget 
+allows you to scroll through log events as it populates new lines in real-time.
+
+Of course, the Log View widget will provide you a way to investigate your log events, to 
+accomplish such actions as:
+
+* recording faults to diagnose and debug
+* identifying security breaches and other system and network misuses.
+* auditing
+
+When you build aggregations in the Log View widget expect it to help you create highly 
+customizable reports and infographics. Furthermore, you can add them to your dashboards. 
+Also, you can save and retrieve them, in the event you need to review that data again. 
+At any time, you can add new values, fields, and metrics to build reports that you need.
+
+.. note::
+    According to the section :ref:`csv_export`, Graylog Open Source is limited to exports in CSV.
+    However, three additional formats are available in Enterprise: JSON, Newline delimited JSON, 
+    and Plain Text form.  
+
+Log View Usage
+==============
+
+To get familiar with Log View, perform the following actions.
+
+* Create a new Log View widget.
+* Expand your report with additional fields, in the widget.
+* Focus on the widget with an expanded view.
+* Export data from your widget.  
+
+.. _create_log_view:
+
+Create a Log View Widget
+------------------------
+
+The Log View Widget is located on the expandable bar, screen left. 
+
+.. image:: /images/searching/log_view_left_menu.png
+
+To create your first widget:
+
+#. Click the *Create* (+) button to extend the menu.
+#. Select Log View to generate the widget in the main UI.
+
+.. image:: /images/searching/log_view_default.png
+
+When the button generates a new widget, ``timestamp``, ``source``, and ``message`` are the default 
+fields presented in plain text format.
+
+.. _add_fields:
+
+Add New Fields to the Report
+----------------------------
+
+To build more informed reports, you might add a new field to the widget. For example, you may
+need to associate activity between ``company.org`` and an http response code.
+
+.. image:: /images/searching/log_view_expand_arrow.png
+
+#. Click the diagonal arrow icon on right side of a logline.
+#. Review and select one or more options, e.g. ``http_response_code``.
+
+.. image:: /images/searching/log_view_select_fields.png
+
+Alternately, you can add new fields via the chevron icon (mentioned in ":ref:`widgets-aggregation`").
+
+#. Click *Edit* from the menu.
+#. Locate *FIELD SELECTION AND ORDER* on the bottom left.
+#. Click the dropdown arrow, or type in a value.
+#. Click *Add* to include the field in your widget.
+#. Press the *Apply Changes* button to save all your edits. 
+
+.. image:: /images/searching/log_view_field_selection_alternate.png
+
+
+.. _widget_focus:
+
+Focus on the Widget
+-------------------
+
+When you return to the main Log View UI, identify the x-crossed arrow icon next to the other widget icons.
+
+.. image:: /images/searching/log_view_widget_focus_icon_cu.png
+
+Click the icon to expand your widget to full view:
+
+.. image:: /images/searching/log_view_widget_focus_UI.png
+
+
+Build a Dashboard with Shareable Data
+-------------------------------------
+
+In this section, you will determine a format that best suits your message delivery efforts, and download a report. 
+For example, you might pass on:
+
+* plain text data to your peers for analysis (i.e. *Log File/Plain Text*)
+* data to a logging library built in JavaScript (i.e. *JSON*)
+* structured data objects to TCP or UNIX pipes (i.e. *NDJSON*)
+
+If still configured, you may use the dashboard created in :ref:`create_log_view`.
+
+.. image:: /images/searching/log_view_export_chevron.png
+
+Follow the steps
+
+#. Click the chevron icon to access the *Actions* menu. (The icon is circled red in the image above.)
+#. Choose *Export* from the menu to access the dialog.
+
+    *  Output Format --- choose from JSON, Log File/Plain Text, NDJSON (Newline-delimited JSON), or CSV.
+    *  Fields to export --- add additional fields to the pre-defined options chosen in :ref:`add_fields`.
+    *  Time Range --- Click the clock icon to configure an Absolute date range. The format is displayed in yyyy-MMM-dd HH:mm:ss.SSS.
+#. Click the *Start Download* button after choosing all necessary fields and optional *Messages limit*.
diff --git a/pages/searching/csv_export.rst b/pages/searching/csv_export.rst
@@ -1,3 +1,5 @@
+.. _csv_export:
+
 Export results as CSV
 ^^^^^^^^^^^^^^^^^^^^^
 It is possible to export the results of your search as a CSV document. To do so, click on the three dots on the right side of the search bar and select the *Export to CSV* option.

diff --git a/pages/searching/widgets.rst b/pages/searching/widgets.rst
@@ -16,55 +16,61 @@ on the chevron on the right side in the head of the widget.
 
 Creating a widget
 ^^^^^^^^^^^^^^^^^
-To add a widget for your search or dashboard, open the sidebar and the "Create" section. You can also open the section directly by
-clicking on the plus sign.
+To add a widget for your search or dashboard:
 
-.. image:: /images/searching/views_widget_create.png
+* Open the sidebar and the *Create* section. 
+* Alternately, you can open the section directly by clicking on the plus sign (*+*).
+
+.. image:: /images/searching/log_view_window.png
    :align: center
 
-You can create an empty ":ref:`widgets-aggregation`". or a predefined widget by selecting the ":ref:`widgets-message-table`" or "Message Count" .
+You can create an empty ":ref:`widgets-aggregation`". or a predefined widget by selecting the ":ref:`widgets-message-table`" or "Message Count".
 
 Empty aggregation widget:
 
-.. image:: /images/searching/views_widget_aggregation_create.png
+.. image:: /images/searching/views_empty_aggregation_edit.png
    :align: center
 
 .. _widgets-aggregation:
 
 Aggregation
 ^^^^^^^^^^^
-The goal of an aggregation is to reduce the number of data points
-in a meaningful way to get an answer from them. Data points can be
-numeric field types in a message (e.g. a took_ms field which contains how
-long a page needed to be rendered).
-Or string values which can be used for grouping the aggregation
+The goal of an aggregation is to reduce the number of data points in a meaningful way to get an answer from them. 
+Data points can be numeric field types in a message (e.g. a ``took_ms`` field which contains how
+long a page needed to be rendered). Or string values which can be used for grouping the aggregation
 (e.g an action field which contains the name of the controller action).
 
 Configuring an aggregation
 """"""""""""""""""""""""""
-As describe in the previous section a click on `+ Create` -> `Aggreatation` will create an empty widget on the very top of the search page.
+As describe in the previous section a click on `+ Create` -> `Aggregation` will create an empty widget on the very top of the search page.
 A click on the `chevron icon -> Edit` on the right side of the head will open the widget edit modal.
 
-.. image:: /images/searching/widget_aggregation_edit.png
+.. image:: /images/searching/aggregation_view.png
    :align: center
 
-:METRICS:
-   **METRICS** are a collection of functions to aggregate data points.
-   The result of the aggregation depends on the grouping of **ROWS** and/or
-   **COLUMNS**. The data points of a field will be aggregated to the grouping.
-   *Example* The ``avg()`` function will find the average of the
-   numeric data points ``took_ms`` around the configured grouping. 
-
-:ROWS/COLUMNS:
-   Allows selecting fields whose values will be used to group results into
-   new rows/columns. If the field is a ``timestamp`` for a row it will
+:GROUP BY:
+   This option allows you to “group” your chart by rows and columns. 
+   When you create a new group with Group By, the values you select 
+   get rolled up into the result. This result can be presented in a 
+   variety of ways. You may present the data as a table, chart, 
+   or visualization with color.  
+
+   At a glance, if ``timestamp`` is a field attributed to a row it will 
    divide the data points into intervals. Otherwise the aggregation will take
    by default up to 15 elements of the selected field and apply the
    selected **METRICS** function to the data points.
+
    *Example* The ``timestamp`` field is aggregated with ``avg()`` on
    ``took_ms``. The column ``action`` will give the average loading
    time for a page per action for every 5 minutes.
 
+:METRICS:
+   **METRICS** are a collection of functions to aggregate data points.
+   The result of the aggregation depends on the grouping of **ROWS** and/or
+   **COLUMNS**. The data points of a field will be aggregated to the grouping.
+   *Example* The ``avg()`` function will find the average of the
+   numeric data points ``took_ms`` around the configured grouping. 
+
 :VISUALIZATION:
    To display the result of an aggregation it is often easier to
    compare lots of result values graphically. ``Area Chart``, ``Bar Chart``,
@@ -177,5 +183,8 @@ Widgets can be freely placed inside the search result grid. You can drag and dro
 left to the widget name or you resize them by using the gray arrow in their bottom-right corner.
 To expand a widget to the full grid width, click on the arrow in its top-right corner.
 
-.. image:: /images/searching/widget_repositioning_and_resizing.png
+.. image:: /images/searching/widget_repositioning_resizing.png
    :align: center
+
+If you want to expand the view of aggregated data in your *Log View* widget, go to :ref:`widget_focus` to 
+perform those steps.