Show event context

docs/management/advanced-options.asciidoc

@@ -78,7 +78,6 @@ Markdown.
 `notifications:lifetime:error`:: Specifies the duration in milliseconds for error notification displays. The default value is 300000. Set this field to `Infinity` to disable error notifications.
 `notifications:lifetime:warning`:: Specifies the duration in milliseconds for warning notification displays. The default value is 10000. Set this field to `Infinity` to disable warning notifications.
 `notifications:lifetime:info`:: Specifies the duration in milliseconds for information notification displays. The default value is 5000. Set this field to `Infinity` to disable information notifications.
-
 `timelion:showTutorial`:: Set this property to `true` to show the Timelion tutorial to users when they first open Timelion.
 `timelion:es.timefield`:: Default field containing a timestamp when using the `.es()` query.
 `timelion:es.default_index`:: Default index when using the `.es()` query.
@@ -89,3 +88,5 @@ Markdown.
 `timelion:graphite.url`:: [experimental] Used with graphite queries, this it the URL of your host
 `timelion:quandl.key`:: [experimental] Used with quandl queries, this is your API key from www.quandl.com
 `state:storeInSessionStorage`:: [experimental] Kibana tracks UI state in the URL, which can lead to problems when there is a lot of information there and the URL gets very long. Enabling this will store parts of the state in your browser session instead, to keep the URL shorter.
+`context:defaultSize`:: Specifies the initial number of surrounding entries to display in the context view. The default value is 5.
+`context:step`:: Specifies the number to increment or decrement the context size by when using the buttons in the context view. The default value is 5.

src/core_plugins/kibana/public/context/NOTES.md

@@ -0,0 +1,97 @@
+# Discover Context App Implementation Notes
+
+The implementation of this app is intended to exhibit certain desirable
+properties by adhering to a set of *principles*. This document aims to explain
+those and the *concepts* employed to achieve that.
+
+
+## Principles
+
+**Single Source of Truth**: A good user experience depends on the UI displaying
+consistent information across the whole page. To achieve this, there should
+always be a single source of truth for the application's state. In this
+application this is the `ContextAppController::state` object.
+
+**Unidirectional Data Flow**: While a single state promotes rendering
+consistency, it does little to make the state changes easier to reason about.
+To avoid having state mutations scattered all over the code, this app
+implements a unidirectional data flow architecture. That means that the state
+is treated as immutable throughout the application except for actions, which
+may modify it to cause angular to re-render and watches to trigger.
+
+**Unit-Testability**: Creating unit tests for large parts of the UI code is
+made easy by expressing the as much of the logic as possible as
+side-effect-free functions. The only place where side-effects are allowed are
+actions. Due to the nature of AngularJS a certain amount of impure code must be
+employed in some cases, e.g. when dealing with the isolate scope bindings in
+`ContextAppController`.
+
+**Loose Coupling**: An attempt was made to couple the parts that make up this
+app as loosely as possible. This means using pure functions whenever possible
+and isolating the angular directives diligently. To that end, the app has been
+implemented as the independent `ContextApp` directive in [app.js](./app.js). It
+does not access the Kibana `AppState` directly but communicates only via its
+directive properties. The binding of these attributes to the state and thereby
+to the route is performed by the `CreateAppRouteController`in
+[index.js](./index.js). Similarly, the `SizePicker` directive only communicates
+with its parent via the passed properties.
+
+
+## Concepts
+
+To adhere to the principles mentioned above, this app borrows some concepts
+from the redux architecture that forms a ciruclar unidirectional data flow:
+
+```
+
+     |* create initial state
+     v
+  +->+
+  |  v
+  |  |* state
+  |  v
+  |  |* angular templates render state
+  |  v
+  |  |* angular calls actions in response to user action/system events
+  |  v
+  |  |* actions modify state
+  |  v
+  +--+
+
+```
+
+**State**: The state is the single source of truth at
+`ContextAppController::state` and may only be modified by actions.
+
+**Action**: Actions are functions that are called inreponse user or system
+actions and may modified the state the are bound to via their closure.
+
+
+## Directory Structure
+
+**index.js**: Defines the route and renders the `<context-app>` directive,
+binding it to the `AppState`.
+
+**app.js**: Defines the `<context-app>` directive, that is at the root of the
+application. Creates the store, reducer and bound actions/selectors.
+
+**query.js**: Exports the actions, reducers and selectors related to the
+query status and results.
+
+**query_parameters.js**: Exports the actions, reducers and selectors related to
+the parameters used to construct the query.
+
+**components/loading_button**: Defines the `<context-loading-button>`
+directive including its respective styles.
+
+**components/size_picker**: Defines the `<context-size-picker>`
+directive including its respective styles.
+
+**api/anchor.js**: Exports `fetchAnchor()` that creates and executes the
+query for the anchor document.
+
+**api/context.js**: Exports `fetchPredecessors()` and `fetchSuccessors()` that
+create and execute the queries for the preceeding and succeeding documents.
+
+**api/utils**: Exports various functions used to create and transform
+queries.

src/core_plugins/kibana/public/context/api/__tests__/anchor.js

@@ -0,0 +1,80 @@
+import expect from 'expect.js';
+import sinon from 'sinon';
+
+import { fetchAnchor } from 'plugins/kibana/context/api/anchor';
+
+
+describe('context app', function () {
+  describe('function fetchAnchor', function () {
+    it('should use the `search` api to query the given index', function () {
+      const indexPatternStub = createIndexPatternStub('index1');
+      const esStub = createEsStub(['hit1']);
+
+      return fetchAnchor(esStub, indexPatternStub, 'UID', { '@timestamp': 'desc' })
+        .then(() => {
+          expect(esStub.search.calledOnce).to.be(true);
+          expect(esStub.search.firstCall.args[0]).to.have.property('index', 'index1');
+        });
+    });
+
+    it('should include computed fields in the query', function () {
+      const indexPatternStub = createIndexPatternStub('index1');
+      const esStub = createEsStub(['hit1']);
+
+      return fetchAnchor(esStub, indexPatternStub, 'UID', { '@timestamp': 'desc' })
+        .then(() => {
+          expect(esStub.search.calledOnce).to.be(true);
+          expect(esStub.search.firstCall.args[0].body).to.have.keys([
+            'script_fields', 'docvalue_fields', 'stored_fields']);
+        });
+    });
+
+    it('should reject with an error when no hits were found', function () {
+      const indexPatternStub = createIndexPatternStub('index1');
+      const esStub = createEsStub([]);
+
+      return fetchAnchor(esStub, indexPatternStub, 'UID', { '@timestamp': 'desc' })
+        .then(
+          () => {
+            expect().fail('expected the promise to be rejected');
+          },
+          (error) => {
+            expect(error).to.be.an(Error);
+          }
+        );
+    });
+
+    it('should return the first hit after adding an anchor marker', function () {
+      const indexPatternStub = createIndexPatternStub('index1');
+      const esStub = createEsStub([{ property1: 'value1' }, {}]);
+
+      return fetchAnchor(esStub, indexPatternStub, 'UID', { '@timestamp': 'desc' })
+        .then((anchorDocument) => {
+          expect(anchorDocument).to.have.property('property1', 'value1');
+          expect(anchorDocument).to.have.property('$$_isAnchor', true);
+        });
+    });
+  });
+});
+
+
+function createIndexPatternStub(indices) {
+  return {
+    getComputedFields: sinon.stub()
+      .returns({}),
+    toIndexList: sinon.stub()
+      .returns(indices),
+  };
+}
+
+function createEsStub(hits) {
+  return {
+    search: sinon.stub()
+      .returns({
+        hits: {
+          hits,
+          total: hits.length,
+        },
+      }),
+  };
+}

src/core_plugins/kibana/public/context/api/anchor.js

@@ -0,0 +1,31 @@
+import _ from 'lodash';
+
+import { addComputedFields } from './utils/fields';
+import { createAnchorQueryBody } from './utils/queries';
+
+
+async function fetchAnchor(es, indexPattern, uid, sort) {
+  const indices = await indexPattern.toIndexList();
+  const queryBody = addComputedFields(indexPattern, createAnchorQueryBody(uid, sort));
+  const response = await es.search({
+    index: indices,
+    body: queryBody,
+  });
+
+  if (_.get(response, ['hits', 'total'], 0) < 1) {
+    throw new Error('Failed to load anchor document.');
+  }
+
+  return Object.assign(
+    {},
+    response.hits.hits[0],
+    {
+      $$_isAnchor: true,
+    },
+  );
+}
+
+
+export {
+  fetchAnchor,
+};

src/core_plugins/kibana/public/context/api/context.js

@@ -0,0 +1,47 @@
+import _ from 'lodash';
+
+import { addComputedFields } from './utils/fields';
+import { getDocumentUid } from './utils/ids';
+import { createSuccessorsQueryBody } from './utils/queries.js';
+import { reverseQuerySort } from './utils/sorting';
+
+
+async function fetchSuccessors(es, indexPattern, anchorDocument, sort, size) {
+  const successorsQueryBody = prepareQueryBody(indexPattern, anchorDocument, sort, size);
+  const results = await performQuery(es, indexPattern, successorsQueryBody);
+  return results;
+}
+
+async function fetchPredecessors(es, indexPattern, anchorDocument, sort, size) {
+  const successorsQueryBody = prepareQueryBody(indexPattern, anchorDocument, sort, size);
+  const predecessorsQueryBody = reverseQuerySort(successorsQueryBody);
+  const reversedResults = await performQuery(es, indexPattern, predecessorsQueryBody);
+  const results = reversedResults.slice().reverse();
+  return results;
+}
+
+
+function prepareQueryBody(indexPattern, anchorDocument, sort, size) {
+  const successorsQueryBody = addComputedFields(
+    indexPattern,
+    createSuccessorsQueryBody(anchorDocument.sort, sort, size)
+  );
+  return successorsQueryBody;
+}
+
+async function performQuery(es, indexPattern, queryBody) {
+  const indices = await indexPattern.toIndexList();
+
+  const response = await es.search({
+    index: indices,
+    body: queryBody,
+  });
+
+  return _.get(response, ['hits', 'hits'], []);
+}
+
+
+export {
+  fetchPredecessors,
+  fetchSuccessors,
+};

src/core_plugins/kibana/public/context/api/utils/__tests__/fields.js

@@ -0,0 +1,49 @@
+import expect from 'expect.js';
+
+import { addComputedFields } from 'plugins/kibana/context/api/utils/fields';
+
+
+describe('context app', function () {
+  describe('function addComputedFields', function () {
+    it('should add the `script_fields` property defined in the given index pattern', function () {
+      const getComputedFields = () => ({
+        scriptFields: {
+          sourcefield1: {
+            script: '_source.field1',
+          },
+        }
+      });
+
+      const query = addComputedFields({ getComputedFields }, {});
+      expect(query).to.have.property('script_fields');
+      expect(query.script_fields).to.eql(getComputedFields().scriptFields);
+    });
+
+    it('should add the `docvalue_fields` property defined in the given index pattern', function () {
+      const getComputedFields = () => ({
+        docvalueFields: ['field1'],
+      });
+
+      const query = addComputedFields({ getComputedFields }, {});
+      expect(query).to.have.property('docvalue_fields');
+      expect(query.docvalue_fields).to.eql(getComputedFields().docvalueFields);
+    });
+
+    it('should add the `stored_fields` property defined in the given index pattern', function () {
+      const getComputedFields = () => ({
+        storedFields: ['field1'],
+      });
+
+      const query = addComputedFields({ getComputedFields }, {});
+      expect(query).to.have.property('stored_fields');
+      expect(query.stored_fields).to.eql(getComputedFields().storedFields);
+    });
+
+    it('should preserve other properties of the query', function () {
+      const getComputedFields = () => ({});
+
+      const query = addComputedFields({ getComputedFields }, { property1: 'value1' });
+      expect(query).to.have.property('property1', 'value1');
+    });
+  });
+});

src/core_plugins/kibana/public/context/api/utils/__tests__/queries.js

@@ -0,0 +1,46 @@
+import expect from 'expect.js';
+
+import {
+  createAnchorQueryBody,
+  createSuccessorsQueryBody,
+} from 'plugins/kibana/context/api/utils/queries';
+
+
+describe('context app', function () {
+  describe('function createAnchorQueryBody', function () {
+    it('should return a search definition that searches the given uid', function () {
+      const query = createAnchorQueryBody('UID', { '@timestamp': 'desc' });
+      expect(query.query.terms._uid[0]).to.eql('UID');
+    });
+
+    it('should return a search definition that sorts by the given criteria and uid', function () {
+      const query = createAnchorQueryBody('UID', { '@timestamp': 'desc' });
+      expect(query.sort).to.eql([
+        { '@timestamp': 'desc' },
+        { _uid: 'asc' },
+      ]);
+    });
+  });
+
+  describe('function createSuccessorsQueryBody', function () {
+    it('should return a search definition that includes the given size', function () {
+      const query = createSuccessorsQueryBody([0, 'UID'], { '@timestamp' : 'desc' }, 10);
+      expect(query).to.have.property('size', 10);
+    });
+
+    it('should return a search definition that sorts by the given criteria and uid', function () {
+      const query = createSuccessorsQueryBody([0, 'UID'], { '@timestamp' : 'desc' }, 10);
+      expect(query).to.have.property('sort');
+      expect(query.sort).to.eql([
+        { '@timestamp': 'desc' },
+        { _uid: 'asc' },
+      ]);
+    });
+
+    it('should return a search definition that searches after the given uid', function () {
+      const query = createSuccessorsQueryBody([0, 'UID'], { '@timestamp' : 'desc' }, 10);
+      expect(query).to.have.property('search_after');
+      expect(query.search_after).to.eql([0, 'UID']);
+    });
+  });
+});