Merge pull request #55 from rashidkpc/master

Documentation

common/css/main.css

@@ -6,17 +6,19 @@
   color: #000;
 }
 
-.kibana-row {
-  margin-left: 15px;
-  margin-bottom: 15px;
-}
-
 .navbar .brand {
   color: #eee;
 }
 
 .navbar-inner {
-    border-width: 0 0 0px;
+  border-width: 0 0 0px;
+  padding-left: 0px;
+  padding-right: 0px;
+}
+
+.kibana-row {
+  margin-left: 15px;
+  margin-bottom: 15px;
 }
 
 .row-close {
@@ -54,6 +56,10 @@
   background-color: #f9f9f9;
 }
 
+.nomargin {
+  margin: 0px;
+}
+
 [ng\:cloak], [ng-cloak], .ng-cloak {
   display: none !important;
 }
@@ -90,7 +96,15 @@
   opacity: 1;
 }
 
-.pointer:hover {
+.link {
+  cursor: pointer;
+}
+
+.pointer {
+  cursor: pointer;
+}
+
+.link:hover {
   color: #0088CC;
 }
 
@@ -98,54 +112,42 @@
   max-width: 500px;
 }
 
-.pointer {
-  cursor: pointer;
+.popover-title { display: none; }
+
+.tiny {
+  font-size: 50%;
 }
 
 .small {
   font-size: 85%;
 }
 
-.input-append label {
-  font-size: inherit !important;
-}
-
 .large {
   font-size: 120%;
 }
 
-.nomargin {
-  margin: 0px;
-}
-
 .strong {
   font-weight: bold;
 }
 
-.btn-active {
-  background-color: #E6E6E6;
-  background-image: none;
-  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.15) inset, 0 1px 2px rgba(0, 0, 0, 0.05);
-  outline: 0 none
+.input-append label {
+  font-size: inherit !important;
 }
 
-.popover-title { display: none; }
-
 .input-smaller {
   width: 75px;
 }
 
-.tiny {
-  font-size: 50%;
+.typeahead { z-index: 1051; }
+
+.btn-active {
+  background-color: #E6E6E6;
+  background-image: none;
+  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.15) inset, 0 1px 2px rgba(0, 0, 0, 0.05);
+  outline: 0 none
 }
 
 .remove:hover {
   background-color: #A60000;
 }
 
-.typeahead { z-index: 1051; }
-
-.navbar-inner {
-  padding-left: 0px;
-  padding-right: 0px;
-}
\ No newline at end of file

panels/column/editor.html

@@ -33,4 +33,4 @@
       </table>
     </div>
   </div>
-</div>
\ No newline at end of file
+</div>

panels/column/module.js

+/*
+
+  ## Column
+
+  The column panel is sort of a hack to allow you to put multiple, veritcal, 
+  panels next to a bigger panel. Note that it has no group, and setting a group
+  for the panel itself will do nothing
+
+  ### Parameters
+  * panels :: an array of panel objects. All of their spans should be set to 12
+
+  ### Group Events
+  #### Sends
+  * time :: Object Includes from, to and index
+
+*/
+
 angular.module('kibana.column', [])
 .controller('column', function($scope, $rootScope) {
   // Set and populate defaults

panels/dashcontrol/module.js

+/*
+
+  ## Dashcontrol
+
+  Dash control allows for saving, loading and sharing of dashboards. Do not
+  disable the dashcontrol module as a special instance of it allows for loading
+  the default dashboard from dashboards/default
+
+  ### Parameters
+  * save
+  ** gist :: Allow saving to gist. Requires registering an oauth domain with Github
+  ** elasticsearch :: Allow saving to a special Kibana index within Elasticsearch
+  ** local :: Allow saving to local file
+  * load
+  ** gist :: Allow loading from gists
+  ** elasticsearch :: Allow searching and loading of elasticsearch saved dashboards
+  ** local :: Allow loading of dashboards from Elasticsearch
+  * hide_control :: Upon save, hide this panel
+  * elasticsearch_size :: show this many dashboards under the ES section in the load drop down
+  * elasticsearch_saveto :: Special kibana index to save to
+  * temp :: Allow saving of temp dashboards
+  * temp_ttl :: How long should temp dashboards persist
+
+  ### Group Events
+  #### Sends
+  * dashboard :: An object containing an entire dashboard to be loaded
+
+*/
+
 angular.module('kibana.dashcontrol', [])
 .controller('dashcontrol', function($scope, $routeParams, $http, eventBus, timer) {
   $scope.panel = $scope.panel || {};

panels/debug/module.js

+/*
+
+  ## Debug
+
+  Shows the exchange of events between panels. Disabled by default and usually
+  should be. This panel exists in the ALL group by default so that it receives
+  all of the events from every panel
+
+  ### Parameters
+  * size :: How many events to show
+  * style :: A hash containing css style parameters
+
+  ### Group Events
+  #### Receives
+  * $kibana_debug :: Contains a meta object of any event sent
+
+*/
+
 angular.module('kibana.debug', [])
 .controller('debug', function($scope, eventBus) {
 

panels/fields/module.js

+/*
+
+  ## Fields
+
+  Allows for enabling and disabling of fields in the table panel as well as a 
+  micro anaylsis panel for analyzing the events in the table panel
+
+  ### Parameters
+  * style :: a hash containing css styles
+  * arrange :: the layout pf the panel 'horizontal' or 'vertical'
+  * micropanel_position :: where to place the micropanel in relation to the field
+  
+  ### Group Events
+  #### Recieves
+  * table_documents :: An object containing the documents in the table panel
+  *** Sends
+  * fields :: an object containing the sort order, existing fields and selected fields
+
+*/
 angular.module('kibana.fields', [])
 .controller('fields', function($scope, eventBus, $timeout) {
 

panels/histogram/module.js

+/*
+
+  ## Histogram
+
+  A bucketted time series representation of the current query or queries. Note that this
+  panel uses facetting. I tried to make it safe by using sequential/serial querying but,
+  yeah, you should know that it uses facetting. It should be pretty safe.
+
+  ### Parameters
+  * query ::  an array of objects as such: {query: 'somequery', label 'legent text'}.
+              this is usually populated by a stringquery panel wher the query and label
+              parameter are the same
+  * interval :: Generated automatically. Tells ES how to bucket the data points
+  * fill :: Only applies to line charts. Level of area shading from 0-10
+  * linewidth ::  Only applies to line charts. How thick the line should be in pixels
+                  While the editor only exposes 0-10, this can be any numeric value. 
+                  Set to 0 and you'll get something like a scatter plot
+  * timezone :: This isn't totally functional yet. Currently only supports browser and utc.
+                browser will adjust the x-axis labels to match the timezone of the user's 
+                browser
+  * spyable ::  Dislay the 'eye' icon that show the last elasticsearch query
+  * zoomlinks :: Show the zoom links?
+  * bars :: Show bars in the chart
+  * stack :: Stack multiple queries. This generally a crappy way to represent things.
+             You probably should just use a line chart without stacking
+  * points :: Should circles at the data points on the chart
+  * lines :: Line chart? Sweet.
+  * legend :: Show the legend?
+  * x-axis :: Show x-axis labels and grid lines
+  * y-axis :: Show y-axis labels and grid lines
+  ### Group Events
+  #### Receives
+  * time :: An object containing the time range to use and the index(es) to query
+  * query :: An Array of queries, even if its only one
+  #### Sends
+  * get_time :: On panel initialization get time range to query
+
+*/
+
 angular.module('kibana.histogram', [])
 .controller('histogram', function($scope, eventBus) {
 

panels/hits/module.js

+/*
+
+  ## Hits
+
+  A variety of representations of the hits a query matches
+
+  ### Parameters
+  * query ::  An array of queries. No labels here, just an array of strings. Maybe
+              there should be labels. Probably. 
+  * style :: A hash of css styles
+  * arrangement :: How should I arrange the query results? 'horizontal' or 'vertical'
+  * chart :: Show a chart? 'none', 'bar', 'pie'
+  * donut :: Only applies to 'pie' charts. Punches a hole in the chart for some reason
+  * tilt :: Only 'pie' charts. Janky 3D effect. Looks terrible 90% of the time. 
+  * lables :: Only 'pie' charts. Labels on the pie?
+  ### Group Events
+  #### Sends
+  * get_time :: On panel initialization get time range to query
+  #### Receives
+  * time :: An object containing the time range to use and the index(es) to query
+  * query :: An Array of queries, even if its only one
+
+*/
 angular.module('kibana.hits', [])
 .controller('hits', function($scope, eventBus) {
 
   // Set and populate defaults
   var _d = {
-    query   : "*",
+    query   : ["*"],
     group   : "default",
     style   : { "font-size": '10pt'},
-    aggregate   : true,
     arrangement : 'vertical',
     chart       : 'none',
     counter_pos : 'above',

panels/map/module.js

+/*
+
+  ## Map
+
+  LOL. Should this even be documented? Zach's map panel is going to ruin this one. 
+  For serious. This shades a map of the world, the US or Europe with the number of 
+  events that match the query. Uses 2 letter country codes and nothing else. This uses
+  a terms facet. Its probably safe as long as you point it at the right field. Nach.
+  There's no way to query sequentially here, so I'm going to hit them all at once!
+
+  ### Parameters
+  * query ::  A single query string, not and array. This panel can only handle one
+              query at a time. 
+  * map :: 'world', 'us' or 'europe'
+  * colors :: an array of colors to use for the regions of the map. If this is a 2 
+              element array, jquerymap will generate shades between these colors 
+  * size :: How big to make the facet. Higher = more countries
+  * exclude :: Exlude the array of counties
+  * spyable :: Show the 'eye' icon that reveals the last ES query
+  * index_limit :: This does nothing yet. Eventually will limit the query to the first
+                   N indices
+  ### Group Events
+  #### Sends
+  * get_time :: On panel initialization get time range to query
+  #### Receives
+  * time :: An object containing the time range to use and the index(es) to query
+  * query :: An Array of queries, this panel uses only the first one
+*/
+
 angular.module('kibana.map', [])
 .controller('map', function($scope, eventBus) {
 

panels/pie/module.js

+/*
+
+  ## Pie
+
+  This panel is probably going away. For now its has 2 modes: 
+    * terms: Run a terms facet on the query. You're gonna have a bad (ES crashing) day
+    if you run in this mode on a high cardinality field
+    * goal: Compare the query to this number and display the percentage that the query
+    represents
+
+  ### Parameters
+  * query :: An object with 3 possible parameters depends on the mode:
+  ** field: Fields to run a terms facet on. Only does anything in terms mode
+  ** query: A string of the query to run
+  ** goal: How many to shoot for, only does anything in goal mode
+  * exclude :: In terms mode, ignore these terms
+  * donut :: Drill a big hole in the pie
+  * tilt :: A janky 3D representation of the pie. Looks terrible 90% of the time.
+  * legend :: Show the legend?
+  * labels :: Label the slices of the pie?
+  * mode :: 'terms' or 'goal'
+  * default_field ::  LOL wat? A dumb fail over field if for some reason the query object 
+                      doesn't have a field
+  * spyable :: Show the 'eye' icon that displays the last ES query for this panel
+
+  ### Group Events
+  #### Sends
+  * get_time :: On panel initialization get time range to query
+  #### Receives
+  * time :: An object containing the time range to use and the index(es) to query
+  * query :: An Array of queries, this panel will use the first in the array
+
+*/
+
 angular.module('kibana.pie', [])
 .controller('pie', function($scope, eventBus) {
 

panels/sort/module.js

+/*
+
+  ## Sort
+
+  This will probably be removed in the near future since it only interacts with 
+  the table panel and the table panel already implements all of its functionality.
+  It only interacts with the table panel in any case
+
+  ### Parameters
+  * label ::  The label to stick over the drop down
+  * sort :: An array where the first elemetn is the field to sort on an the second
+            is the direction ('asc' or 'desc')
+  ### Group Events
+  #### Sends
+  * sort :: An array where the first elemetn is the field to sort on an the second
+            is the direction ('asc' or 'desc')
+  #### Receives
+  * fields :: An array containing the fields in a table. This will be concat'd + 
+              uniqued with the curent list. 
+
+*/
+
 angular.module('kibana.sort', [])
 .controller('sort', function($scope, eventBus) {
 

panels/stringquery/editor.html

@@ -7,13 +7,6 @@
       <label class="small">Arrangement</label> 
       <select class="input-small" ng-model="panel.multi_arrange" ng-options="f for f in ['vertical','horizontal']"></select>
     </div>
-    <div class="span3" style="white-space:nowrap">
-      <label class="small">Sort</label>
-      <input ng-show="all_fields.length<=0 || !all_fields"style="width:85%" ng-model="panel.sort[0]" type="text"></input>
-      <select ng-show="all_fields.length>0"style="width:85%" ng-model="panel.sort[0]" ng-options="f for f in all_fields"></select>
-      <i ng-click="set_sort(panel.sort[0])" ng-class="{'icon-chevron-up': panel.sort[1] == 'asc','icon-chevron-down': panel.sort[1] == 'desc'}"></i>
-    </div>
-    <div>
   </div>
   <div class="row-fluid" ng-show="panel.multi">    
     <div class="span12">

panels/stringquery/module.js

+/*
+
+  ## Stringquery
+
+  Broadcasts a query object to other panels
+
+  ### Parameters
+  * label ::  The label to stick over the field 
+  * query ::  A string or an array of querys. String if multi is off, array if it is on
+              This should be fixed, it should always be an array even if its only 
+              one element
+  * multi :: Allow input of multiple queries? true/false
+  * multi_arrange :: How to arrange multu query string panels, 'vertical' or 'horizontal'
+  ### Group Events
+  #### Sends
+  * query :: Always broadcast as an array, even in multi: false
+  #### Receives
+  * query :: An array of queries. This is probably needs to be fixed.
+
+*/
+
 angular.module('kibana.stringquery', [])
 .controller('stringquery', function($scope, eventBus) {
 
@@ -5,8 +26,6 @@ angular.module('kibana.stringquery', [])
   var _d = {
     label   : "Search",
     query   : "*",
-    size    : 100,
-    sort    : ['_score','desc'],
     group   : "default",
     multi   : false,
     multi_arrange: 'horizontal',
@@ -41,13 +60,6 @@ angular.module('kibana.stringquery', [])
       new Array($scope.panel.query) : $scope.panel.query[0];
   }
 
-  $scope.set_sort = function(field) {
-    if($scope.panel.sort[0] === field)
-      $scope.panel.sort[1] = $scope.panel.sort[1] == 'asc' ? 'desc' : 'asc';
-    else
-      $scope.panel.sort[0] = field;
-  }
-
   $scope.remove_query = function(index) {
     $scope.panel.query.splice(index,1);
   }

panels/table/module.js

+/*
+
+  ## Table
+
+  A paginated table of events matching a query
+
+  ### Parameters
+  * query ::  A string representing then current query
+  * size :: Number of events per page to show
+  * pages :: Number of pages to show. size * pages = number of cached events. 
+             Bigger = more memory usage byh the browser
+  * offset :: Position from which to start in the array of hits
+  * sort :: An array with 2 elements. sort[0]: field, sort[1]: direction ('asc' or 'desc')
+  * style :: hash of css properties
+  * fields :: columns to show in table
+  * sortable :: Allow sorting?
+  * spyable :: Show the 'eye' icon that reveals the last ES query for this panel
+  ### Group Events
+  #### Sends
+  * table_documents :: An array containing all of the documents in the table. 
+                       Only used by the fields panel so far. 
+  #### Receives
+  * time :: An object containing the time range to use and the index(es) to query
+  * query :: An Array of queries, even if its only one
+  * sort :: An array with 2 elements. sort[0]: field, sort[1]: direction ('asc' or 'desc')
+  * selected_fields :: An array of fields to show
+*/
+
 angular.module('kibana.table', [])
 .controller('table', function($scope, eventBus, fields) {
 

panels/text/module.js

+/*
+
+  ## Text
+
+  A simple panel of static content
+
+  ### Parameters
+  * mode :: 'text', 'html', 'markdown'
+  * content :: Content of the panel
+  * style :: Hash containing css properties
+  
+*/
+
 angular.module('kibana.text', [])
 .controller('text', function($scope, $rootScope) {
 

panels/timepicker/module.js

 /*
-## Timepicker
-
-The timepicker panel is used to select time ranges and inform other panel of 
-them. It also handles searching for indices that match the given time range and 
-a pattern
-
-### Parameters
-* mode :: The default mode of the panel. Options: 'relative', 'absolute' 'since' Default: 'relative'
-* time_options :: An array of possible time options. Default: ['5m','15m','1h','6h','12h','24h','2d','7d','30d']
-* timespan :: The default options selected for the relative view. Default: '15m'
-* timefield :: The field in which time is stored in the document.
-* index :: Index pattern to match. Literals should be double quoted. Default: '_all'
-* defaultindex :: Index to failover to if index not found
-* refresh: Object containing refresh parameters
-  * enable :: true/false, enable auto refresh by default. Default: false
-  * interval :: Seconds between auto refresh. Default: 30
-  * min :: The lowest interval a user may set
-
-### Group Events
-#### Sends
-* time :: Object Includes from, to and index
-#### Receives
-* get_time :: Receives an object containing a uniqueid, broadcasts to it.
+
+  ## Timepicker
+
+  The timepicker panel is used to select time ranges and inform other panel of 
+  them. It also handles searching for indices that match the given time range and 
+  a pattern
+
+  ### Parameters
+  * mode :: The default mode of the panel. Options: 'relative', 'absolute' 'since' Default: 'relative'
+  * time_options :: An array of possible time options. Default: ['5m','15m','1h','6h','12h','24h','2d','7d','30d']
+  * timespan :: The default options selected for the relative view. Default: '15m'
+  * timefield :: The field in which time is stored in the document.
+  * index :: Index pattern to match. Literals should be double quoted. Default: '_all'
+  * defaultindex :: Index to failover to if index not found
+  * index_interval :: Time between timestamped indices (can be 'none') for static index
+  * refresh: Object containing refresh parameters
+    * enable :: true/false, enable auto refresh by default. Default: false
+    * interval :: Seconds between auto refresh. Default: 30
+    * min :: The lowest interval a user may set
+
+  ### Group Events
+  #### Sends
+  * time :: Object Includes from, to and index
+  #### Receives
+  * get_time :: Receives an object containing a $id, broadcasts back to it.
 
 */
+
 angular.module('kibana.timepicker', [])
 .controller('timepicker', function($scope, eventBus, $timeout, timer, $http) {
 
@@ -167,8 +170,8 @@ angular.module('kibana.timepicker', [])
     $scope.time_apply();
   }
 
-  $scope.time_check = function(){
-
+  // 
+  $scope.time_calc = function(){
     // If time picker is defined (on initialization)
     if(!(_.isUndefined($scope.timepicker))) {
       var from = $scope.panel.mode === 'relative' ? time_ago($scope.panel.timespan) :
@@ -198,7 +201,7 @@ angular.module('kibana.timepicker', [])
 
   $scope.time_apply = function() {      
     // Update internal time object
-    $scope.time = $scope.time_check();
+    $scope.time = $scope.time_calc();
     $scope.time.field = $scope.panel.timefield
 
     // Get indices for the time period, then broadcast time range and index list
@@ -213,12 +216,18 @@ angular.module('kibana.timepicker', [])
       eventBus.broadcast($scope.$id,$scope.panel.group,'time',$scope.time)
     }
 
-    // Update panel's string representation of the time object
-    $scope.panel.time = { 
-      from : $scope.time.from.format("mm/dd/yyyy HH:MM:ss"),
-      to : $scope.time.to.format("mm/dd/yyyy HH:MM:ss"),
-      index : $scope.time.index,
-    };
+    // Update panel's string representation of the time object.Don't update if
+    // we're in relative mode since we dont want to store the time object in the
+    // json for relative periods
+    if($scope.panel.mode !== 'relative') {
+      $scope.panel.time = { 
+        from : $scope.time.from.format("mm/dd/yyyy HH:MM:ss"),
+        to : $scope.time.to.format("mm/dd/yyyy HH:MM:ss"),
+        index : $scope.time.index,
+      };
+    } else {
+      delete $scope.panel.time;
+    }
   };
 
   function set_timepicker(from,to) {
@@ -272,6 +281,7 @@ angular.module('kibana.timepicker', [])
   // this is stupid, but there is otherwise no good way to ensure that when
   // I extract the date from an object that I'm get the UTC date. Stupid js.
   // I die a little inside every time I call this function.
+  // Update: I just read this again. I died a little more inside.
   function fake_utc(date) {
     return new Date(date.getTime() + date.getTimezoneOffset() * 60000);
   }