Show event context

docs/management/advanced-options.asciidoc

@@ -74,3 +74,5 @@ 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.
+`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,127 @@
+# 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 and a new state may only be
+derived via the root reducer (see below).
+
+**Unit-Testability**: Creating unit tests for large parts of the UI code is
+made easy by expressing the state management logic mostly as side-effect-free
+functions. The only place where side-effects are allowed are action creators
+and the reducer middlewares. 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
+  |  |* selectors calculate derived (memoized) values
+  |  v
+  |  |* angular templates render values
+  |  v
+  |  |* angular dispatches actions in response to user action/system events
+  |  v
+  |  |* middleware processes the action
+  |  v
+  |  |* reducer derives new state from action
+  |  v
+  +--+
+
+```
+
+**State**: The state is the single source of truth at
+`ContextAppController::state` and may only be replaced by a new state create
+via the root reducer.
+
+**Reducer**: The reducer at `ContextAppController.reducer` can derive a new
+state from the previous state and an action. It must be a pure function and can
+be composed from sub-reducers using various utilities like
+`createReducerPipeline`, that passes the action and the previous sub-reducer's
+result to each sub-reducer in order. The reducer is only called by the dispatch
+function located at `ContextAppController::dispatch`.
+
+**Action**: Actions are objets that describe user or system actions in a
+declarative manner. Each action is supposed to be passed to
+`ContextAppController::dispatch`, that passes them to each of its middlewares
+in turn before calling the root reducer with the final action. Usually, actions
+are created using helper functions called action creators to ensure they adhere
+to the [Flux Standard Action] schema.
+
+[Flux Standard Action]: https://github.com/acdlite/flux-standard-action
+
+**Selector**: To decouple the view from the specific state structure, selectors
+encapsulate the knowledge about how to retrieve a particular set of values from
+the state in a single location. Additionally, selectors can encapsulate the
+logic for calculating derived properties from the state, which should be kept
+as flat as possible and free of duplicate information. The performance penalty
+for performing these calculations at query time is commonly circumvented by
+memoizing the selector results as is the case with `createSelector` from
+[redux_lite/selector_helpers.js](./redux_lite/selector_helpers.js).
+
+
+## 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.
+
+**redux_lite**: Exports various functions to create the dispatcher, action
+creators, reducers and selectors.

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

@@ -0,0 +1,84 @@
+import { expect } from 'chai';
+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)
+            .to.have.lengthOf(1)
+            .with.deep.property('[0].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)
+            .to.have.lengthOf(1)
+            .with.deep.property('[0].body')
+              .that.contains.all.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(true, 'expected the promise to be rejected').to.be.false;
+          },
+          (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,27 @@
+import _ from 'lodash';
+
+import { addComputedFields } from './utils/fields';
+import { createAnchorQuery } from './utils/queries';
+
+
+async function fetchAnchor(es, indexPattern, uid, sort) {
+  const indices = await indexPattern.toIndexList();
+  const response = await es.search({
+    index: indices,
+    body: addComputedFields(indexPattern, createAnchorQuery(uid, sort)),
+  });
+
+  if (_.get(response, ['hits', 'total'], 0) < 1) {
+    throw new Error('Failed to load anchor row.');
+  }
+
+  return {
+    ...response.hits.hits[0],
+    $$_isAnchor: true,
+  };
+}
+
+
+export {
+  fetchAnchor,
+};

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

@@ -0,0 +1,53 @@
+import _ from 'lodash';
+
+import { addComputedFields } from './utils/fields';
+import { getDocumentUid } from './utils/ids';
+import { createSuccessorsQuery } from './utils/queries.js';
+import { reverseQuerySort } from './utils/sorting';
+
+
+async function fetchSuccessors(es, indexPattern, anchorDocument, sort, size) {
+  const successorsQuery = prepareQuery(indexPattern, anchorDocument, sort, size);
+  const results = await performQuery(es, indexPattern, successorsQuery);
+  return results;
+}
+
+async function fetchPredecessors(es, indexPattern, anchorDocument, sort, size) {
+  const successorsQuery = prepareQuery(indexPattern, anchorDocument, sort, size);
+  const predecessorsQuery = reverseQuerySort(successorsQuery);
+  const reversedResults = await performQuery(es, indexPattern, predecessorsQuery);
+  const results = reverseResults(reversedResults);
+  return results;
+}
+
+
+function prepareQuery(indexPattern, anchorDocument, sort, size) {
+  const anchorUid = getDocumentUid(anchorDocument._type, anchorDocument._id);
+  const successorsQuery = addComputedFields(
+    indexPattern,
+    createSuccessorsQuery(anchorUid, anchorDocument.sort, sort, size)
+  );
+  return successorsQuery;
+}
+
+async function performQuery(es, indexPattern, query) {
+  const indices = await indexPattern.toIndexList();
+
+  const response = await es.search({
+    index: indices,
+    body: query,
+  });
+
+  return _.get(response, ['hits', 'hits'], []);
+}
+
+function reverseResults(results) {
+  results.reverse();
+  return results;
+}
+
+
+export {
+  fetchPredecessors,
+  fetchSuccessors,
+};

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

@@ -0,0 +1,46 @@
+import { expect } from 'chai';
+
+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',
+          },
+        }
+      });
+
+      expect(addComputedFields({ getComputedFields }, {})).to.have.property('script_fields')
+        .that.is.deep.equal(getComputedFields().scriptFields);
+    });
+
+    it('should add the `docvalue_fields` property defined in the given index pattern', function () {
+      const getComputedFields = () => ({
+        docvalueFields: ['field1'],
+      });
+
+      expect(addComputedFields({ getComputedFields }, {})).to.have.property('docvalue_fields')
+        .that.is.deep.equal(getComputedFields().docvalueFields);
+    });
+
+    it('should add the `stored_fields` property defined in the given index pattern', function () {
+      const getComputedFields = () => ({
+        storedFields: ['field1'],
+      });
+
+      expect(addComputedFields({ getComputedFields }, {})).to.have.property('stored_fields')
+        .that.is.deep.equal(getComputedFields().storedFields);
+    });
+
+    it('should preserve other properties of the query', function () {
+      const getComputedFields = () => ({});
+
+      expect(addComputedFields({ getComputedFields }, { property1: 'value1' }))
+        .to.have.property('property1', 'value1');
+    });
+  });
+});

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

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