.. _analytics-building-a-dashboard-report:


Search Definitions
--------------------


Overview 
............

A saved search definition creates a dashboard and report with the title being 
the name you give the definition.  
      
You can create any number of combinations of saved search definitions 
on any log source (i.e. multiple search definitions on a DNS log).

The **Saved Definitions** drop-down lists all saved definitions that have been created. Each 
saved definition is a resource from which data can be pulled into a widget on a dashboard 
and report as you design them.
   
|saved-definitions|   



Configure a Saved Definition
..................................

This procedure configures a saved definition to add a dashboard and report. 


**Perform these steps**:

1. On the Insights Dashboard main interface, select the **Search** menu. 
2. On the **Create Definitions** tab, determine which logs contain the data you wish to analyze. 

   An example is DNS Logs from a Bind9 open source DNS server. In this case, type any word 
   contained in these logs, such as "queries", and then ensure that you have the 
   log coming from the Bind9 DNS server.
   
   |build_dash| 
   
#. Extract the fields you wish to analyze (perform this step for each field you wish to extract): 

   * Highlight the field by dragging the cursor over it, or double click the field. 
   * In the **Extract Field** dialog, fill out the field name. 
   * Click **Save**. 

     The automated Regular Expression engine extracts the field and saves the field name, which displays 
     beneath **Saved Definitions**.  
   
   |build-dash-extract-1|
   
#. At **Saved Definitions** click **New**, then click **Field**. 
#. At the **Type** field, choose the field type based on the context of the log, either Text, 
   Integer, Float, Epoch Date, or Calculation.
   
   |build-dash-extract-2|

   .. note:: 
      
      When selecting field type "Calculation", you'll need to specify the math to 
      derive an integer result. An example is a bandwidth calculation. In this case, 
      the result is stored with the definition and will  be available to utilize on a 
      dashboard. 
      
      Drag the field(s) to calculate, add a numeric input, and then design the 
      equation by dragging the operands and groupings.

      The equation will display below the bar to allow for easy checking of the logic. Click 
      **Test Calculation** to allow the system to perform the math and display the results 
      for further logic testing before saving the calculation.

      |build-dash-extract-calc|
   
#. Repeat these steps for each field you wish to analyze. 

#. Once complete, fill out a name for the new search definition. 



Manage Saved Definitions
.........................

This procedure clones, edits, and deletes saved definitions/resources. 


1. On the Insights Dashboard main interface, select the **Search** menu. 
2. On the **Create Definitions** tab, select a saved definition from the drop-down. 

3. Choose an option: 

   * Click **Clone** to copy an existing saved definition, then give the clone a new name. 
     Now you can simply change only the field extractions you want instead of creating
     them from new.

     |clone|
   
   * Modify an existing saved definition, then click **Save**. 
   
     When saving a modified definition, the dashboard updates when new 
     log data arrives into the system. 
  
   * Click **Delete** to remove a search definition from the list. 
   * **Summarize Data** gives you the option of consolidating the data from the logs
     based on time. Clicking the drop-down, allows you to choose the required
     interval on which the data will be summarized (Minute, 15 Minutes, 30 Minutes, 
     Hourly, and Daily). When invoking summarization all unique combinations of
     text fields will be kept.  

     |analytics-summarize-data|

     Integer fields are aggregated together with their associated operation (Counts 
     are summed; Min, Max, Avg, Stddev, and Variance aggregations are stored for 
     every integer field). This is a method of making the dashboards more responsive 
     since it will summarize the data and store only that one value versus all of
     the values. 
    
    
.. |build_dash| image:: /src/images/build_dash.png
.. |build-dash-extract-1| image:: /src/images/analytics-build-dash-extract-1.png
.. |build-dash-extract-2| image:: /src/images/analytics-build-dash-extract-2.png
.. |saved-definitions| image:: /src/images/analytics-saved-definitions.png
.. |clone| image:: /src/images/analytics-clone.png
.. |analytics-summarize-data| image:: /src/images/analytics-summarize-data.png
.. |build-dash-extract-calc| image:: /src/images/analytics-build-dash-extract-calc.png