kibana/rfcs/text/0009_screenshot_mode_service.md

• Start Date: 2020-03-02
• RFC PR: (leave this empty)
• Kibana Issue: (leave this empty)

Summary

Currently, the applications that support screenshot reports are:

• Dashboard
• Visualize Editor
• Canvas

Kibana UI code should be aware when the page is rendering for the purpose of capturing a screenshot. There should be a service to interact with low-level code for providing that awareness. Reporting would interact with this service to improve the quality of the Kibana Reporting feature for a few reasons:

• Fewer objects in the headless browser memory since interactive code doesn't run
• Fewer API requests made by the headless browser for features that don't apply in a non-interactive context

Screenshot mode service

The Reporting-enabled applications should use the recommended practice of having a customized URL for Reporting. The customized URL renders without UI features like navigation, auto-complete, and anything else that wouldn't make sense for non-interactive pages.

However, applications are one piece of the UI code in a browser, and they have dependencies on other UI plugins. Apps can't control plugins and other things that Kibana loads in the browser.

This RFC proposes a Screenshot Mode Service as a low-level plugin that allows other plugins (UI code) to make choices when the page is rendering for a screenshot.

More background on how Reporting currently works, including the lifecycle of creating a PNG report, is here: https://github.com/elastic/kibana/issues/59396

Motivation

The Reporting team wants all applications to support a customized URLs, such as Canvas does with its #/export/workpad/pdf/{workpadId} UI route. The customized URL is where an app can solve any rendering issue in a PDF or PNG, without needing extra CSS to be injected into the page.

However, many low-level plugins have been added to the UI over time. These run on every page and an application can not turn them off. Reporting performance is negatively affected by this type of code. When the Reporting team analyzes customer logs to figure out why a job timed out, we sometimes see requests for the newsfeed API and telemetry API: services that aren't needed during a reporting job.

In 7.12.0, using the customized /export/workpad/pdf in Canvas, the Sample Data Flights workpad loads 163 requests. Most of thees requests don't come from the app itself but from the application container code that Canvas can't turn off.

Detailed design

The Screenshot Mode Service is an entirely new plugin that has an API method that returns a Boolean. The return value tells the plugin whether or not it should render itself to optimize for non-interactivity.

The plugin is low-level as it has no dependencies of its own, so other low-level plugins can depend on it.

Interface

A plugin would depend on screenshotMode in kibana.json. That provides screenshotMode as a plugin object. The plugin's purpose is to know when the page is rendered for screenshot capture, and to interact with plugins through an API. It allows plugins to decides what to do with the screenshot mode information.

interface IScreenshotModeServiceSetup {
  isScreenshotMode: () => boolean;
}

The plugin knows the screenshot mode from request headers: this interface is constructed from a class that refers to information sent via a custom proprietary header:

interface HeaderData {
  'X-Screenshot-Mode': true
}

class ScreenshotModeServiceSetup implements IScreenshotModeServiceSetup {
  constructor(rawData: HeaderData) {}
  public isScreenshotMode (): boolean {}
}

The Reporting headless browser that opens the page can inject custom headers into the request. Teams should be able to test how their app renders when loaded with this header. They could use a web debugging proxy, or perhaps the new service should support a URL parameter which triggers screenshot mode to be enabled, for easier testing.

Basic example

When Kibana loads initially, there is a Newsfeed plugin in the UI that checks internally cached records to see if it must fetch the Elastic News Service for newer items. When the Screenshot Mode Service is implemented, the Newsfeed component has a source of information to check on whether or not it should load in the Kibana UI. If it can avoid loading, it avoids an unnecessary HTTP round trip, which weigh heavily on performance.

Alternatives

• Print media query CSS If applications UIs supported printability using @media print, and Kibana Reporting uses page.print() to capture the PDF, it would be easy for application developers to test, and prevent bugs showing up in the report.

  However, this proposal only provides high-level customization over visual rendering, which the application already has if it uses a customized URL for rendering the layout for screenshots. It has a performance downside, as well: the headless browser still has to render the entire page as a "normal" render before we can call page.print(). No one sees the results of that initial render, so it is the same amount of wasted rendering cycles during report generation that we have today.

Adoption strategy

Using this service doesn't mean that anything needs to be replaced or thrown away. It's an add on that any plugin or even application can use to add conditionals that previously weren't possible. The Reporting Services team should create an example in a developer example plugin on how to build a UI that is aware of Screenshot Mode Service. From there, the team would work on updating whichever code that would benefit from this the most, which we know from analyzing debugging logs of a report job. The team would work across teams to get it accepted by the owners.

How we teach this

The Reporting Services team will continue to analyze debug logs of reporting jobs to find if there is UI code running during a report job that could be optimized by this service. The team would reach out to the code owners and determine if it makes sense to use this service to improve screenshot performance of their code.

Further examples

• Applications can also use screenshot context to customize the way they load. An example is Toast Notifications: by default they auto-dismiss themselves after 30 seconds or so. That makes sense when there is a human there to notice the message, read it and remember it. But if the page is loaded for capturing a screenshot, the toast notifications should never disappear. The message in the toast needs to be part of the screenshot for its message to mean anything, so it should not force the screenshot capture tool to race against the toast timeout window.
• Avoid collection and sending of telemetry from the browser when page is loaded for screenshot capture.
• Turn off autocomplete features and auto-refresh features that weigh on performance for screenshot capture.