[Research] Document Timeline visualization type

[joshuarrrr]

• [Research] Document timeline plugin
• [Research] Document vis_type_timeline plugin

[ananzh]

Research on timeline and vis_type_timeline plugin

Introduction

Currently, we have two Timeline related plugins exists in OpenSearch Dashboards (OSD) repo. One is Timeline application (timeline plugin) and the other one is Timeline visualization (vis_type_timeline plugin) in Visualize.

Timeline application

Activate timeline application

Timeline application is deprecated since kibana 7.0. If you want to activate and use Timeline as a separate application, you will need to set timeline.ui.enabled: true in the opensearch_dashboards.yml. Then run OSD normally and you will see Timeline at the right navigation bar with discover, dashboards, visualize and etc. as an application.

Use timeline application

Timeline application allows multiple timeline expressions and graphs. You could click add to add another one.

Work flow

The data fetch is through $scope.search() in the timelineController. $scope.search() sends a api request $http.post('../api/timeline/run') which actually routes to runRoute() in vis_type_timeline plugin. runRoute is the actually route method to send the request to OS to fetch response.

Saved Objects

There are two ways to save the timeline application. Therefore, there are two saved objects.

Save entire Timeline sheet

• Choose save entire Timeline sheet

• Save button calls saveSheet() which uses savedSheet.save() to save in the timelineController. Here savedSheet is the saved object (type: SavedSheet).

//src/legacy/core_plugins/timelion/public/app.js

function saveSheet() {
    savedSheet.timelion_sheet = $scope.state.sheet;
    savedSheet.timelion_interval = $scope.state.interval;
    savedSheet.timelion_columns = $scope.state.columns;
    savedSheet.timelion_rows = $scope.state.rows;
    savedSheet.save().then(function (id) {
      if (id) {
        toastNotifications.addSuccess(
          i18n('timelion.saveSheet.successNotificationText', {
            defaultMessage: `Saved sheet '{title}'`,
            values: { title: savedSheet.title },
          })
        );

        if (savedSheet.id !== $routeParams.id) {
          kbnUrl.change('/{{id}}', { id: savedSheet.id });
        }
      }
    });
  }

• However, when we click open in the top navigation and select the saved sheet. We only see the default expression.

• The SavedSheet saved object details are:

The reference object is:

• About multiple saved objects

Timeline application allows multiple timeline expressions and graphs. If there are more than one timeline expressions, all the expressions are saved in the timeline_sheet array. For example, we saved two expressions as test-2.

However, when we click open in the top navigation and select the saved sheet. Same as one expression, we don't see any saved expressions.

Save current expression as OpenSearch Dashboards dashboard

• Choose Save current expression as OpenSearch Dashboards dashboard panel

• Save button calls saveExpression() in the timelineController. savedExpression is a SavedVis object, which has visualization (vis), visState (include expression). It calls save() in src/ui/public/courier/saved_object/saved_object.js to save the objects.

// src/legacy/core_plugins/timelion/public/app.js

  function saveExpression(title) {
    savedVisualizations.get({ type: 'timelion' }).then(function (savedExpression) {
      savedExpression.visState.params = {
        expression: $scope.state.sheet[$scope.state.selected],
        interval: $scope.state.interval
      };
      savedExpression.title = title;
      savedExpression.visState.title = title;
      savedExpression.save().then(function (id) {
        if (id) {
          toastNotifications.addSuccess(
            i18n('timelion.saveExpression.successNotificationText', {
              defaultMessage: `Saved expression '{title}'`,
              values: { title: savedExpression.title },
            }),
          );
        }
      });
    });
  }
 

• SavedVis can only be open in the visualization page. Need to route to visualize and open.
• The SavedVis saved object details are:

We could see the expression is saved in VisState.

The reference object is:

• About multiple saved objects

Only the last expression is saved. For the same example, we could see only metric:"avg:machine.ram" is saved.

When open the saved visualization, only see one timeline graph which matches the saved expression

[ananzh]

Timeline visualization

Create a timeline visualization

• Navigate to Visualize and click the Timeline icon.

• Enter the expression and adjust the time range then run.

Workflow

Saved Objects

• The saved object type of timeline visualization is SavedVis. The details are

• The reference object:

• The saved object of timeline visualization is the same as the saved object created by timeline application if chooses Save current expression as OpenSearch Dashboards dashboard. Therefore, there should be no migration issue between these two. The saved object created from Save entire Timeline sheet in timeline application will have migration issue.

[ananzh]

Done the research and close it