diff --git a/Gruntfile.js b/Gruntfile.js index dceb171f69d..bcc542e01d6 100644 --- a/Gruntfile.js +++ b/Gruntfile.js @@ -8,6 +8,7 @@ module.exports = function (grunt) { srcDir: 'src', destDir: 'dist', tempDir: 'tmp', + docsDir: 'docs/' }; // load plugins diff --git a/docs/kibana/configuration/config.js.asciidoc b/docs/kibana/configuration/config.js.asciidoc new file mode 100644 index 00000000000..2147c29a42c --- /dev/null +++ b/docs/kibana/configuration/config.js.asciidoc @@ -0,0 +1,29 @@ +== Configuration == +config.js is where you will find the core Kibana configuration. This file contains parameter that +must be set before kibana is run for the first time. +// src/config.js:1 + +=== Parameters === +// src/config.js:10 + +==== elasticsearch ==== + +The URL to your elasticsearch server. You almost certainly don't +want +http://localhost:9200+ here. Even if Kibana and Elasticsearch are on +the same host. By default this will attempt to reach ES at the same host you have +elasticsearch installed on. You probably want to set it to the FQDN of your +elasticsearch host +// src/config.js:15 + +==== kibana-int ==== + +The default ES index to use for storing Kibana specific object +such as stored dashboards +// src/config.js:26 + +==== panel_name ==== + +An array of panel modules available. Panels will only be loaded when they are defined in the +dashboard, but this list is used in the "add panel" interface. +// src/config.js:34 + diff --git a/docs/kibana/index.asciidoc b/docs/kibana/index.asciidoc new file mode 100644 index 00000000000..4e98149e15d --- /dev/null +++ b/docs/kibana/index.asciidoc @@ -0,0 +1,18 @@ += Kibana + +// Why can't I have a preamble here? + +== Introduction + +Kibana is an open source (Apache Licensed), browser based analytics and search dashboard for +ElasticSearch. Kibana is a snap to setup and start using. Written entirely in HTML and Javascript +it requires only a plain webserver, Kibana requires no fancy server side components. +Kibana strives to be easy to get started with, while also being flexible and powerful, just like +Elasticsearch. + +include::configuration/config.js.asciidoc[] + +include::panels.asciidoc[] + +// src/app/controllers/dash.js:1 + diff --git a/docs/kibana/panels.asciidoc b/docs/kibana/panels.asciidoc new file mode 100644 index 00000000000..a8c4c9bb3dc --- /dev/null +++ b/docs/kibana/panels.asciidoc @@ -0,0 +1,64 @@ +[[panels]] += Panels + +[partintro] +-- +*Kibana* dashboards are made up of blocks called +panels+. Panels are organized into rows +and can serve many purposes, though most are designed to provide the results of a query or +multiple queries as a visualization. Other panels may show collections of documents or +allow you to insert instructions for your users. + +Panels can be configured easily via the Kibana web interface. For more advanced usage, such +as templated or scripted dashboards, documentation of panel properties is available in this +section. You may find settings here which are not exposed via the web interface. + +Each panel type has its own properties, hover there are several that are shared. + +// src/app/controllers/row.js:61 + +span:: A number, 1-12, that describes the width of the panel. +// src/app/controllers/row.js:87 + +editable:: Enable or disable the edit button the the panel +// src/app/controllers/row.js:91 + +type:: The type of panel this object contains. Each panel type will require additional +properties. See the panel types list to the right. +// src/app/controllers/row.js:95 + +-- +// src/app/controllers/row.js:103 + +include::panels/bettermap.asciidoc[] +// src/app/panels/bettermap/module.js:1 + +include::panels/column.asciidoc[] +// src/app/panels/column/module.js:1 + +include::panels/histogram.asciidoc[] +// src/app/panels/histogram/module.js:1 + +include::panels/hits.asciidoc[] +// src/app/panels/hits/module.js:1 + +include::panels/map.asciidoc[] +// src/app/panels/map/module.js:1 + +include::panels/pie.asciidoc[] +// src/app/panels/pie/module.js:1 + +include::panels/sparklines.asciidoc[] +// src/app/panels/sparklines/module.js:1 + +include::panels/table.asciidoc[] +// src/app/panels/table/module.js:1 + +include::panels/terms.asciidoc[] +// src/app/panels/terms/module.js:1 + +include::panels/text.asciidoc[] +// src/app/panels/text/module.js:1 + +include::panels/trends.asciidoc[] +// src/app/panels/trends/module.js:1 + diff --git a/docs/kibana/panels/bettermap.asciidoc b/docs/kibana/panels/bettermap.asciidoc new file mode 100644 index 00000000000..8d13f7c0cfc --- /dev/null +++ b/docs/kibana/panels/bettermap.asciidoc @@ -0,0 +1,36 @@ +== Bettermap +Status: *Experimental* + +Bettermap is called bettermap for lack of a better name. Bettermap uses geographic coordinates to +create clusters of markers on map and shade them orange, yellow and green depending on the +density of the cluster. + +To drill down, click on a cluster. The map will be zoomed and the cluster broken into smaller cluster. +When it no longer makes visual sense to cluster, individual markers will be displayed. Hover over +a marker to see the tooltip value/ + +IMPORTANT: bettermap requires an internet connection to download its map panels. +// src/app/panels/bettermap/module.js:5 + +=== Parameters + +field:: The field that contains the coordinates, in geojson format. GeoJSON is ++[longitude,latitude]+ in an array. This is different from most implementations, which use +latitude, longitude. +// src/app/panels/bettermap/module.js:62 + +size:: The number of documents to use when drawing the map +// src/app/panels/bettermap/module.js:70 + +spyable:: Should the `inspect` icon be shown? +// src/app/panels/bettermap/module.js:74 + +tooltip:: Which field to use for the tooltip when hovering over a marker +// src/app/panels/bettermap/module.js:78 + +==== Queries +queries object:: This object describes the queries to use on this panel. +queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+ +queries.ids::: In +selected+ mode, which query ids are selected. +// src/app/panels/bettermap/module.js:82 + diff --git a/docs/kibana/panels/column.asciidoc b/docs/kibana/panels/column.asciidoc new file mode 100644 index 00000000000..643d50c4aad --- /dev/null +++ b/docs/kibana/panels/column.asciidoc @@ -0,0 +1,14 @@ +== Column +Status: *Stable* + +A pseudo panel that lets you add other panels to be arranged in a column with defined heights. +While the column panel is stable, it does have many limitations, including the inability to drag +and drop panels within its borders. It may be removed in a future release. + +// src/app/panels/column/module.js:5 + +=== Parameters + +panel:: An array of panel objects +// src/app/panels/column/module.js:36 + diff --git a/docs/kibana/panels/histogram.asciidoc b/docs/kibana/panels/histogram.asciidoc new file mode 100644 index 00000000000..0cde6be0ef9 --- /dev/null +++ b/docs/kibana/panels/histogram.asciidoc @@ -0,0 +1,129 @@ +== Histogram +Status: *Stable* + +The histogram panel allow for the display of time charts. It includes several modes and tranformations +to display event counts, mean, min, max and total of numeric fields, and derivatives of counter +fields. + +// src/app/panels/histogram/module.js:5 + +=== Parameters +==== Axis options +mode:: Value to use for the y-axis. For all modes other than count, +value_field+ must be +defined. Possible values: count, mean, max, min, total. +// src/app/panels/histogram/module.js:65 + +time_field:: x-axis field. This must be defined as a date type in Elasticsearch. +// src/app/panels/histogram/module.js:72 + +value_field:: y-axis field if +mode+ is set to mean, max, min or total. Must be numeric. +// src/app/panels/histogram/module.js:76 + +x-axis:: Show the x-axis +// src/app/panels/histogram/module.js:80 + +y-axis:: Show the y-axis +// src/app/panels/histogram/module.js:84 + +scale:: Scale the y-axis by this factor +// src/app/panels/histogram/module.js:88 + +y_as_bytes:: Show the y-axis scale as bytes, automatically round to KB, MB, GB, etc. +// src/app/panels/histogram/module.js:92 + +==== Annotations +annotate object:: A query can be specified, the results of which will be displayed as markers on +the chart. For example, for noting code deploys. +annotate.enable::: Should annotations, aka markers, be shown? +annotate.query::: Lucene query_string syntax query to use for markers. +annotate.size::: Max number of markers to show +annotate.field::: Field from documents to show +annotate.sort::: Sort array in format [field,order], For example [`@timestamp',`desc'] +// src/app/panels/histogram/module.js:115 + +==== Interval options +auto_int:: Automatically scale intervals? +// src/app/panels/histogram/module.js:132 + +resolution:: If auto_int is true, shoot for this many bars. +// src/app/panels/histogram/module.js:137 + +interval:: If auto_int is set to false, use this as the interval. +// src/app/panels/histogram/module.js:141 + +interval:: Array of possible intervals in the *View* selector. Example [`auto',`1s',`5m',`3h'] +// src/app/panels/histogram/module.js:145 + +==== Drawing options +lines:: Show line chart +// src/app/panels/histogram/module.js:149 + +fill:: Area fill factor for line charts, 1-10 +// src/app/panels/histogram/module.js:154 + +linewidth:: Weight of lines in pixels +// src/app/panels/histogram/module.js:158 + +points:: Show points on chart +// src/app/panels/histogram/module.js:162 + +pointradius:: Size of points in pixels +// src/app/panels/histogram/module.js:166 + +bars:: Show bars on chart +// src/app/panels/histogram/module.js:170 + +stack:: Stack multiple series +// src/app/panels/histogram/module.js:174 + +spyable:: Show inspect icon +// src/app/panels/histogram/module.js:178 + +zoomlinks:: Show `Zoom Out' link +// src/app/panels/histogram/module.js:182 + +options:: Show quick view options section +// src/app/panels/histogram/module.js:186 + +legend:: Display the legond +// src/app/panels/histogram/module.js:190 + +show_query:: If no alias is set, should the query be displayed? +// src/app/panels/histogram/module.js:194 + +interactive:: Enable click-and-drag to zoom functionality +// src/app/panels/histogram/module.js:198 + +legend_counts:: Show counts in legend +// src/app/panels/histogram/module.js:202 + +==== Transformations +timezone:: Correct for browser timezone?. Valid values: browser, utc +// src/app/panels/histogram/module.js:206 + +percentage:: Show the y-axis as a percentage of the axis total. Only makes sense for multiple +queries +// src/app/panels/histogram/module.js:211 + +zerofill:: Improves the accuracy of line charts at a small performance cost. +// src/app/panels/histogram/module.js:216 + +derivative:: Show each point on the x-axis as the change from the previous point +// src/app/panels/histogram/module.js:220 + +tooltip object:: +tooltip.value_type::: Individual or cumulative controls how tooltips are display on stacked charts +tooltip.query_as_alias::: If no alias is set, should the query be displayed? +// src/app/panels/histogram/module.js:224 + +grid object:: Min and max y-axis values +grid.min::: Minimum y-axis value +grid.max::: Maximum y-axis value +// src/app/panels/histogram/module.js:96 + +==== Queries +queries object:: This object describes the queries to use on this panel. +queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+ +queries.ids::: In +selected+ mode, which query ids are selected. +// src/app/panels/histogram/module.js:105 + diff --git a/docs/kibana/panels/hits.asciidoc b/docs/kibana/panels/hits.asciidoc new file mode 100644 index 00000000000..0a25543e465 --- /dev/null +++ b/docs/kibana/panels/hits.asciidoc @@ -0,0 +1,37 @@ +== Hits +Status: *Stable* + +The hits panel displays the number of hits for each of the queries on the dashboard in a +configurable format specified by the `chart' property. + +// src/app/panels/hits/module.js:5 + +=== Parameters + +arrangement:: The arrangement of the legend. horizontal or vertical +// src/app/panels/hits/module.js:49 + +chart:: bar, pie or none +// src/app/panels/hits/module.js:55 + +counter_pos:: The position of the legend, above or below +// src/app/panels/hits/module.js:59 + +donut:: If the chart is set to pie, setting donut to true will draw a hole in the midle of it +// src/app/panels/hits/module.js:63 + +tilt:: If the chart is set to pie, setting tilt to true will tilt it back into an oval +// src/app/panels/hits/module.js:67 + +labels:: If the chart is set to pie, setting labels to true will draw labels in the slices +// src/app/panels/hits/module.js:71 + +spyable:: Setting spyable to false disables the inspect icon. +// src/app/panels/hits/module.js:75 + +==== Queries +queries object:: This object describes the queries to use on this panel. +queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+ +queries.ids::: In +selected+ mode, which query ids are selected. +// src/app/panels/hits/module.js:79 + diff --git a/docs/kibana/panels/map.asciidoc b/docs/kibana/panels/map.asciidoc new file mode 100644 index 00000000000..5fd7faeb578 --- /dev/null +++ b/docs/kibana/panels/map.asciidoc @@ -0,0 +1,32 @@ +== Map +Status: *Stable* + +The map panel translates 2 letter country or state codes into shaded regions on a map. Currently +available maps are world, usa and europe. + +// src/app/panels/map/module.js:5 + +=== Parameters + +map:: Map to display. world, usa, europe +// src/app/panels/map/module.js:48 + +colors:: An array of colors to use to shade the map. If 2 colors are specified, shades +between them will be used. For example [`#A0E2E2', `#265656'] +// src/app/panels/map/module.js:54 + +size:: Max number of regions to shade +// src/app/panels/map/module.js:59 + +exclude:: exclude this array of regions. For example [`US',`BR',`IN'] +// src/app/panels/map/module.js:63 + +spyable:: Setting spyable to false disables the inspect icon. +// src/app/panels/map/module.js:67 + +==== Queries +queries object:: This object describes the queries to use on this panel. +queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+ +queries.ids::: In +selected+ mode, which query ids are selected. +// src/app/panels/map/module.js:71 + diff --git a/docs/kibana/panels/pie.asciidoc b/docs/kibana/panels/pie.asciidoc new file mode 100644 index 00000000000..b1ec93e511f --- /dev/null +++ b/docs/kibana/panels/pie.asciidoc @@ -0,0 +1,50 @@ +== Pie +Status: *Deprecated* + +The pie panel has been largely replaced by the +terms+ panel. It exists for backwards compatibility +for now, but will be removed in a future release + +// src/app/panels/pie/module.js:5 + +=== Parameters + +mode:: terms or goal. Terms mode finds the top N most popular terms, Goal mode display +progress towards a fix goal in terms of documents matched +// src/app/panels/pie/module.js:48 + +size:: The max number of results to display in +terms+ mode. +// src/app/panels/pie/module.js:55 + +exclude:: Exclude these terms in terms mode +// src/app/panels/pie/module.js:59 + +donut:: Draw a hole in the middle of the pie, creating a tasty donut. +// src/app/panels/pie/module.js:63 + +tilt:: Tilt the pie back into an oval shape +// src/app/panels/pie/module.js:67 + +legend:: The location of the legend, above, below or none +// src/app/panels/pie/module.js:71 + +labels:: Set to false to disable drawing labels inside the pie slices +// src/app/panels/pie/module.js:75 + +spyable:: Set to false to disable the inspect function. +// src/app/panels/pie/module.js:79 + +==== Query + +query object:: This confusingly named object has properties to set the terms mode field, +and the fixed goal for the goal mode +query.field::: the field to facet on in terms mode +query.goal::: the fixed goal for goal mode +// src/app/panels/pie/module.js:83 + +==== Queries + +queries object:: This object describes the queries to use on this panel. +queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+ +queries.ids::: In +selected+ mode, which query ids are selected. +// src/app/panels/pie/module.js:92 + diff --git a/docs/kibana/panels/sparklines.asciidoc b/docs/kibana/panels/sparklines.asciidoc new file mode 100644 index 00000000000..a26f0bb7abb --- /dev/null +++ b/docs/kibana/panels/sparklines.asciidoc @@ -0,0 +1,32 @@ +== Sparklines +Status: *Experimental* + +The sparklines panel shows tiny time charts. The purpose of these is not to give an exact value, +but rather to show the shape of the time series in a compact manner + +// src/app/panels/sparklines/module.js:5 + +=== Parameters +mode:: Value to use for the y-axis. For all modes other than count, +value_field+ must be +defined. Possible values: count, mean, max, min, total. +// src/app/panels/sparklines/module.js:56 + +time_field:: x-axis field. This must be defined as a date type in Elasticsearch. +// src/app/panels/sparklines/module.js:62 + +value_field:: y-axis field if +mode+ is set to mean, max, min or total. Must be numeric. +// src/app/panels/sparklines/module.js:66 + +interval:: Sparkline intervals are computed automatically as long as there is a time filter +present. In the absence of a time filter, use this interval. +// src/app/panels/sparklines/module.js:70 + +spyable:: Show inspect icon +// src/app/panels/sparklines/module.js:75 + +==== Queries +queries object:: This object describes the queries to use on this panel. +queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+ +queries.ids::: In +selected+ mode, which query ids are selected. +// src/app/panels/sparklines/module.js:79 + diff --git a/docs/kibana/panels/table.asciidoc b/docs/kibana/panels/table.asciidoc new file mode 100644 index 00000000000..4064dede990 --- /dev/null +++ b/docs/kibana/panels/table.asciidoc @@ -0,0 +1,63 @@ +== table +Status: *Stable* + +The table panel contains a sortable, pagable view of documents that. It can be arranged into +defined columns and offers several interactions, such as performing adhoc terms aggregations. + +// src/app/panels/table/module.js:5 + +=== Parameters + +size:: The number of hits to show per page +// src/app/panels/table/module.js:53 + +pages:: The number of pages available +// src/app/panels/table/module.js:59 + +offset:: The current page +// src/app/panels/table/module.js:63 + +sort:: An array describing the sort order of the table. For example [`@timestamp',`desc'] +// src/app/panels/table/module.js:67 + +overflow:: The css overflow property. `min-height' (expand) or `auto' (scroll) +// src/app/panels/table/module.js:71 + +fields:: the fields used a columns of the table, in an array. +// src/app/panels/table/module.js:75 + +highlight:: The fields on which to highlight, in an array +// src/app/panels/table/module.js:79 + +sortable:: Set sortable to false to disable sorting +// src/app/panels/table/module.js:83 + +header:: Set to false to hide the table column names +// src/app/panels/table/module.js:87 + +paging:: Set to false to hide the paging controls of the table +// src/app/panels/table/module.js:91 + +field_list:: Set to false to hide the list of fields. The user will be able to expand it, +but it will be hidden by default +// src/app/panels/table/module.js:95 + +all_fields:: Set to true to show all fields in the mapping, not just the current fields in +the table. +// src/app/panels/table/module.js:100 + +trimFactor:: The trim factor is the length at which to truncate fields takinging into +consideration the number of columns in the table. For example, a trimFactor of 100, with 5 +columns in the table, would trim each column at 20 character. The entirety of the field is +still available in the expanded view of the event. +// src/app/panels/table/module.js:105 + +spyable:: Set to false to disable the inspect icon +// src/app/panels/table/module.js:112 + +==== Queries +queries object:: This object describes the queries to use on this panel. +queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+ +queries.ids::: In +selected+ mode, which query ids are selected. +// src/app/panels/table/module.js:116 + diff --git a/docs/kibana/panels/terms.asciidoc b/docs/kibana/panels/terms.asciidoc new file mode 100644 index 00000000000..c20caf59078 --- /dev/null +++ b/docs/kibana/panels/terms.asciidoc @@ -0,0 +1,56 @@ +== terms +Status: *Stable* + +A table, bar chart or pie chart based on the results of an Elasticsearch terms facet. + +// src/app/panels/terms/module.js:5 + +=== Parameters + +field:: The field on which to computer the facet +// src/app/panels/terms/module.js:45 + +exclude:: terms to exclude from the results +// src/app/panels/terms/module.js:51 + +missing:: Set to false to disable the display of a counter showing how much results are +missing the field +// src/app/panels/terms/module.js:55 + +other:: Set to false to disable the display of a counter representing the aggregate of all +values outside of the scope of your +size+ property +// src/app/panels/terms/module.js:60 + +size:: Show this many terms +// src/app/panels/terms/module.js:65 + +order:: count, term, reverse_count or reverse_term +// src/app/panels/terms/module.js:69 + +donut:: In pie chart mode, draw a hole in the middle of the pie to make a tasty donut. +// src/app/panels/terms/module.js:74 + +tilt:: In pie chart mode, tilt the chart back to appear as more of an oval shape +// src/app/panels/terms/module.js:78 + +lables:: In pie chart mode, draw labels in the pie slices +// src/app/panels/terms/module.js:82 + +arrangement:: In bar or pie mode, arrangement of the legend. horizontal or vertical +// src/app/panels/terms/module.js:86 + +chart:: table, bar or pie +// src/app/panels/terms/module.js:90 + +counter_pos:: The location of the legend in respect to the chart, above or below. +// src/app/panels/terms/module.js:94 + +spyable:: Set spyable to false to disable the inspect button +// src/app/panels/terms/module.js:98 + +==== Queries +queries object:: This object describes the queries to use on this panel. +queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+ +queries.ids::: In +selected+ mode, which query ids are selected. +// src/app/panels/terms/module.js:102 + diff --git a/docs/kibana/panels/text.asciidoc b/docs/kibana/panels/text.asciidoc new file mode 100644 index 00000000000..da8cfb69cd1 --- /dev/null +++ b/docs/kibana/panels/text.asciidoc @@ -0,0 +1,16 @@ +== text +Status: *Stable* + +The text panel is used for displaying static text formated as markdown, sanitized html or as plain +text. + +// src/app/panels/text/module.js:5 + +=== Parameters + +mode:: `html', `markdown' or `text' +// src/app/panels/text/module.js:33 + +content:: The content of your panel, written in the mark up specified in +mode+ +// src/app/panels/text/module.js:39 + diff --git a/docs/kibana/panels/trends.asciidoc b/docs/kibana/panels/trends.asciidoc new file mode 100644 index 00000000000..ce90c34730b --- /dev/null +++ b/docs/kibana/panels/trends.asciidoc @@ -0,0 +1,27 @@ +== trends +Status: *Beta* + +A stock-ticker style representation of how queries are moving over time. For example, if the +time is 1:10pm, your time picker was set to "Last 10m", and the "Time Ago" parameter was set to +"1h", the panel would show how much the query results have changed since 12:00-12:10pm + +// src/app/panels/trends/module.js:5 + +=== Parameters + +ago:: A date math formatted string describing the relative time period to compare the +queries to. +// src/app/panels/trends/module.js:49 + +arrangement:: `horizontal' or `vertical' +// src/app/panels/trends/module.js:56 + +spyable:: Set to false to disable the inspect icon +// src/app/panels/trends/module.js:60 + +==== Queries +queries object:: This object describes the queries to use on this panel. +queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+ +queries.ids::: In +selected+ mode, which query ids are selected. +// src/app/panels/trends/module.js:64 + diff --git a/package.json b/package.json index 50fe9d8d154..d58807e4ec9 100644 --- a/package.json +++ b/package.json @@ -29,7 +29,8 @@ "grunt-contrib-uglify": "~0.2.4", "load-grunt-tasks": "~0.2.0", "glob": "~3.2.7", - "grunt-contrib-connect": "~0.5.0" + "grunt-contrib-connect": "~0.5.0", + "grunt-scratchy": "git://github.com/rashidkpc/grunt-scratchy.git" }, "license": "Apache License" } diff --git a/src/app/controllers/dash.js b/src/app/controllers/dash.js index 8a29a01355d..d15330346d4 100644 --- a/src/app/controllers/dash.js +++ b/src/app/controllers/dash.js @@ -1,3 +1,22 @@ +/** @scratch /index/0 + * = Kibana + * + * // Why can't I have a preamble here? + * + * == Introduction + * + * Kibana is an open source (Apache Licensed), browser based analytics and search dashboard for + * ElasticSearch. Kibana is a snap to setup and start using. Written entirely in HTML and Javascript + * it requires only a plain webserver, Kibana requires no fancy server side components. + * Kibana strives to be easy to get started with, while also being flexible and powerful, just like + * Elasticsearch. + * + * include::configuration/config.js.asciidoc[] + * + * include::panels.asciidoc[] + * + */ + define([ 'angular', 'config', diff --git a/src/app/controllers/row.js b/src/app/controllers/row.js index 6efa5effa5f..3fbd85f5edb 100644 --- a/src/app/controllers/row.js +++ b/src/app/controllers/row.js @@ -58,6 +58,25 @@ function (angular, app, _) { $scope.row.panels.push(panel); }; + /** @scratch /panels/0 + * [[panels]] + * = Panels + * + * [partintro] + * -- + * *Kibana* dashboards are made up of blocks called +panels+. Panels are organized into rows + * and can serve many purposes, though most are designed to provide the results of a query or + * multiple queries as a visualization. Other panels may show collections of documents or + * allow you to insert instructions for your users. + * + * Panels can be configured easily via the Kibana web interface. For more advanced usage, such + * as templated or scripted dashboards, documentation of panel properties is available in this + * section. You may find settings here which are not exposed via the web interface. + * + * Each panel type has its own properties, hover there are several that are shared. + * + */ + $scope.reset_panel = function(type) { var defaultSpan = 4, @@ -65,12 +84,26 @@ function (angular, app, _) { $scope.panel = { error : false, + /** @scratch /panels/1 + * span:: A number, 1-12, that describes the width of the panel. + */ span : _as < defaultSpan && _as > 0 ? _as : defaultSpan, + /** @scratch /panels/1 + * editable:: Enable or disable the edit button the the panel + */ editable: true, + /** @scratch /panels/1 + * type:: The type of panel this object contains. Each panel type will require additional + * properties. See the panel types list to the right. + */ type : type }; }; + /** @scratch /panels/2 + * -- + */ + $scope.init(); } diff --git a/src/app/panels/bettermap/module.js b/src/app/panels/bettermap/module.js index ef11c47a9b0..d1cfd14450e 100644 --- a/src/app/panels/bettermap/module.js +++ b/src/app/panels/bettermap/module.js @@ -1,13 +1,21 @@ -/* +/** @scratch /panels/5 + * include::panels/bettermap.asciidoc[] + */ - ## Better maps - - ### Parameters - * size :: How many results to show, more results = slower - * field :: field containing a 2 element array in the format [lon,lat] - * tooltip :: field to extract the tool tip value from - * spyable :: Show the 'eye' icon that reveals the last ES query -*/ +/** @scratch /panels/bettermap/0 + * == Bettermap + * Status: *Experimental* + * + * Bettermap is called bettermap for lack of a better name. Bettermap uses geographic coordinates to + * create clusters of markers on map and shade them orange, yellow and green depending on the + * density of the cluster. + * + * To drill down, click on a cluster. The map will be zoomed and the cluster broken into smaller cluster. + * When it no longer makes visual sense to cluster, individual markers will be displayed. Hover over + * a marker to see the tooltip value/ + * + * IMPORTANT: bettermap requires an internet connection to download its map panels. + */ define([ 'angular', 'app', @@ -51,21 +59,43 @@ function (angular, app, _, L, localRequire) { // Set and populate defaults var _d = { + /** @scratch /panels/bettermap/3 + * === Parameters + * + * field:: The field that contains the coordinates, in geojson format. GeoJSON is + * +[longitude,latitude]+ in an array. This is different from most implementations, which use + * latitude, longitude. + */ + field : null, + /** @scratch /panels/bettermap/5 + * size:: The number of documents to use when drawing the map + */ + size : 1000, + /** @scratch /panels/bettermap/5 + * spyable:: Should the `inspect` icon be shown? + */ + spyable : true, + /** @scratch /panels/bettermap/5 + * tooltip:: Which field to use for the tooltip when hovering over a marker + */ + tooltip : "_id", + /** @scratch /panels/bettermap/5 + * ==== Queries + * queries object:: This object describes the queries to use on this panel. + * queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+ + * queries.ids::: In +selected+ mode, which query ids are selected. + */ queries : { mode : 'all', ids : [] }, - size : 1000, - spyable : true, - tooltip : "_id", - field : null }; _.defaults($scope.panel,_d); - $scope.requireContext = localRequire; // inorder to use relative paths in require calls, require needs a context to run. Without // setting this property the paths would be relative to the app not this context/file. + $scope.requireContext = localRequire; $scope.init = function() { $scope.$on('refresh',function(){ @@ -204,6 +234,7 @@ function (angular, app, _, L, localRequire) { zoom: 10 }); + // This could be made configurable? L.tileLayer('http://{s}.tile.cloudmade.com/57cbb6ca8cac418dbb1a402586df4528/22677/256/{z}/{x}/{y}.png', { maxZoom: 18, minZoom: 2 diff --git a/src/app/panels/column/module.js b/src/app/panels/column/module.js index b81368dfd25..56687633e7a 100644 --- a/src/app/panels/column/module.js +++ b/src/app/panels/column/module.js @@ -1,11 +1,16 @@ -/* +/** @scratch /panels/5 + * include::panels/column.asciidoc[] + */ - ## Column - - ### Parameters - * panels :: an array of panel objects. All of their spans should be set to 12 - -*/ +/** @scratch /panels/column/0 + * == Column + * Status: *Stable* + * + * A pseudo panel that lets you add other panels to be arranged in a column with defined heights. + * While the column panel is stable, it does have many limitations, including the inability to drag + * and drop panels within its borders. It may be removed in a future release. + * + */ define([ 'angular', 'app', @@ -28,6 +33,11 @@ function (angular, app, _, config) { // Set and populate defaults var _d = { + /** @scratch /panels/column/3 + * === Parameters + * + * panel:: An array of panel objects + */ panels : [] }; _.defaults($scope.panel,_d); diff --git a/src/app/panels/histogram/module.js b/src/app/panels/histogram/module.js index 4fa4f8fc81f..217c69bf64f 100644 --- a/src/app/panels/histogram/module.js +++ b/src/app/panels/histogram/module.js @@ -1,32 +1,16 @@ -/* +/** @scratch /panels/5 + * include::panels/histogram.asciidoc[] + */ - ## Histogram - - ### Parameters - * auto_int :: Auto calculate data point interval? - * resolution :: If auto_int is enables, shoot for this many data points, rounding to - sane intervals - * interval :: Datapoint interval in elasticsearch date math format (eg 1d, 1w, 1y, 5y) - * 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 - * interactive :: Allow drag to select time range - -*/ +/** @scratch /panels/histogram/0 + * == Histogram + * Status: *Stable* + * + * The histogram panel allow for the display of time charts. It includes several modes and tranformations + * to display event counts, mean, min, max and total of numeric fields, and derivatives of counter + * fields. + * + */ define([ 'angular', 'app', @@ -78,12 +62,66 @@ function (angular, app, $, _, kbn, moment, timeSeries) { // Set and populate defaults var _d = { + /** @scratch /panels/histogram/3 + * === Parameters + * ==== Axis options + * mode:: Value to use for the y-axis. For all modes other than count, +value_field+ must be + * defined. Possible values: count, mean, max, min, total. + */ mode : 'count', + /** @scratch /panels/histogram/3 + * time_field:: x-axis field. This must be defined as a date type in Elasticsearch. + */ time_field : '@timestamp', - queries : { - mode : 'all', - ids : [] + /** @scratch /panels/histogram/3 + * value_field:: y-axis field if +mode+ is set to mean, max, min or total. Must be numeric. + */ + value_field : null, + /** @scratch /panels/histogram/3 + * x-axis:: Show the x-axis + */ + 'x-axis' : true, + /** @scratch /panels/histogram/3 + * y-axis:: Show the y-axis + */ + 'y-axis' : true, + /** @scratch /panels/histogram/3 + * scale:: Scale the y-axis by this factor + */ + scale : 1, + /** @scratch /panels/histogram/3 + * y_as_bytes:: Show the y-axis scale as bytes, automatically round to KB, MB, GB, etc. + */ + y_as_bytes : false, + /** @scratch /panels/histogram/5 + * grid object:: Min and max y-axis values + * grid.min::: Minimum y-axis value + * grid.max::: Maximum y-axis value + */ + grid : { + max: null, + min: 0 }, + /** @scratch /panels/histogram/5 + * ==== Queries + * queries object:: This object describes the queries to use on this panel. + * queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+ + * queries.ids::: In +selected+ mode, which query ids are selected. + */ + queries : { + mode : 'all', + ids : [] + }, + /** @scratch /panels/histogram/3 + * ==== Annotations + * annotate object:: A query can be specified, the results of which will be displayed as markers on + * the chart. For example, for noting code deploys. + * annotate.enable::: Should annotations, aka markers, be shown? + * annotate.query::: Lucene query_string syntax query to use for markers. + * annotate.size::: Max number of markers to show + * annotate.field::: Field from documents to show + * annotate.sort::: Sort array in format [field,order], For example [`@timestamp',`desc'] + */ annotate : { enable : false, query : "*", @@ -91,40 +129,106 @@ function (angular, app, $, _, kbn, moment, timeSeries) { field : '_type', sort : ['_score','desc'] }, - value_field : null, + /** @scratch /panels/histogram/3 + * ==== Interval options + * auto_int:: Automatically scale intervals? + */ auto_int : true, + /** @scratch /panels/histogram/3 + * resolution:: If auto_int is true, shoot for this many bars. + */ resolution : 100, + /** @scratch /panels/histogram/3 + * interval:: If auto_int is set to false, use this as the interval. + */ interval : '5m', + /** @scratch /panels/histogram/3 + * interval:: Array of possible intervals in the *View* selector. Example [`auto',`1s',`5m',`3h'] + */ intervals : ['auto','1s','1m','5m','10m','30m','1h','3h','12h','1d','1w','1y'], - fill : 0, - linewidth : 3, - pointradius : 5, - timezone : 'browser', // browser, utc or a standard timezone - spyable : true, - zoomlinks : true, - bars : true, - stack : true, - points : false, + /** @scratch /panels/histogram/3 + * ==== Drawing options + * lines:: Show line chart + */ lines : false, - legend : true, - show_query : true, - legend_counts : true, - 'x-axis' : true, - 'y-axis' : true, - percentage : false, - zerofill : true, - interactive : true, + /** @scratch /panels/histogram/3 + * fill:: Area fill factor for line charts, 1-10 + */ + fill : 0, + /** @scratch /panels/histogram/3 + * linewidth:: Weight of lines in pixels + */ + linewidth : 3, + /** @scratch /panels/histogram/3 + * points:: Show points on chart + */ + points : false, + /** @scratch /panels/histogram/3 + * pointradius:: Size of points in pixels + */ + pointradius : 5, + /** @scratch /panels/histogram/3 + * bars:: Show bars on chart + */ + bars : true, + /** @scratch /panels/histogram/3 + * stack:: Stack multiple series + */ + stack : true, + /** @scratch /panels/histogram/3 + * spyable:: Show inspect icon + */ + spyable : true, + /** @scratch /panels/histogram/3 + * zoomlinks:: Show `Zoom Out' link + */ + zoomlinks : true, + /** @scratch /panels/histogram/3 + * options:: Show quick view options section + */ options : true, + /** @scratch /panels/histogram/3 + * legend:: Display the legond + */ + legend : true, + /** @scratch /panels/histogram/3 + * show_query:: If no alias is set, should the query be displayed? + */ + show_query : true, + /** @scratch /panels/histogram/3 + * interactive:: Enable click-and-drag to zoom functionality + */ + interactive : true, + /** @scratch /panels/histogram/3 + * legend_counts:: Show counts in legend + */ + legend_counts : true, + /** @scratch /panels/histogram/3 + * ==== Transformations + * timezone:: Correct for browser timezone?. Valid values: browser, utc + */ + timezone : 'browser', // browser or utc + /** @scratch /panels/histogram/3 + * percentage:: Show the y-axis as a percentage of the axis total. Only makes sense for multiple + * queries + */ + percentage : false, + /** @scratch /panels/histogram/3 + * zerofill:: Improves the accuracy of line charts at a small performance cost. + */ + zerofill : true, + /** @scratch /panels/histogram/3 + * derivative:: Show each point on the x-axis as the change from the previous point + */ derivative : false, - scale : 1, - y_as_bytes : false, + /** @scratch /panels/histogram/3 + * tooltip object:: + * tooltip.value_type::: Individual or cumulative controls how tooltips are display on stacked charts + * tooltip.query_as_alias::: If no alias is set, should the query be displayed? + */ tooltip : { value_type: 'cumulative', query_as_alias: true - }, - grid : { - max: null, - min: 0 } }; diff --git a/src/app/panels/hits/module.js b/src/app/panels/hits/module.js index 09b9ee2ae9d..53e1fba8f6c 100644 --- a/src/app/panels/hits/module.js +++ b/src/app/panels/hits/module.js @@ -1,16 +1,15 @@ -/* +/** @scratch /panels/5 + * include::panels/hits.asciidoc[] + */ - ## Hits - - ### Parameters - * 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? - -*/ +/** @scratch /panels/hits/0 + * == Hits + * Status: *Stable* + * + * The hits panel displays the number of hits for each of the queries on the dashboard in a + * configurable format specified by the `chart' property. + * + */ define([ 'angular', 'app', @@ -46,18 +45,47 @@ define([ // Set and populate defaults var _d = { + style : { "font-size": '10pt'}, + /** @scratch /panels/hits/3 + * === Parameters + * + * arrangement:: The arrangement of the legend. horizontal or vertical + */ + arrangement : 'horizontal', + /** @scratch /panels/hits/3 + * chart:: bar, pie or none + */ + chart : 'bar', + /** @scratch /panels/hits/3 + * counter_pos:: The position of the legend, above or below + */ + counter_pos : 'above', + /** @scratch /panels/hits/3 + * donut:: If the chart is set to pie, setting donut to true will draw a hole in the midle of it + */ + donut : false, + /** @scratch /panels/hits/3 + * tilt:: If the chart is set to pie, setting tilt to true will tilt it back into an oval + */ + tilt : false, + /** @scratch /panels/hits/3 + * labels:: If the chart is set to pie, setting labels to true will draw labels in the slices + */ + labels : true, + /** @scratch /panels/hits/3 + * spyable:: Setting spyable to false disables the inspect icon. + */ + spyable : true, + /** @scratch /panels/hits/5 + * ==== Queries + * queries object:: This object describes the queries to use on this panel. + * queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+ + * queries.ids::: In +selected+ mode, which query ids are selected. + */ queries : { mode : 'all', ids : [] }, - style : { "font-size": '10pt'}, - arrangement : 'horizontal', - chart : 'bar', - counter_pos : 'above', - donut : false, - tilt : false, - labels : true, - spyable : true }; _.defaults($scope.panel,_d); diff --git a/src/app/panels/map/module.js b/src/app/panels/map/module.js index f13ed5fc7b9..4bd58e5e83f 100644 --- a/src/app/panels/map/module.js +++ b/src/app/panels/map/module.js @@ -1,19 +1,15 @@ -/* - - ## Map - - ### Parameters - * 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 - -*/ +/** @scratch /panels/5 + * include::panels/map.asciidoc[] + */ +/** @scratch /panels/map/0 + * == Map + * Status: *Stable* + * + * The map panel translates 2 letter country or state codes into shaded regions on a map. Currently + * available maps are world, usa and europe. + * + */ define([ 'angular', 'app', @@ -49,16 +45,39 @@ function (angular, app, _, $) { // Set and populate defaults var _d = { + /** @scratch /panels/map/3 + * === Parameters + * + * map:: Map to display. world, usa, europe + */ + map : "world", + /** @scratch /panels/map/3 + * colors:: An array of colors to use to shade the map. If 2 colors are specified, shades + * between them will be used. For example [`#A0E2E2', `#265656'] + */ + colors : ['#A0E2E2', '#265656'], + /** @scratch /panels/map/3 + * size:: Max number of regions to shade + */ + size : 100, + /** @scratch /panels/map/3 + * exclude:: exclude this array of regions. For example [`US',`BR',`IN'] + */ + exclude : [], + /** @scratch /panels/map/3 + * spyable:: Setting spyable to false disables the inspect icon. + */ + spyable : true, + /** @scratch /panels/map/5 + * ==== Queries + * queries object:: This object describes the queries to use on this panel. + * queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+ + * queries.ids::: In +selected+ mode, which query ids are selected. + */ queries : { mode : 'all', ids : [] - }, - map : "world", - colors : ['#A0E2E2', '#265656'], - size : 100, - exclude : [], - spyable : true, - index_limit : 0 + } }; _.defaults($scope.panel,_d); diff --git a/src/app/panels/pie/module.js b/src/app/panels/pie/module.js index 216a6b19839..d70009f1c49 100644 --- a/src/app/panels/pie/module.js +++ b/src/app/panels/pie/module.js @@ -1,21 +1,15 @@ -/* +/** @scratch /panels/5 + * include::panels/pie.asciidoc[] + */ - ## Pie - - ### Parameters - * query :: An object with 2 possible parameters depends on the mode: - ** field: Fields to run a terms facet on. Only does anything in terms mode - ** 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 -*/ +/** @scratch /panels/pie/0 + * == Pie + * Status: *Deprecated* + * + * The pie panel has been largely replaced by the +terms+ panel. It exists for backwards compatibility + * for now, but will be removed in a future release + * + */ define([ 'angular', 'app', @@ -51,20 +45,63 @@ define([ // Set and populate defaults var _d = { + /** @scratch /panels/pie/3 + * === Parameters + * + * mode:: terms or goal. Terms mode finds the top N most popular terms, Goal mode display + * progress towards a fix goal in terms of documents matched + */ + mode : "terms", + /** @scratch /panels/pie/3 + * size:: The max number of results to display in +terms+ mode. + */ + size : 10, + /** @scratch /panels/pie/3 + * exclude:: Exclude these terms in terms mode + */ + exclude : [], + /** @scratch /panels/pie/3 + * donut:: Draw a hole in the middle of the pie, creating a tasty donut. + */ + donut : false, + /** @scratch /panels/pie/3 + * tilt:: Tilt the pie back into an oval shape + */ + tilt : false, + /** @scratch /panels/pie/3 + * legend:: The location of the legend, above, below or none + */ + legend : "above", + /** @scratch /panels/pie/3 + * labels:: Set to false to disable drawing labels inside the pie slices + */ + labels : true, + /** @scratch /panels/pie/3 + * spyable:: Set to false to disable the inspect function. + */ + spyable : true, + /** @scratch /panels/pie/3 + * ==== Query + * + * query object:: This confusingly named object has properties to set the terms mode field, + * and the fixed goal for the goal mode + * query.field::: the field to facet on in terms mode + * query.goal::: the fixed goal for goal mode + */ query : { field:"_type", goal: 100}, + /** @scratch /panels/pie/5 + * ==== Queries + * + * queries object:: This object describes the queries to use on this panel. + * queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+ + * queries.ids::: In +selected+ mode, which query ids are selected. + */ queries : { mode : 'all', ids : [] }, - size : 10, - exclude : [], - donut : false, - tilt : false, - legend : "above", - labels : true, - mode : "terms", - default_field : 'DEFAULT', - spyable : true, + default_field : '_type', + }; _.defaults($scope.panel,_d); diff --git a/src/app/panels/sparklines/module.js b/src/app/panels/sparklines/module.js index 600d6b9e604..d0fce1ee3e7 100644 --- a/src/app/panels/sparklines/module.js +++ b/src/app/panels/sparklines/module.js @@ -1,32 +1,15 @@ -/* +/** @scratch /panels/5 + * include::panels/sparklines.asciidoc[] + */ - ## Histogram - - ### Parameters - * auto_int :: Auto calculate data point interval? - * resolution :: If auto_int is enables, shoot for this many data points, rounding to - sane intervals - * interval :: Datapoint interval in elasticsearch date math format (eg 1d, 1w, 1y, 5y) - * 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 - * interactive :: Allow drag to select time range - -*/ +/** @scratch /panels/sparklines/0 + * == Sparklines + * Status: *Experimental* + * + * The sparklines panel shows tiny time charts. The purpose of these is not to give an exact value, + * but rather to show the shape of the time series in a compact manner + * + */ define([ 'angular', 'app', @@ -70,15 +53,39 @@ function (angular, app, $, _, kbn, moment, timeSeries) { // Set and populate defaults var _d = { + /** @scratch /panels/sparklines/3 + * === Parameters + * mode:: Value to use for the y-axis. For all modes other than count, +value_field+ must be + * defined. Possible values: count, mean, max, min, total. + */ mode : 'count', + /** @scratch /panels/sparklines/3 + * time_field:: x-axis field. This must be defined as a date type in Elasticsearch. + */ time_field : '@timestamp', - queries : { - mode : 'all', - ids : [] - }, + /** @scratch /panels/sparklines/3 + * value_field:: y-axis field if +mode+ is set to mean, max, min or total. Must be numeric. + */ value_field : null, + /** @scratch /panels/sparklines/3 + * interval:: Sparkline intervals are computed automatically as long as there is a time filter + * present. In the absence of a time filter, use this interval. + */ interval : '5m', - spyable : true + /** @scratch /panels/sparklines/3 + * spyable:: Show inspect icon + */ + spyable : true, + /** @scratch /panels/sparklines/5 + * ==== Queries + * queries object:: This object describes the queries to use on this panel. + * queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+ + * queries.ids::: In +selected+ mode, which query ids are selected. + */ + queries : { + mode : 'all', + ids : [] + }, }; _.defaults($scope.panel,_d); diff --git a/src/app/panels/table/module.js b/src/app/panels/table/module.js index 897dd871a10..71c8aa887f4 100644 --- a/src/app/panels/table/module.js +++ b/src/app/panels/table/module.js @@ -1,31 +1,21 @@ -/* +/** @scratch /panels/5 + * include::panels/table.asciidoc[] + */ - ## Table - - ### Parameters - * 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 - * overflow :: 'height' or 'min-height' controls wether the row will expand (min-height) to - to fit the table, or if the table will scroll to fit the row (height) - * trimFactor :: If line is > this many characters, divided by the number of columns, trim it. - * sortable :: Allow sorting? - * spyable :: Show the 'eye' icon that reveals the last ES query for this panel - -*/ +/** @scratch /panels/table/0 + * == table + * Status: *Stable* + * + * The table panel contains a sortable, pagable view of documents that. It can be arranged into + * defined columns and offers several interactions, such as performing adhoc terms aggregations. + * + */ define([ 'angular', 'app', 'underscore', 'kbn', 'moment', - - // 'text!./pagination.html', - // 'text!partials/querySelect.html' ], function (angular, app, _, kbn, moment) { 'use strict'; @@ -60,27 +50,81 @@ function (angular, app, _, kbn, moment) { // Set and populate defaults var _d = { + /** @scratch /panels/table/5 + * === Parameters + * + * size:: The number of hits to show per page + */ + size : 100, // Per page + /** @scratch /panels/table/5 + * pages:: The number of pages available + */ + pages : 5, // Pages available + /** @scratch /panels/table/5 + * offset:: The current page + */ + offset : 0, + /** @scratch /panels/table/5 + * sort:: An array describing the sort order of the table. For example [`@timestamp',`desc'] + */ + sort : ['_score','desc'], + /** @scratch /panels/table/5 + * overflow:: The css overflow property. `min-height' (expand) or `auto' (scroll) + */ + overflow: 'min-height', + /** @scratch /panels/table/5 + * fields:: the fields used a columns of the table, in an array. + */ + fields : [], + /** @scratch /panels/table/5 + * highlight:: The fields on which to highlight, in an array + */ + highlight : [], + /** @scratch /panels/table/5 + * sortable:: Set sortable to false to disable sorting + */ + sortable: true, + /** @scratch /panels/table/5 + * header:: Set to false to hide the table column names + */ + header : true, + /** @scratch /panels/table/5 + * paging:: Set to false to hide the paging controls of the table + */ + paging : true, + /** @scratch /panels/table/5 + * field_list:: Set to false to hide the list of fields. The user will be able to expand it, + * but it will be hidden by default + */ + field_list: true, + /** @scratch /panels/table/5 + * all_fields:: Set to true to show all fields in the mapping, not just the current fields in + * the table. + */ + all_fields: false, + /** @scratch /panels/table/5 + * trimFactor:: The trim factor is the length at which to truncate fields takinging into + * consideration the number of columns in the table. For example, a trimFactor of 100, with 5 + * columns in the table, would trim each column at 20 character. The entirety of the field is + * still available in the expanded view of the event. + */ + trimFactor: 300, + /** @scratch /panels/table/5 + * spyable:: Set to false to disable the inspect icon + */ + spyable : true, + /** @scratch /panels/table/5 + * ==== Queries + * queries object:: This object describes the queries to use on this panel. + * queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+ + * queries.ids::: In +selected+ mode, which query ids are selected. + */ queries : { mode : 'all', ids : [] }, - size : 100, // Per page - pages : 5, // Pages available - offset : 0, - sort : ['_score','desc'], - group : "default", style : {'font-size': '9pt'}, - overflow: 'min-height', - fields : [], - highlight : [], - sortable: true, - header : true, - paging : true, - field_list: true, - all_fields: false, - trimFactor: 300, normTimes : true, - spyable : true }; _.defaults($scope.panel,_d); diff --git a/src/app/panels/terms/module.js b/src/app/panels/terms/module.js index baf0623a2dd..fe767360f22 100644 --- a/src/app/panels/terms/module.js +++ b/src/app/panels/terms/module.js @@ -1,15 +1,14 @@ -/* - ## Terms +/** @scratch /panels/5 + * include::panels/terms.asciidoc[] + */ - ### Parameters - * style :: A hash of css styles - * size :: top N - * 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? -*/ +/** @scratch /panels/terms/0 + * == terms + * Status: *Stable* + * + * A table, bar chart or pie chart based on the results of an Elasticsearch terms facet. + * + */ define([ 'angular', 'app', @@ -43,24 +42,73 @@ function (angular, app, _, $, kbn) { // Set and populate defaults var _d = { + /** @scratch /panels/terms/5 + * === Parameters + * + * field:: The field on which to computer the facet + */ + field : '_type', + /** @scratch /panels/terms/5 + * exclude:: terms to exclude from the results + */ + exclude : [], + /** @scratch /panels/terms/5 + * missing:: Set to false to disable the display of a counter showing how much results are + * missing the field + */ + missing : true, + /** @scratch /panels/terms/5 + * other:: Set to false to disable the display of a counter representing the aggregate of all + * values outside of the scope of your +size+ property + */ + other : true, + /** @scratch /panels/terms/5 + * size:: Show this many terms + */ + size : 10, + /** @scratch /panels/terms/5 + * order:: count, term, reverse_count or reverse_term + */ + order : 'count', + style : { "font-size": '10pt'}, + /** @scratch /panels/terms/5 + * donut:: In pie chart mode, draw a hole in the middle of the pie to make a tasty donut. + */ + donut : false, + /** @scratch /panels/terms/5 + * tilt:: In pie chart mode, tilt the chart back to appear as more of an oval shape + */ + tilt : false, + /** @scratch /panels/terms/5 + * lables:: In pie chart mode, draw labels in the pie slices + */ + labels : true, + /** @scratch /panels/terms/5 + * arrangement:: In bar or pie mode, arrangement of the legend. horizontal or vertical + */ + arrangement : 'horizontal', + /** @scratch /panels/terms/5 + * chart:: table, bar or pie + */ + chart : 'bar', + /** @scratch /panels/terms/5 + * counter_pos:: The location of the legend in respect to the chart, above or below. + */ + counter_pos : 'above', + /** @scratch /panels/terms/5 + * spyable:: Set spyable to false to disable the inspect button + */ + spyable : true, + /** @scratch /panels/terms/5 + * ==== Queries + * queries object:: This object describes the queries to use on this panel. + * queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+ + * queries.ids::: In +selected+ mode, which query ids are selected. + */ queries : { mode : 'all', ids : [] }, - field : '_type', - exclude : [], - missing : true, - other : true, - size : 10, - order : 'count', - style : { "font-size": '10pt'}, - donut : false, - tilt : false, - labels : true, - arrangement : 'horizontal', - chart : 'bar', - counter_pos : 'above', - spyable : true }; _.defaults($scope.panel,_d); diff --git a/src/app/panels/text/module.js b/src/app/panels/text/module.js index 0eeb65110e6..39e16f55599 100644 --- a/src/app/panels/text/module.js +++ b/src/app/panels/text/module.js @@ -1,10 +1,15 @@ -/* - ## Text - ### Parameters - * mode :: 'text', 'html', 'markdown' - * content :: Content of the panel - * style :: Hash containing css properties -*/ +/** @scratch /panels/5 + * include::panels/text.asciidoc[] + */ + +/** @scratch /panels/text/0 + * == text + * Status: *Stable* + * + * The text panel is used for displaying static text formated as markdown, sanitized html or as plain + * text. + * + */ define([ 'angular', 'app', @@ -25,8 +30,15 @@ function (angular, app, _, require) { // Set and populate defaults var _d = { - status : "Stable", - mode : "markdown", + /** @scratch /panels/text/5 + * === Parameters + * + * mode:: `html', `markdown' or `text' + */ + mode : "markdown", // 'html','markdown','text' + /** @scratch /panels/text/5 + * content:: The content of your panel, written in the mark up specified in +mode+ + */ content : "", style: {}, }; diff --git a/src/app/panels/trends/module.js b/src/app/panels/trends/module.js index bc0e5c31573..5efe02fb911 100644 --- a/src/app/panels/trends/module.js +++ b/src/app/panels/trends/module.js @@ -1,13 +1,16 @@ -/* +/** @scratch /panels/5 + * include::panels/trends.asciidoc[] + */ - ## Trends - - ### Parameters - * style :: A hash of css styles - * arrangement :: How should I arrange the query results? 'horizontal' or 'vertical' - * ago :: Date math formatted time to look back - -*/ +/** @scratch /panels/trends/0 + * == trends + * Status: *Beta* + * + * A stock-ticker style representation of how queries are moving over time. For example, if the + * time is 1:10pm, your time picker was set to "Last 10m", and the "Time Ago" parameter was set to + * "1h", the panel would show how much the query results have changed since 12:00-12:10pm + * + */ define([ 'angular', 'app', @@ -43,14 +46,32 @@ function (angular, app, _, kbn) { // Set and populate defaults var _d = { + /** @scratch /panels/trends/5 + * === Parameters + * + * ago:: A date math formatted string describing the relative time period to compare the + * queries to. + */ + ago : '1d', + /** @scratch /panels/trends/5 + * arrangement:: `horizontal' or `vertical' + */ + arrangement : 'vertical', + /** @scratch /panels/trends/5 + * spyable:: Set to false to disable the inspect icon + */ + spyable: true, + /** @scratch /panels/trends/5 + * ==== Queries + * queries object:: This object describes the queries to use on this panel. + * queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+ + * queries.ids::: In +selected+ mode, which query ids are selected. + */ queries : { mode : 'all', ids : [] }, style : { "font-size": '14pt'}, - ago : '1d', - arrangement : 'vertical', - spyable: true }; _.defaults($scope.panel,_d); diff --git a/src/config.js b/src/config.js index 80c0c8129a7..d993b020bde 100644 --- a/src/config.js +++ b/src/config.js @@ -1,36 +1,41 @@ -/** - * These is the app's configuration, If you need to configure - * the default dashboard, please see dashboards/default +/** @scratch /configuration/config.js/1 + * == Configuration == + * config.js is where you will find the core Kibana configuration. This file contains parameter that + * must be set before kibana is run for the first time. */ define(['settings'], function (Settings) { "use strict"; + /** @scratch /configuration/config.js/2 + * === Parameters === + */ return new Settings({ - /** - * URL to your elasticsearch server. You almost certainly don't - * want 'http://localhost:9200' here. Even if Kibana and ES are on - * the same host + /** @scratch /configuration/config.js/5 + * ==== elasticsearch ==== * - * By default this will attempt to reach ES at the same host you have + * The URL to your elasticsearch server. You almost certainly don't + * want +http://localhost:9200+ here. Even if Kibana and Elasticsearch are on + * the same host. By default this will attempt to reach ES at the same host you have * elasticsearch installed on. You probably want to set it to the FQDN of your * elasticsearch host - * @type {String} */ elasticsearch: "http://"+window.location.hostname+":9200", - /** + /** @scratch /configuration/config.js/5 + * ==== kibana-int ==== + * * The default ES index to use for storing Kibana specific object * such as stored dashboards - * @type {String} */ kibana_index: "kibana-int", - /** - * Panel modules available. Panels will only be loaded when they are defined in the + /** @scratch /configuration/config.js/5 + * ==== panel_name ==== + * + * An array of panel modules available. Panels will only be loaded when they are defined in the * dashboard, but this list is used in the "add panel" interface. - * @type {Array} */ panel_names: [ 'histogram', @@ -40,11 +45,9 @@ function (Settings) { 'filtering', 'timepicker', 'text', - 'fields', 'hits', 'dashcontrol', 'column', - 'derivequeries', 'trends', 'bettermap', 'query', diff --git a/tasks/default_task.js b/tasks/default_task.js index c81cf9ba610..95c15a81094 100644 --- a/tasks/default_task.js +++ b/tasks/default_task.js @@ -1,4 +1,4 @@ // Lint and build CSS module.exports = function(grunt) { - grunt.registerTask('default', ['jshint:source', 'less:src']); + grunt.registerTask('default', ['docs','jshint:source', 'less:src']); }; \ No newline at end of file diff --git a/tasks/docs_task.js b/tasks/docs_task.js new file mode 100644 index 00000000000..2ff68b885dc --- /dev/null +++ b/tasks/docs_task.js @@ -0,0 +1,4 @@ +// Lint and build CSS +module.exports = function(grunt) { + grunt.registerTask('docs', ['clean:docs', 'scratchy:docs']); +}; \ No newline at end of file diff --git a/tasks/options/clean.js b/tasks/options/clean.js index e1624ebae74..7db6ef22f26 100644 --- a/tasks/options/clean.js +++ b/tasks/options/clean.js @@ -2,5 +2,6 @@ module.exports = function(config) { return { on_start: ['<%= destDir %>', '<%= tempDir %>'], temp: ['<%= tempDir %>'], + docs: ['<%= docsDir %>'] }; }; \ No newline at end of file diff --git a/tasks/options/scratchy.js b/tasks/options/scratchy.js new file mode 100644 index 00000000000..a7f7ad2a486 --- /dev/null +++ b/tasks/options/scratchy.js @@ -0,0 +1,13 @@ +module.exports = function(config) { + return { + docs: { + src: ['src/app/**/*.js','src/config.js'], + dest: config.docsDir+"/kibana", + options: { + unslash: true, + extension: '.asciidoc', + annotate: '// ' + } + } + } +}; \ No newline at end of file