mirror of
https://github.com/elastic/kibana.git
synced 2025-04-23 09:19:04 -04:00
* [DOCS] Updates to Reporting docs (#46158) * [DOCS] Updated to Reporting docs * Updated with review comments * Removed float tag
This commit is contained in:
Kaarina Tungseth
GitHub
parent
c3c2efbd42
commit
0a521742e1
12 changed files with 103 additions and 111 deletions
|
|
@ -1,54 +1,54 @@
|
|||
[role="xpack"]
|
||||
[[automating-report-generation]]
|
||||
== Automating Report Generation
|
||||
== Automating report generation
|
||||
You can automatically generate reports with {watcher}, or by submitting
|
||||
HTTP `POST` requests from a script.
|
||||
|
||||
include::report-intervals.asciidoc[]
|
||||
|
||||
[float]
|
||||
=== Getting the POST URL
|
||||
=== Get the POST URL
|
||||
|
||||
Generating a report either through Watcher or a script requires capturing the **POST
|
||||
Generating a report either through {watcher} or a script requires capturing the **POST
|
||||
URL**, which is the URL to queue a report for generation.
|
||||
|
||||
To get the URL for triggering PDF report generation during a given time period:
|
||||
|
||||
. Load the saved object in the Visualize editor, or load a Dashboard.
|
||||
. Use the timepicker to specify a relative or absolute time period.
|
||||
. Click *Share* in the Kibana toolbar.
|
||||
. To specify a relative or absolute time period, use the time filter.
|
||||
. In the {kib} toolbar, click *Share*.
|
||||
. Select *PDF Reports*.
|
||||
. Click **Copy POST URL**.
|
||||
|
||||
To get the URL for triggering CSV report generation during a given time period:
|
||||
|
||||
. Load a saved search in Discover.
|
||||
. Use the timepicker to specify a relative or absolute time period.
|
||||
. Click *Share* in the Kibana toolbar.
|
||||
. Load the saved search in Discover.
|
||||
. To specify a relative or absolute time period, use the time filter.
|
||||
. In the {kib} toolbar, click *Share*.
|
||||
. Select *CSV Reports*.
|
||||
. Click **Copy POST URL**.
|
||||
|
||||
[float]
|
||||
=== Using Watcher
|
||||
=== Use Watcher
|
||||
|
||||
include::watch-example.asciidoc[]
|
||||
|
||||
[float]
|
||||
=== Using a Script
|
||||
=== Use a script
|
||||
|
||||
include::script-example.asciidoc[]
|
||||
|
||||
[float]
|
||||
=== HTTP Response Codes
|
||||
=== HTTP response codes
|
||||
|
||||
include::response-codes.asciidoc[]
|
||||
|
||||
[float]
|
||||
== Deprecated Report URLs
|
||||
== Deprecated report URLs
|
||||
|
||||
The following POST URL paths were once supported but are now deprecated. If there are
|
||||
any problems with using these paths after upgrading Kibana's version, you should use
|
||||
{kib} to re-generate the POST URL for a particular report.
|
||||
any problems with using these paths after upgrading {kib}, use
|
||||
{kib} to regenerate the POST URL for a particular report.
|
||||
|
||||
* Dashboard Reports: `/api/reporting/generate/dashboard/<dashboard-id>`
|
||||
* Visualization Reports: `/api/reporting/generate/visualization/<visualization-id>`
|
||||
|
|
|
|||
|
|
@ -1,13 +1,13 @@
|
|||
[role="xpack"]
|
||||
[[reporting-chromium-sandbox]]
|
||||
=== Chromium Sandbox
|
||||
=== Chromium sandbox
|
||||
|
||||
When {reporting} uses the Chromium browser for generating PDF reports, it's recommended to use the sandbox for
|
||||
an additional layer of security. The Chromium sandbox uses operating system provided mechanisms to ensure that
|
||||
code execution cannot make persistent changes to the computer or access confidential information. The specific
|
||||
sandboxing techniques differ for each operating system.
|
||||
|
||||
==== Linux Sandbox
|
||||
==== Linux sandbox
|
||||
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. {reporting}
|
||||
will automatically disable the sandbox when it is running on Debian and CentOS as additional steps are required to enable
|
||||
|
|
@ -19,6 +19,6 @@ recommended to enable usernamespaces and set `xpack.reporting.capture.browser.ch
|
|||
`kibana.yml` to enable the sandbox.
|
||||
|
||||
==== Docker
|
||||
When running Kibana in a Docker container, all container processes are run within a usernamespace with seccomp-bpf and
|
||||
When running {kib} in a Docker container, all container processes are run within a usernamespace with seccomp-bpf and
|
||||
AppArmor profiles that prevent the Chromium sandbox from being used. In these situations, disabling the sandbox is recommended,
|
||||
as the container implements similar security mechanisms.
|
||||
|
|
@ -1,19 +1,20 @@
|
|||
[role="xpack"]
|
||||
[[configuring-reporting]]
|
||||
== Configuring Reporting
|
||||
== Reporting configuration
|
||||
|
||||
You can configure settings in `kibana.yml` to control how {reporting}
|
||||
communicates with the Kibana server, manages background jobs, and captures
|
||||
communicates with the {kib} server, manages background jobs, and captures
|
||||
screenshots. See <<reporting-settings-kb, Reporting Settings>> for the complete
|
||||
list of settings.
|
||||
|
||||
=== Encryption Keys for Multiple Kibana Instances
|
||||
[float]
|
||||
=== Encryption keys for multiple {kib} instances
|
||||
|
||||
By default, a new encryption key is generated for {reporting} each time
|
||||
you start Kibana. This means if a static encryption key is not persisted in the
|
||||
Kibana configuration, any pending reports will fail when you restart Kibana.
|
||||
you start {kib}. This means if a static encryption key is not persisted in the
|
||||
{kib} configuration, any pending reports will fail when you restart {kib}.
|
||||
|
||||
If you are load balancing across multiple Kibana instances, they need to have
|
||||
If you are load balancing across multiple {kib} instances, they need to have
|
||||
the same reporting encryption key. Otherwise, report generation will fail if a
|
||||
report is queued through one instance and another instance picks up the job
|
||||
from the report queue. The other instance will not be able to decrypt the
|
||||
|
|
@ -28,9 +29,10 @@ configuration file. You can use any text string as the encryption key.
|
|||
xpack.reporting.encryptionKey: "something_secret"
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
=== Reporting Indices for Multiple Kibana Workspaces
|
||||
[float]
|
||||
=== Report indices for multiple {kib} workspaces
|
||||
|
||||
If you divide workspaces in an Elastic cluster using multiple Kibana instances
|
||||
If you divide workspaces in an Elastic cluster using multiple {kib} instances
|
||||
with a different `kibana.index` setting per instance, you must set a unique `xpack.reporting.index`
|
||||
setting per `kibana.index`. Otherwise, report generation will periodically fail
|
||||
if a report is queued through an instance with one `kibana.index` setting, and
|
||||
|
|
@ -56,9 +58,10 @@ NOTE: If security is enabled, the `xpack.reporting.index` setting should begin
|
|||
with `.reporting-` in order for the `kibana_system` role to have the necessary
|
||||
privileges over the index.
|
||||
|
||||
=== Using Reverse Proxies
|
||||
[float]
|
||||
=== Use reverse proxies
|
||||
|
||||
If your Kibana instance requires a reverse-proxy (NGINX, Apache, etc.) for
|
||||
If your {kib} instance requires a reverse proxy (NGINX, Apache, etc.) for
|
||||
access, because of rewrite rules or special headers being added by the proxy,
|
||||
then you need to configure the `xpack.reporting.kibanaServer` settings to make
|
||||
the headless browser process connect to the proxy in <<reporting-kibana-server-settings, Kibana server settings>>.
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
=== CSV
|
||||
|
||||
[float]
|
||||
==== Job Parameters
|
||||
==== Job parameters
|
||||
If integrating with Reporting via a custom UI, the following job parameters must be Rison encoded and posted to
|
||||
the aforementioned generate job url:
|
||||
|
||||
|
|
|
|||
|
|
@ -1,25 +1,25 @@
|
|||
[role="xpack"]
|
||||
[[reporting-integration]]
|
||||
== Reporting Integration
|
||||
Integrating a Kibana application with {reporting} requires a minimum amount of code, and the goal is to not have to
|
||||
== Reporting integration
|
||||
Integrating a {kib} application with {reporting} requires a minimum amount of code, and the goal is to not have to
|
||||
modify the Reporting code as we add additional applications. Instead, applications abide by a contract that Reporting
|
||||
uses to determine the information that is required to export CSVs and PDFs.
|
||||
|
||||
[IMPORTANT]
|
||||
==============================================
|
||||
These pages document internal APIs and are not guaranteed to be supported across future versions of Kibana.
|
||||
However, these docs will be kept up-to-date to reflect the current implementation of Reporting integration in Kibana.
|
||||
These pages document internal APIs and are not guaranteed to be supported across future versions of {kib}.
|
||||
However, these docs will be kept up-to-date to reflect the current implementation of Reporting integration in {kib}.
|
||||
==============================================
|
||||
|
||||
[float]
|
||||
[[reporting-nav-bar-extensions]]
|
||||
=== Share Menu Extensions
|
||||
=== Share menu extensions
|
||||
X-Pack uses the `ShareContextMenuExtensionsRegistryProvider` to register actions in the share menu.
|
||||
|
||||
This integration will likely be changing in the near future as we move towards a unified actions abstraction across {kib}.
|
||||
|
||||
[float]
|
||||
=== Generate Job URL
|
||||
=== Generate job URL
|
||||
To generate a new {reporting} job, different export types require different `jobParams` that are Rison encoded into a URL
|
||||
that abide by the following convention: `/api/reporting/generate?jobParams=${rison.encode(jobParams)}`. If you use the
|
||||
aforementioned <<reporting-nav-bar-extensions, nav bar extensions>> then this detail will be abstracted away, but if you
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
=== PDF
|
||||
|
||||
[float]
|
||||
==== Job Parameters
|
||||
==== Job parameters
|
||||
If integrating with Reporting via a custom UI, the following job parameters must be Rison encoded and posted to
|
||||
the aforementioned generate job url:
|
||||
|
||||
|
|
@ -27,7 +27,7 @@ interface jobParameters {
|
|||
`jobParameters.layout.dimensions` is only currently used by "preserve_layout"
|
||||
|
||||
[float]
|
||||
==== `export-config` Directive
|
||||
==== `export-config` directive
|
||||
If integrating with Reporting via the `export-config` directive, the AngularJS controller that contains
|
||||
the directive should expose the following methods and the `export-config` directive will POST them to the
|
||||
reporting API:
|
||||
|
|
|
|||
1
docs/user/reporting/generating-reports.asciidoc
Normal file
1
docs/user/reporting/generating-reports.asciidoc
Normal file
|
|
@ -0,0 +1 @@
|
|||
[role="xpack"]
|
||||
|
|
@ -1,52 +0,0 @@
|
|||
[role="xpack"]
|
||||
[[reporting-getting-started]]
|
||||
== Getting Started
|
||||
|
||||
[float]
|
||||
=== System Setup
|
||||
|
||||
{reporting} is automatically enabled in {kib}. The first time Kibana runs, it extracts a custom build for the Chromium web browser, which
|
||||
runs on the server in headless mode to load Kibana and capture the rendered Kibana charts as images.
|
||||
|
||||
Chromium is an open-source project not related to Elastic, but the Chromium binary for Kibana has been custom-built by Elastic to ensure it
|
||||
works with minimal setup. However, the Kibana server OS might still require additional dependencies for Chromium. See the
|
||||
<<reporting-troubleshooting-system-dependencies, Reporting Troubleshooting>> section for more information about the system dependencies
|
||||
for different operating systems.
|
||||
|
||||
[float]
|
||||
=== Generating a Report Manually
|
||||
|
||||
. Open {kib} in your web browser and log in. If you are running {kib}
|
||||
locally, go to `http://localhost:5601`. To access {kib} and generate
|
||||
reports, you need the `kibana_user` and `reporting_user` roles. For more
|
||||
information, see <<secure-reporting>>.
|
||||
|
||||
. Open the dashboard, visualization, or saved search you want to include
|
||||
in the report.
|
||||
|
||||
. Click *Share* in the {kib} toolbar:
|
||||
+
|
||||
--
|
||||
[role="screenshot"]
|
||||
image:user/reporting/images/share-button.png["Reporting Button",link="share-button.png"]
|
||||
--
|
||||
|
||||
. Depending on the {kib} application, choose the appropriate options:
|
||||
|
||||
.. If you're on Discover:
|
||||
... Select *CSV Reports*
|
||||
|
||||
... Click the *Generate CSV* button.
|
||||
|
||||
.. If you're on Visualize or Dashboard:
|
||||
... Select *PDF Reports*
|
||||
|
||||
... Dashboard only: Choose to enable *Optimize for printing* layout mode. For an explanation of the different layout modes, see <<pdf-layout-modes, PDF Layout Modes>>.
|
||||
|
||||
... Click the *Generate PDF* button.
|
||||
|
||||
[float]
|
||||
=== Generating a Report Automatically
|
||||
|
||||
If you want to automatically generate reports from a script or with
|
||||
{watcher}, see <<automating-report-generation, Automating Report Generation>>
|
||||
|
|
@ -3,7 +3,9 @@
|
|||
= Reporting from Kibana
|
||||
|
||||
[partintro]
|
||||
|
||||
--
|
||||
|
||||
You can generate reports that contain {kib} dashboards,
|
||||
visualizations, and saved searches. Dashboards and visualizations are
|
||||
exported as PDF documents, while saved searches in Discover
|
||||
|
|
@ -14,13 +16,53 @@ Reporting is located in the share menu from the {kib} toolbar:
|
|||
[role="screenshot"]
|
||||
image::user/reporting/images/share-button.png["Share"]
|
||||
|
||||
You can also <<automating-report-generation, generate reports automatically>>.
|
||||
[float]
|
||||
== System setup
|
||||
|
||||
{reporting} is automatically enabled in {kib}. The first time {kib} runs, it extracts a custom build for the Chromium web browser, which
|
||||
runs on the server in headless mode to load {kib} and capture the rendered {kib} charts as images.
|
||||
|
||||
Chromium is an open-source project not related to Elastic, but the Chromium binary for {kib} has been custom-built by Elastic to ensure it
|
||||
works with minimal setup. However, the {kib} server OS might still require additional dependencies for Chromium. See the
|
||||
<<reporting-troubleshooting-system-dependencies, Reporting Troubleshooting>> section for more information about the system dependencies
|
||||
for different operating systems.
|
||||
|
||||
[float]
|
||||
== Manually generate reports
|
||||
|
||||
. Open {kib} in your web browser and log in. If you are running {kib}
|
||||
locally, go to `http://localhost:5601`. To access {kib} and generate
|
||||
reports, you need the `kibana_user` and `reporting_user` roles. For more
|
||||
information, see <<secure-reporting>>.
|
||||
|
||||
. Open the dashboard, visualization, or saved search you want to include
|
||||
in the report.
|
||||
|
||||
. Click *Share* in the {kib} toolbar:
|
||||
+
|
||||
[role="screenshot"]
|
||||
image:user/reporting/images/share-button.png["Reporting Button",link="share-button.png"]
|
||||
|
||||
. Depending on the {kib} application, choose the appropriate options:
|
||||
|
||||
. If you're on Discover, select *CSV Reports*, then click *Generate CSV*.
|
||||
|
||||
. If you're on Visualize or Dashboard:
|
||||
|
||||
.. Select *PDF Reports*
|
||||
|
||||
.. Dashboard only: Choose to enable *Optimize for printing* layout mode. For an explanation of the different layout modes, see <<pdf-layout-modes, PDF Layout Modes>>.
|
||||
|
||||
.. Click *Generate PDF*.
|
||||
|
||||
[float]
|
||||
== Automatically generate reports
|
||||
|
||||
If you want to automatically generate reports from a script or with
|
||||
{watcher}, see <<automating-report-generation, Automating Report Generation>>
|
||||
|
||||
To use {reporting} in a production environment, <<securing-reporting, secure
|
||||
the Reporting endpoints>>.
|
||||
--
|
||||
|
||||
include::getting-started.asciidoc[]
|
||||
include::automating-report-generation.asciidoc[]
|
||||
include::pdf-layout-modes.asciidoc[]
|
||||
include::configuring-reporting.asciidoc[]
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
[[pdf-layout-modes]]
|
||||
== PDF Layout Modes
|
||||
== PDF layout modes
|
||||
|
||||
When creating a PDF report of a dashboard, there are two layout modes: *Optimize PDF for printing* and *Preserve existing layout in PDF*
|
||||
When you create a PDF report of a dashboard, you can use the *Optimize PDF for printing* or *Preserve existing layout in PDF* modes.
|
||||
|
||||
--
|
||||
[role="screenshot"]
|
||||
|
|
@ -11,7 +11,7 @@ image:user/reporting/images/preserve-layout-switch.png["PDF Reporting",link="pre
|
|||
[float]
|
||||
[[optimize-pdf-for-printing]]
|
||||
=== Optimize PDF for printing
|
||||
This will create a print friendly PDF with multiple A4 portrait pages, with 2 visualizations per page. This is the layout mode that was always used prior to Kibana 6.1, and will create PDFs similar to the following:
|
||||
Create a print friendly PDF with multiple A4 portrait pages and two visualizations per page.
|
||||
|
||||
--
|
||||
[role="screenshot"]
|
||||
|
|
@ -21,11 +21,11 @@ image:user/reporting/images/print-layout.png["optimize-pdf-for-printing",link="p
|
|||
[float]
|
||||
[[preserve-existing-layout-in-pdf]]
|
||||
=== Preserve existing layout in PDF
|
||||
This will create a PDF preserving the existing layout and size of the Visualization or Dashboard, and will create PDFs similar to the following:
|
||||
Create a PDF with the existing layout and size of the Visualization or Dashboard.
|
||||
|
||||
--
|
||||
[role="screenshot"]
|
||||
image:user/reporting/images/preserve-layout.png["Preserve existing layout in PDF",link="preserve-layout.png"]
|
||||
--
|
||||
|
||||
When creating a PNG or a PDF report of a visualization, the "Optimize for printing" option will automatically be used.
|
||||
When you create a PNG or a PDF report of a visualization, the *Optimize for printing* option is used.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
[role="xpack"]
|
||||
[[reporting-troubleshooting]]
|
||||
== Reporting Troubleshooting
|
||||
== Reporting troubleshooting
|
||||
++++
|
||||
<titleabbrev>Troubleshooting</titleabbrev>
|
||||
++++
|
||||
|
|
@ -8,8 +8,8 @@
|
|||
Having trouble? Here are solutions to common problems you might encounter while using Reporting.
|
||||
|
||||
[float]
|
||||
=== Verbose Logging
|
||||
Kibana's server logs have a lot of useful information for troubleshooting and understanding how things work. If you're having any issues at
|
||||
=== 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`:
|
||||
|
||||
[source,yaml]
|
||||
|
|
@ -21,15 +21,14 @@ For more information about logging, see <<logging-verbose,Kibana configuration s
|
|||
|
||||
[float]
|
||||
[[reporting-troubleshooting-system-dependencies]]
|
||||
=== 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.
|
||||
|
||||
Make sure Kibana server OS has the appropriate packages installed for the distribution.
|
||||
|
||||
[float]
|
||||
==== On CentOS/RHEL systems, the following packages should be installed:
|
||||
If you are using CentOS/RHEL systems, install the following packages:
|
||||
* `ipa-gothic-fonts`
|
||||
* `xorg-x11-fonts-100dpi`
|
||||
* `xorg-x11-fonts-75dpi`
|
||||
|
|
@ -40,25 +39,24 @@ Make sure Kibana server OS has the appropriate packages installed for the distri
|
|||
* `fontconfig`
|
||||
* `freetype`
|
||||
|
||||
[float]
|
||||
==== On Ubuntu/Debian systems, the following packages should be installed:
|
||||
If you are using Ubuntu/Debian systems, install the following packages:
|
||||
* `fonts-liberation`
|
||||
* `libfontconfig1`
|
||||
|
||||
[float]
|
||||
=== Text is Not rendered correctly in generated reports
|
||||
=== Text is 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]
|
||||
=== Data Table Visualization does not show all data in PDF reports
|
||||
=== 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]
|
||||
=== 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.
|
||||
|
||||
|
|
@ -70,7 +68,7 @@ the first time Kibana starts when verbose logging is enabled.
|
|||
|
||||
[float]
|
||||
[[reporting-troubleshooting-error-messages]]
|
||||
=== Error Messages
|
||||
=== Error messages
|
||||
Whenever possible, a Reporting error message tries to be as self-explanatory as possible. Here are some error messages you might encounter,
|
||||
along with the solution.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
[role="xpack"]
|
||||
[[secure-reporting]]
|
||||
=== Reporting and Security
|
||||
=== Reporting and security
|
||||
|
||||
Reporting operates by creating and updating documents in {es} in response to
|
||||
user actions in {kib}.
|
||||
|
|
@ -48,7 +48,7 @@ reporting_user:
|
|||
|
||||
[role="xpack"]
|
||||
[[securing-reporting]]
|
||||
=== Securing the Reporting Endpoints
|
||||
=== Secure the reporting endpoints
|
||||
|
||||
In a production environment, you should restrict access to
|
||||
the {reporting} endpoints to authorized users. This requires that you:
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue