Reporting settings in Kibana

edit

Reporting settings in Kibana

edit

You can configure xpack.reporting settings in your kibana.yml to:

Enable reporting

edit
xpack.reporting.enabled logo cloud
When true, enables the reporting features. The reporting features are automatically enabled in Kibana. The default is true.

Encryption key setting

edit

By 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 logo cloud
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"

Reporting index setting

edit
xpack.reporting.index
[7.11.0] Deprecated in 7.11.0. This setting will be removed in 8.0.0. Multitenancy by changing kibana.index is unsupported starting in 8.0.0. For more details, refer to 8.0 Breaking Changes. When you divide workspaces in an Elastic cluster using multiple Kibana instances with a different kibana.index setting per instance, you must set a unique xpack.reporting.index setting per kibana.index. Otherwise, report generation periodically fails if a report is queued through an instance with one kibana.index setting, and an instance with a different kibana.index attempts to claim the job. Reporting uses a weekly index in Elasticsearch to store the reporting job and the report content. The index is automatically created if it does not already exist. Configure a unique value for xpack.reporting.index, beginning with .reporting-, for every Kibana instance that has a unique kibana.index setting. Defaults to .reporting.

Kibana instance A:

kibana.index: ".kibana-a"
xpack.reporting.index: ".reporting-a"
xpack.reporting.encryptionKey: "something_secret"

Kibana instance B:

kibana.index: ".kibana-b"
xpack.reporting.index: ".reporting-b"
xpack.reporting.encryptionKey: "something_secret"

If security is enabled, the xpack.reporting.index setting should begin with .reporting- for the kibana_system role to have the necessary privileges over the index.

Kibana server settings

edit

Reporting opens the Kibana web interface in a server process to generate screenshots of Kibana visualizations. In most cases, the default settings work and you don’t need to configure the reporting features to communicate with Kibana.

If your Kibana instance requires a reverse proxy (such as NGINX, Apache, etc.) for access, because of rewrite rules or special headers being added by the proxy, you must configure the xpack.reporting.kibanaServer settings to make the headless browser process connect to the proxy.

If a reverse proxy carries encrypted traffic from user clients back to a Kibana server, the proxy port, protocol, and hostname in xpack.reporting.kibanaServer must be valid for the encryption that the Reporting browser receives. Encrypted communications fail if there are mismatches in the host information between the request and the certificate on the server.

Configuring the xpack.reporting.kibanaServer settings to point to a proxy host requires that the Kibana server has network access to the proxy.

xpack.reporting.kibanaServer.port
The port for accessing Kibana, if different from the server.port value.
xpack.reporting.kibanaServer.protocol
The protocol for accessing Kibana, typically http or https.
xpack.reporting.kibanaServer.hostname
The hostname for accessing Kibana, if different from the server.host value.

Reporting authenticates requests on the Kibana page only when the hostname matches the xpack.reporting.kibanaServer.hostname setting. Therefore Reporting fails if the set value redirects to another server. For that reason, "0" is an invalid setting because, in the Reporting browser, it becomes an automatic redirect to "0.0.0.0".

Background job settings

edit

Reporting 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.queue.indexInterval
How often the index that stores reporting jobs rolls over to a new index. Valid values are year, month, week, day, and hour. Defaults to week.
xpack.reporting.queue.pollEnabled logo cloud
Set to true (default) to enable the Kibana instance to poll the index for pending jobs and claim them for execution. Setting this to false allows the Kibana instance to only add new jobs to the reporting queue, list jobs, and provide the downloads to completed report through the UI.

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 logo cloud
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 2m.

Capture settings

edit

Reporting works by capturing screenshots from Kibana. The following settings control the capturing process.

xpack.reporting.capture.timeouts.openUrl logo cloud
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.reporting.capture.timeouts.waitForElements logo cloud
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 30s.
xpack.reporting.capture.timeouts.renderComplete logo cloud
Specify the timeto 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 30s.

If any timeouts from xpack.reporting.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.reporting.capture.maxAttempts logo cloud
If capturing a report fails for any reason, Kibana will re-attempt other reporting job, as many times as this setting. Defaults to 3.
xpack.reporting.capture.loadDelay
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. Defaults to 3s.
xpack.reporting.capture.browser.type logo cloud
Specifies the browser to use to capture screenshots. This setting exists for backward compatibility. The only valid option is chromium.

Chromium settings

edit

When xpack.reporting.capture.browser.type is set to chromium (default) you can also specify the following settings.

xpack.reporting.capture.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 Debian, Red Hat Linux, and CentOS, which use true.
xpack.reporting.capture.browser.chromium.proxy.enabled
Enables the proxy for Chromium to use. When set to true, you must also specify the xpack.reporting.capture.browser.chromium.proxy.server setting. Defaults to false.
xpack.reporting.capture.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.reporting.capture.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

edit

To 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.reporting.capture.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.reporting.capture.networkPolicy.enabled
When false, disables the Reporting network policy. Defaults to true.
xpack.reporting.capture.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.reporting.capture.networkPolicy:
  rules: [ { allow: true, host: "placeholder.com" } ]
# Only allow requests to https://placeholder.com
xpack.reporting.capture.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.reporting.capture.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.reporting.capture.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 logo cloud
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 10mb.

Setting xpack.reporting.csv.maxSizeBytes much larger than the default 10 MB limit has the potential to negatively affect the performance of Kibana and your Elasticsearch cluster. There is no enforced maximum for this setting, but a reasonable maximum value depends on multiple factors:

  • The http.max_content_length setting in Elasticsearch.
  • Network proxies, which are often configured by default to block large requests with a 413 error.
  • The amount of memory available to the Kibana server, which limits the size of CSV data that must be held temporarily.

For information about Kibana memory limits, see using Kibana in a production environment.

xpack.reporting.csv.scroll.size
Number of documents retrieved from Elasticsearch for each scroll iteration during a CSV export. Defaults to 500.
xpack.reporting.csv.scroll.duration
Amount of time allowed before Kibana cleans the scroll context during a CSV export. Defaults to 30s.
xpack.reporting.csv.checkForFormulas
Enables a check that warns you when there’s a potential formula involved in the output (=, -, +, and @ chars). See OWASP: https://www.owasp.org/index.php/CSV_Injection. Defaults to true.
xpack.reporting.csv .enablePanelActionDownload
Enables CSV export from a saved search on a dashboard. This action is available in the dashboard panel menu for the saved search. NOTE: This setting exists for backwards compatibility, but is unused and hardcoded to true. CSV export from a saved search on a dashboard is enabled when Reporting is enabled.

Security settings

edit

With 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. It does not allow API Keys to generate reports, and it doesn’t allow 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 by xpack.reporting.roles.allow. Defaults to true.
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 be true. Defaults to [ "reporting_user" ].