diff --git a/images/searching/aggregation_view.png b/images/searching/aggregation_view.png new file mode 100644 index 000000000..9cc0b702c Binary files /dev/null and b/images/searching/aggregation_view.png differ diff --git a/images/searching/log_view_addl_values.png b/images/searching/log_view_addl_values.png new file mode 100644 index 000000000..9c4040530 Binary files /dev/null and b/images/searching/log_view_addl_values.png differ diff --git a/images/searching/log_view_default.png b/images/searching/log_view_default.png new file mode 100644 index 000000000..c17a18cc6 Binary files /dev/null and b/images/searching/log_view_default.png differ diff --git a/images/searching/log_view_expand_arrow.png b/images/searching/log_view_expand_arrow.png new file mode 100644 index 000000000..4d3525c26 Binary files /dev/null and b/images/searching/log_view_expand_arrow.png differ diff --git a/images/searching/log_view_expand_arrows.png b/images/searching/log_view_expand_arrows.png new file mode 100644 index 000000000..21b720a1b Binary files /dev/null and b/images/searching/log_view_expand_arrows.png differ diff --git a/images/searching/log_view_export_chevron.png b/images/searching/log_view_export_chevron.png new file mode 100644 index 000000000..8c7320ff1 Binary files /dev/null and b/images/searching/log_view_export_chevron.png differ diff --git a/images/searching/log_view_field_selection_alternate.png b/images/searching/log_view_field_selection_alternate.png new file mode 100644 index 000000000..7814e4fc6 Binary files /dev/null and b/images/searching/log_view_field_selection_alternate.png differ diff --git a/images/searching/log_view_left_menu.png b/images/searching/log_view_left_menu.png new file mode 100644 index 000000000..776c473c8 Binary files /dev/null and b/images/searching/log_view_left_menu.png differ diff --git a/images/searching/log_view_select_fields.png b/images/searching/log_view_select_fields.png new file mode 100644 index 000000000..2ca4fcaf2 Binary files /dev/null and b/images/searching/log_view_select_fields.png differ diff --git a/images/searching/log_view_widget_focus_UI.png b/images/searching/log_view_widget_focus_UI.png new file mode 100644 index 000000000..828beee91 Binary files /dev/null and b/images/searching/log_view_widget_focus_UI.png differ diff --git a/images/searching/log_view_widget_focus_icon_cu.png b/images/searching/log_view_widget_focus_icon_cu.png new file mode 100644 index 000000000..c4e5da4d6 Binary files /dev/null and b/images/searching/log_view_widget_focus_icon_cu.png differ diff --git a/images/searching/log_view_window.png b/images/searching/log_view_window.png new file mode 100644 index 000000000..94d09e01c Binary files /dev/null and b/images/searching/log_view_window.png differ diff --git a/images/searching/views_empty_aggregation_edit.png b/images/searching/views_empty_aggregation_edit.png new file mode 100644 index 000000000..bf9a39540 Binary files /dev/null and b/images/searching/views_empty_aggregation_edit.png differ diff --git a/images/searching/views_widget_create.png b/images/searching/views_widget_create.png deleted file mode 100644 index 0ea87fdce..000000000 Binary files a/images/searching/views_widget_create.png and /dev/null differ diff --git a/images/searching/widget_repositioning_resizing.png b/images/searching/widget_repositioning_resizing.png new file mode 100644 index 000000000..4db58d1e8 Binary files /dev/null and b/images/searching/widget_repositioning_resizing.png differ diff --git a/index.rst b/index.rst index 62283d248..9a86fdf2e 100644 --- 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 new file mode 100644 index 000000000..934013dd0 Binary files /dev/null and b/pages/enterprise/.DS_Store differ diff --git a/pages/enterprise/log_view_widget.rst b/pages/enterprise/log_view_widget.rst new file mode 100644 index 000000000..d564180b5 --- /dev/null +++ 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*. \ No newline at end of file diff --git a/pages/searching/csv_export.rst b/pages/searching/csv_export.rst index 7facd39fd..6423d3c17 100644 --- 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 index 8af159e5a..af23e05f6 100644 --- 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. \ No newline at end of file