Reporting settings in Kibana
editReporting settings in Kibana
editYou can configure xpack.reporting
settings in your kibana.yml
to:
Enable reporting
editDisabling the reporting features is discouraged. If you need to turn off the ability to generate reports, configure the roles and spaces in the Kibana application privileges.
If needed, you can also prevent a Kibana instance from claiming reporting work by setting
xpack.reporting.queue.pollEnabled: false
.
Encryption key setting
editBy default, an encryption key is generated for the reporting features each time you start Kibana. If a static encryption key is not persisted in the Kibana configuration, any pending reports fail when you restart Kibana.
If you are load balancing across multiple Kibana instances, each instance needs to have the same reporting encryption key. Otherwise, report generation fails if a report is queued through one instance, and another instance picks up the job from the report queue. The instance that picks up the job is unable to decrypt the reporting job metadata.
-
xpack.reporting.encryptionKey
-
The static encryption key for reporting. Use an alphanumeric text string that is at least 32 characters. By default, Kibana generates a random key when it starts, which causes pending reports to fail after restart. Configure
xpack.reporting.encryptionKey
to preserve the same key across multiple restarts and multiple Kibana instances.
xpack.reporting.encryptionKey: "something_secret"
Background job settings
editReporting generates reports in the background and jobs are coordinated using documents in Elasticsearch. Depending on how often you generate reports and the overall number of reports, you might need to change the following settings.
-
xpack.reporting.capture.maxAttempts
-
If capturing a report fails for any reason, Kibana will re-queue the report job for retry, as many times as this setting. Defaults to
3
. -
xpack.reporting.queue.indexInterval
-
How often the index that stores reporting jobs rolls over to a new index. Valid values are
year
,month
,week
,day
, andhour
. Defaults toweek
. -
xpack.reporting.queue.pollEnabled
-
When
true
, enables the Kibana instance to poll Elasticsearch for pending jobs and claim them for execution. Whenfalse
, allows the Kibana instance to only add new jobs to the reporting queue, list jobs, and provide the downloads to completed reports through the UI. This requires a deployment where at least one other Kibana instance in the Elastic cluster has this setting totrue
. The default istrue
.
Running multiple instances of Kibana in a cluster for load balancing of
reporting requires identical values for xpack.reporting.encryptionKey
and, if
security is enabled, xpack.security.encryptionKey
.
-
xpack.reporting.queue.pollInterval
-
Specifies the time that the reporting poller waits between polling the index for any pending Reporting jobs. Can be specified as number of milliseconds. Defaults to
3s
. -
xpack.reporting.queue.timeout
-
How long each worker has to produce a report. If your machine is slow or under heavy load, you
might need to increase this timeout. If a Reporting job execution goes over this time limit, the job is marked
as a failure and no download will be available. Can be specified as number of milliseconds. Defaults to
4m
.
Capture settings
editReporting uses an internal "screenshotting" plugin to capture screenshots from Kibana. The following settings control the capturing process.
-
xpack.screenshotting.capture.timeouts.openUrl
-
Specify the time to allow the Reporting browser to wait for the "Loading…" screen to dismiss
and find the initial data for the page. If the time is exceeded, a screenshot is captured showing the current
page, and the download link shows a warning message. Can be specified as number of milliseconds. Defaults to
1m
. -
xpack.screenshotting.capture.timeouts.waitForElements
-
Specify the time to allow the Reporting browser to wait for all visualization panels to load on
the page. If the time is exceeded, a screenshot is captured showing the current page, and the download link
shows a warning message. Can be specified as number of milliseconds. Defaults to
1m
. -
xpack.screenshotting.capture.timeouts.renderComplete
-
Specify the time to allow the Reporting browser to wait for all visualizations to fetch and
render the data. If the time is exceeded, a screenshot is captured showing the current page, and the download
link shows a warning message. Can be specified as number of milliseconds. Defaults to
2m
.
If any timeouts from xpack.screenshotting.capture.timeouts.*
settings occur when
running a report job, Reporting will log the error and try to continue
capturing the page with a screenshot. As a result, a download will be
available, but there will likely be errors in the visualizations in the report.
-
xpack.screenshotting.capture.loadDelay
- [8.0.0] Deprecated in 8.0.0. This setting has no effect. Specify the amount of time before taking a screenshot when visualizations are not evented. All visualizations that ship with Kibana are evented, so this setting should not have much effect. If you are seeing empty images instead of visualizations, try increasing this value. NOTE: This setting exists for backwards compatibility, but is unused and therefore does not have an affect on reporting performance.
Chromium settings
editFor PDF and PNG reports, Reporting spawns a headless Chromium browser process on the server to load and capture a screenshot of the Kibana app. When installing Kibana on Linux and Windows platforms, the Chromium binary comes bundled with the Kibana download. For Mac platforms, the Chromium binary is downloaded the first time Kibana is started.
-
xpack.screenshotting.browser.chromium.disableSandbox
-
It is recommended that you research the feasibility of enabling unprivileged user namespaces. An exception is if you are running Kibana in Docker because the container runs in a user namespace with the built-in seccomp/bpf filters. For more information, refer to Chromium sandbox. Defaults to
false
for all operating systems except CentOS, Debian, and Red Hat Linux, which usetrue
. -
xpack.screenshotting.browser.chromium.proxy.enabled
-
Enables the proxy for Chromium to use. When set to
true
, you must also specify thexpack.screenshotting.browser.chromium.proxy.server
setting. Defaults tofalse
. -
xpack.screenshotting.browser.chromium.proxy.server
- The uri for the proxy server. Providing the username and password for the proxy server via the uri is not supported.
-
xpack.screenshotting.browser.chromium.proxy.bypass
- An array of hosts that should not go through the proxy server and should use a direct connection instead. Examples of valid entries are "elastic.co", "*.elastic.co", ".elastic.co", ".elastic.co:5601".
Network policy settings
editTo generate PDF reports, Reporting uses the Chromium browser to fully load the Kibana page on the server. This potentially involves sending requests to external hosts. For example, a request might go to an external image server to show a field formatted as an image, or to show an image in a Markdown visualization.
If the Chromium browser is asked to send a request that violates the network policy, Reporting stops processing the page before the request goes out, and the report is marked as a failure. Additional information about the event is in the Kibana server logs.
Kibana installations are not designed to be publicly accessible over the internet. The Reporting network policy and other capabilities of the Elastic Stack security features do not change this condition.
-
xpack.screenshotting.networkPolicy
- Capturing a screenshot from a Kibana page involves sending out requests for all the linked web assets. For example, a Markdown visualization can show an image from a remote server.
-
xpack.screenshotting.networkPolicy.enabled
-
When
false
, disables the Reporting network policy. Defaults totrue
. -
xpack.screenshotting.networkPolicy.rules
- A policy is specified as an array of objects that describe what to allow or deny based on a host or protocol. If a host or protocol is not specified, the rule matches any host or protocol.
The rule objects are evaluated sequentially from the beginning to the end of the array, and continue until there is a matching rule. If no rules allow a request, the request is denied.
# Only allow requests to placeholder.com xpack.screenshotting.networkPolicy: rules: [ { allow: true, host: "placeholder.com" } ]
# Only allow requests to https://placeholder.com xpack.screenshotting.networkPolicy: rules: [ { allow: true, host: "placeholder.com", protocol: "https:" } ]
A final allow
rule with no host or protocol allows all requests that are not explicitly denied:
# Denies requests from http://placeholder.com, but anything else is allowed. xpack.screenshotting.networkPolicy: rules: [{ allow: false, host: "placeholder.com", protocol: "http:" }, { allow: true }];
A network policy can be composed of multiple rules:
# Allow any request to http://placeholder.com but for any other host, https is required xpack.screenshotting.networkPolicy rules: [ { allow: true, host: "placeholder.com", protocol: "http:" }, { allow: true, protocol: "https:" }, ]
The file:
protocol is always denied, even if no network policy is configured.
CSV settings
edit-
xpack.reporting.csv.maxSizeBytes
-
The maximum byte size of a CSV file before being truncated. This setting exists to prevent large
exports from causing performance and storage issues. Can be specified as number of bytes. Defaults to
250mb
.
We recommend using CSV reports to export moderate amounts of data only. The feature enables analysis of data in
external tools, but it’s not intended for bulk export or to backup Elasticsearch data. If you need to export more than
250 MB of CSV, rather than increasing xpack.reporting.csv.maxSizeBytes
, please use filters to create multiple
smaller reports, or extract the data you need directly from Elasticsearch.
The following deployment configurations may lead to failed report jobs or incomplete reports:
- Any shard needed for search is unavailable.
- Data is stored on slow storage tiers.
- Network latency between nodes is high.
- Cross-cluster search is used.
To export large amounts of data we recommend using Elasticsearch APIs directly. See Point in time API, or SQL with CSV response data format.
-
xpack.reporting.csv.scroll.size
-
Number of documents retrieved from Elasticsearch for each scroll iteration during a CSV export. Defaults to
500
.
You may need to lower this setting if the default number of documents creates a strain on network resources.
-
xpack.reporting.csv.scroll.duration
-
Amount of time allowed before Kibana cleans the scroll context during a CSV export. Defaults to
30s
.
If search latency in Elasticsearch is sufficiently high, such as if you are using cross-cluster search, you may need to increase the setting.
-
xpack.reporting.csv.checkForFormulas
-
Enables a check that warns you when there’s a potential formula included in the output (=, -, +, and @ chars). See OWASP: https://www.owasp.org/index.php/CSV_Injection. Defaults to
true
. -
xpack.reporting.csv.escapeFormulaValues
-
Escape formula values in cells with a
'
. See OWASP: https://www.owasp.org/index.php/CSV_Injection. Defaults totrue
. -
xpack.reporting.csv.enablePanelActionDownload
- [7.9.0] Deprecated in 7.9.0. This setting has no effect. Enables CSV export from a saved search on a dashboard. This action is available in the dashboard panel menu for the saved search.
This setting exists for backwards compatibility, and is hardcoded to true
. CSV export from a saved search on a dashboard is enabled when Reporting is enabled.
-
xpack.reporting.csv.useByteOrderMarkEncoding
-
Adds a byte order mark (
\ufeff
) at the beginning of the CSV file. Defaults tofalse
.
Security settings
editWith Security enabled, Reporting has two forms of access control: each user can only access their own reports, and custom roles determine who has privilege to generate reports. When Reporting is configured with Kibana application privileges, you can control the spaces and applications where users are allowed to generate reports.
The xpack.reporting.roles
settings are for a deprecated system of access control in Reporting. Turning off this feature allows API Keys to generate reports, and allows reporting access through Kibana application privileges. We recommend you explicitly turn off reporting’s deprecated access control feature by adding xpack.reporting.roles.enabled: false
in kibana.yml. This will enable you to create custom roles that provide application privileges for reporting, as described in granting users access to reporting.
-
xpack.reporting.roles.enabled
-
[7.14.0]
Deprecated in 7.14.0. The default for this setting will be
false
in an upcoming version of Kibana. Sets access control to a set of assigned reporting roles, specified byxpack.reporting.roles.allow
. Defaults totrue
. -
xpack.reporting.roles.allow
-
[7.14.0]
Deprecated in 7.14.0.
In addition to superusers, specifies the roles that can generate reports using the Elasticsearch role management APIs. Requires
xpack.reporting.roles.enabled
to betrue
. Defaults to[ "reporting_user" ]
.
Kibana server settings
editTo generate screenshots for PNG and PDF reports, Reporting opens the Kibana web interface using a local connection on the server. In most cases, using a local connection to the Kibana server presents no issue. If you prefer the headless browser to connect to Kibana using a specific hostname, there are a number of settings that allow the headless browser to connect to Kibana through a proxy, rather than directly.
The xpack.reporting.kibanaServer
settings are optional. Take caution when editing these settings. Adding
these settings can cause the reporting features to fail. If report fail,
inspect the server logs. The full Kibana URL that Reporting is attempting to
open is logged during report execution.