[DOCS][Reporting] Updates introduction and troubleshooting sections" (#54036) (#54069)

* [Reporting/Docs] Various Documentation Additions

- Add ECONNREFUSED to troubleshooting page:
- System Requirements for Reporting
- Layout and Sizing

* [DOCS][Reporting] Updates index and troubleshooting pages

Co-authored-by: Tim Sullivan <tsullivan@users.noreply.github.com>

Co-authored-by: Tim Sullivan <tsullivan@users.noreply.github.com>

docs/user/reporting/index.asciidoc

@@ -6,11 +6,11 @@
 
 --
 
-You can generate a report that contains a {kib} dashboard, visualization, 
-saved search, or Canvas workpad. Depending on the object type, you can export the data as 
+You can generate a report that contains a {kib} dashboard, visualization,
+saved search, or Canvas workpad. Depending on the object type, you can export the data as
 a PDF, PNG, or CSV document, which you can keep for yourself, or share with others.
 
-Reporting is available from the *Share* menu 
+Reporting is available from the *Share* menu
 in *Discover*, *Visualize*, *Dashboard*, and *Canvas*.
 
 [role="screenshot"]
@@ -40,9 +40,9 @@ for an example.
 [[manually-generate-reports]]
 == Generate a report manually
 
-. Open the dashboard, visualization, Canvas workpad, or saved search that you want to include in the report. 
+. Open the dashboard, visualization, Canvas workpad, or saved search that you want to include in the report.
 
-. In the {kib} toolbar, click *Share*.  If you are working in Canvas, 
+. In the {kib} toolbar, click *Share*.  If you are working in Canvas,
 click the share icon image:user/reporting/images/canvas-share-button.png["Canvas Share button"].
 
 . Select the option appropriate for your object. You can export:
@@ -55,14 +55,36 @@ click the share icon image:user/reporting/images/canvas-share-button.png["Canvas
 +
 A notification appears when the report is complete.
 
+[float]
+[[reporting-layout-sizing]]
+== Layout and sizing
+The layout and size of the PDF or PNG image depends on the {kib} app
+with which the Reporting plugin is integrated. For Canvas, the
+worksheet dimensions determine the size for Reporting. In other apps,
+the dimensions are taken on the fly by looking at
+the size of the visualization elements or panels on the page.
+
+The size dimensions are part of the reporting job parameters. Therefore, to
+make the report output larger or smaller, you can change the size of the browser.
+This resizes the shareable container before generating the
+report, so the desired dimensions are passed in the job parameters.
+
+In the following {kib} dashboard, the shareable container is highlighted.
+The shareable container is captured when you click the
+*Generate* or *Copy POST URL* button. It might take some trial and error
+before you're satisfied with the layout and dimensions in the resulting
+PNG or PDF image.
+
+[role="screenshot"]
+image::user/reporting/images/shareable-container.png["Shareable Container"]
+
+
+
 [float]
 [[optimize-pdf]]
 == Optimize PDF for print—dashboard only
 
-By default, {kib} creates a PDF  
-using the existing layout and size of the dashboard. To create a 
-printer-friendly PDF with multiple A4 portrait pages and two visualizations 
-per page, turn on *Optimize for printing*.
+To create a printer-friendly PDF with multiple A4 portrait pages and two visualizations per page, turn on *Optimize for printing*.
 
 [role="screenshot"]
 image::user/reporting/images/preserve-layout-switch.png["Share"]
@@ -72,8 +94,8 @@ image::user/reporting/images/preserve-layout-switch.png["Share"]
 [[manage-report-history]]
 == View and manage report history
 
-For a list of your reports, go to *Management > Reporting*.  
-From this view, you can monitor the generation of a report and 
+For a list of your reports, go to *Management > Reporting*.
+From this view, you can monitor the generation of a report and
 download reports that you previously generated.
 
 [float]

docs/user/reporting/reporting-troubleshooting.asciidoc

@@ -7,12 +7,20 @@
 
 Having trouble? Here are solutions to common problems you might encounter while using Reporting.
 
+* <<reporting-troubleshooting-system-dependencies>>
+* <<reporting-troubleshooting-text-incorrect>>
+* <<reporting-troubleshooting-missing-data>>
+* <<reporting-troubleshooting-file-permissions>>
+* <<reporting-troubleshooting-error-messages>>
+* <<reporting-troubleshooting-puppeteer-debug-logs>>
+* <<reporting-troubleshooting-system-requirements>>
+
 [float]
 [[reporting-troubleshooting-system-dependencies]]
 === System dependencies
 Reporting launches a "headless" web browser called Chromium on the Kibana server. It is a custom build made by Elastic of an open source
 project, and it is intended to have minimal dependencies on OS libraries. However, the Kibana server OS might still require additional
-dependencies for Chromium.
+dependencies to run the Chromium executable.
 
 Make sure Kibana server OS has the appropriate packages installed for the distribution.
 
@@ -33,19 +41,30 @@ If you are using Ubuntu/Debian systems, install the following packages:
 * `fonts-liberation`
 * `libfontconfig1`
 
+If the system is missing dependencies, then Reporting will fail in a non-deterministic way. {kib} runs a self-test at server startup, and
+if it encounters errors, logs them in the Console. Unfortunately, the error message does not include
+information about why Chromium failed to run. The most common error message is `Error: connect ECONNREFUSED`, which indicates
+that {kib} could not connect to the Chromium process.
+
+To troubleshoot the problem, start the {kib} server with environment variables that tell Chromium to print verbose logs. See the
+<<reporting-troubleshooting-puppeteer-debug-logs, Puppeteer debug method>> for more information.
+
 [float]
-=== Text is rendered incorrectly in generated reports
+[[reporting-troubleshooting-text-incorrect]]
+=== Text rendered incorrectly in generated reports
 
 If a report label is rendered as an empty rectangle, no system fonts are available. Install at least one font package on the system.
 
 If the report is missing certain Chinese, Japanese or Korean characters, ensure that a system font with those characters is installed.
 
 [float]
+[[reporting-troubleshooting-missing-data]]
 === Missing data in PDF report of data table visualization
 There is currently a known limitation with the Data Table visualization that only the first page of data rows, which are the only data
 visible on the screen, are shown in PDF reports.
 
 [float]
+[[reporting-troubleshooting-file-permissions]]
 === File permissions
 Ensure that the `headless_shell` binary located in your Kibana data directory is owned by the user who is running Kibana, that the
 user has the execute permission, and if applicable, that the filesystem is mounted with the `exec` option.
@@ -63,25 +82,25 @@ Whenever possible, a Reporting error message tries to be as self-explanatory as
 along with the solution.
 
 [float]
-==== "Max attempts reached"
+==== Max attempts reached
 There are two primary causes of this error:
 
-. You're creating a PDF of a visualization or dashboard that spans a large amount of data and Kibana is hitting the `xpack.reporting.queue.timeout`
+* You're creating a PDF of a visualization or dashboard that spans a large amount of data and Kibana is hitting the `xpack.reporting.queue.timeout`
 
-. Kibana is hosted behind a reverse-proxy, and the <<reporting-kibana-server-settings, Kibana server settings>> are not configured correctly
+* Kibana is hosted behind a reverse-proxy, and the <<reporting-kibana-server-settings, Kibana server settings>> are not configured correctly
 
 Create a Markdown visualization and then create a PDF report. If this succeeds, increase the `xpack.reporting.queue.timeout` setting. If the
 PDF report fails with "Max attempts reached," check your <<reporting-kibana-server-settings, Kibana server settings>>.
 
 [float]
 [[reporting-troubleshooting-nss-dependency]]
-==== "You must install nss for Reporting to work"
+==== You must install nss for Reporting to work
 Reporting using the Chromium browser relies on the Network Security Service libraries (NSS). Install the appropriate nss package for your
 distribution.
 
 [float]
 [[reporting-troubleshooting-sandbox-dependency]]
-==== "Unable to use Chromium sandbox"
+==== Unable to use Chromium sandbox
 Chromium uses sandboxing techniques that are built on top of operating system primitives. The Linux sandbox depends on user namespaces,
 which were introduced with the 3.8 Linux kernel. However, many distributions don't have user namespaces enabled by default, or they require
 the CAP_SYS_ADMIN capability.
@@ -90,6 +109,7 @@ Elastic recommends that you research the feasibility of enabling unprivileged us
 is if you are running Kibana in Docker because the container runs in a user namespace with the built-in seccomp/bpf filters.
 
 [float]
+[[reporting-troubleshooting-verbose-logs]]
 === Verbose logs
 {kib} server logs have a lot of useful information for troubleshooting and understanding how things work. If you're having any issues at
 all, the full logs from Reporting will be the first place to look. In `kibana.yml`:
@@ -101,10 +121,12 @@ logging.verbose: true
 
 For more information about logging, see <<logging-verbose,Kibana configuration settings>>.
 
+[float]
+[[reporting-troubleshooting-puppeteer-debug-logs]]
 === Puppeteer debug logs
 The Chromium browser that {kib} launches on the server is driven by a NodeJS library for Chromium called Puppeteer. The Puppeteer library
 has its own command-line method to generate its own debug logs, which can sometimes be helpful, particularly to figure out if a problem is
-caused by Kibana or Chromium. See more at https://github.com/GoogleChrome/puppeteer/blob/v1.19.0/README.md#debugging-tips
+caused by Kibana or Chromium. See more at https://github.com/GoogleChrome/puppeteer/blob/v1.19.0/README.md#debugging-tips[debugging tips].
 
 Using Puppeteer's debug method when launching Kibana would look like:
 ```
@@ -114,3 +136,14 @@ The internal DevTools protocol traffic will be logged via the `debug` module und
 
 
 The Puppeteer logs are very verbose and could possibly contain sensitive information. Handle the generated output with care.
+
+[float]
+[[reporting-troubleshooting-system-requirements]]
+=== System requirements
+In Elastic Cloud, the {kib} instances that most configurations provide by default is for 1GB of RAM for the instance. That is enough for
+{kib} Reporting when the visualization or dashboard is relatively simple, such as a single pie chart or a dashboard with
+a few visualizations. However, certain visualization types incur more load than others. For example, a TSVB panel has a lot of network
+requests to render.
+
+If the {kib} instance doesn't have enough memory to run the report, the report fails with an error such as `Error: Page crashed!`
+In this case, try increasing the memory for the {kib} instance to 2GB.