Add first draft for Views documentation (#637)

* Add first draft on views

* Some small adjustments and adding missing screenshot

* Add forgotten screenshot

* Add Field and Value Actions

* Fix annotations from @dennisoelkers

index.rst

@@ -23,6 +23,7 @@ NOTE: There are multiple options for reading this documentation. See link to the
    pages/sending_data
    pages/sidecar
    pages/queries
+   pages/extended_search
    pages/streams
    pages/streams/alerts
    pages/dashboards

pages/extended_search.rst

@@ -0,0 +1,154 @@
+.. _extended_search:
+
+***************
+Extended Search
+***************
+
+Views
+=====
+A views contains a set of queries. Each query has a collection of widgets
+which display messages and charts depending on the search string entered
+in the search bar and the selected time range. A view can be saved with
+a name to keep the current progress and continue later on.
+Saved views can be shared, so other people can use them in their processes.
+For a better work flow Parameters can be added in the search query.
+Parameters are part of the Graylog Enterprise plugin.
+
+.. image:: /images/views_1.png
+
+Widgets
+=======
+A widget is either a Message Table or an Aggregation. It can be freely
+placed inside a query. A widget can be edited or duplicated by clicking
+on the chevron on the right side in the head of the widget.
+Next to the chevron is a filter symbol, where filters can be added to the
+top search query.
+
+.. image:: /images/views_widget.png
+
+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).
+
+Creating an aggregation
+-----------------------
+By clicking on `+ Create` -> `Custom Aggreatation` a new empty widget will
+be shown on the very top of the Extended Search page.
+A click on the chevron icon on the right side of the head will open the widget
+in a modal in the edit mode.
+
+.. image:: /images/views_create_aggregation.png
+
+: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
+   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.
+
+:VISUALIZATION:
+   To display the result of an aggregation it is often easier to
+   compare lots of result values graphically. ``Bar Chart``,
+   ``Data Table``, ``Line Chart``, ``Pie Chart``, ``Scatter Plot``,
+   ``Single Number`` or ``World Map`` can be used as **VISUALIZATION**.
+   The ``World Map`` needs geographical points in the form of ``latitude,longitude``.
+
+:SORTING/DIRECTION:
+   The order of the result values can be configured here. **SORTING** defines
+   by which field the sorting should happen and **DIRECTION** configures
+   if it will be ``ascending`` or ``descending``.
+
+Message Table
+=============
+
+The Message Table displays the messages and their fields.
+The Message Table can be configured to show the message fields and
+the actual message. The actual message is rendered in a blue font,
+below the fields.
+Clicking on a message row opens the detailed view of a message with
+all its fields.
+
+.. image:: /images/views_messages.png
+
+Value and Field Actions
+=======================
+In the Sidebar and on Data Tables and Detail Message Rows are values and
+fields visible. By clicking on a value or a field a context menu will be
+shown where different actions can be executed.
+
+Field actions
+-------------
+Based on the type of the field and where the menu is opened different
+Field actions are shown when a field name (and not its value) is clicked.
+
+.. image:: /images/views_field_actions.png
+
+:Chart:
+   This will generate a new Widget containing a line chart where the fields
+   average value is displayed over time. This chart can be taken as an
+   starting point for a more defined aggregation. This is only possible
+   on fields from a numerical type.
+:Aggregate:
+   This action will generate a new Widget containing a data table
+   where the fields value are listed in the rows and the count
+   of occurrence will be displayed next to it.
+   This was formerly known as the "Quick Values" action.
+:Statistics:
+   Here the field values will be given to various statistics function
+   depending on the type of the field. The result will be displayed
+   in a Data Table Widget.
+:Add to table:
+   Add the field to the displayed fields of the message table where
+   the Field Actions menu is shown.
+:Add to all tables:
+   Add the field to the displayed fields of all tables.
+:Remove from table:
+   Remove the field from the list displayed fields from this table.
+:Remove from table:
+   Remove the field from the list displayed fields from all tables.
+
+Value actions
+-------------
+The value actions produce different results depending on the type of the
+value and where the menu is opened. The following actions can be executed.
+
+.. image:: /images/views_value_actions.png
+
+:Insert into view:
+   This action will open up a modal where a view can be selected.
+   A select-able list of Parameters will be shown from the selected
+   view and after choosing a parameter a new browser tab will be
+   opened containing the view with the value used in the parameter.
+   This action is only available in enterprise Graylog.
+:Exclude from results:
+   Will add `NOT field:value` to the query to exclude all results
+   where the field contains the value of the value action.
+:Add to query:
+   Will add `field:value` to the query to filter the results
+   additionally for where the field has the value of the value action.
+:Use in new query:
+   Will open a new view tab with `field:value` as query string.
+:Show documents for value:
+   Available in Data Tables it will show the documents which
+   where aggregated to display this value.
+:Create extractor:
+   For values of type string in Message Tables a short cut to create
+   an extractor is given with this action.
+:Highlight this value:
+   This action will highlight this value for this field in all
+   Message Tables and Data Tables.