[role="xpack"]
[[reporting-settings-kb]]
=== Reporting settings in {kib}
++++
<titleabbrev>Reporting settings</titleabbrev>
++++

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

* <<reporting-kibana-server-settings,Control how the {report-features} communicate with the {kib} server>>
* <<reporting-job-queue-settings,Manage background jobs>>
* <<reporting-capture-settings,Capture screenshots>>

[float]
[[general-reporting-settings]]
==== General reporting settings

[cols="2*<"]
|===
| [[xpack-enable-reporting]]`xpack.reporting.enabled` {ess-icon}
  | Set to `false` to disable the {report-features}.

| `xpack.reporting.encryptionKey` {ess-icon}
  | Set to an alphanumeric, at least 32 characters long text string. By default, {kib} will generate a random key when it
  starts, which will cause pending reports to fail after restart. Configure this
  setting to preserve the same key across multiple restarts and multiple instances of {kib}.

|===

[float]
[[reporting-kibana-server-settings]]
==== {kib} server settings

Reporting opens the {kib} web interface in a server process to generate
screenshots of {kib} visualizations. In most cases, the default settings
will work and you don't need to configure Reporting to communicate with {kib}.
However, if your client connections must go through a reverse-proxy
to access {kib}, Reporting configuration must have the proxy port, protocol,
and hostname set in the `xpack.reporting.kibanaServer.*` settings.

[NOTE]
====
If a reverse-proxy carries encrypted traffic from end-user
clients back to a {kib} server, the proxy port, protocol, and hostname
in Reporting settings must be valid for the encryption that the Reporting
browser will receive. Encrypted communications will 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 {kib} server has network access to the proxy.
====

[cols="2*<"]
|===
| `xpack.reporting.kibanaServer.port`
  | The port for accessing {kib}, if different from the `server.port` value.

| `xpack.reporting.kibanaServer.protocol`
  | The protocol for accessing {kib}, typically `http` or `https`.

| `xpack.reporting.kibanaServer.hostname`
  | The hostname for accessing {kib}, if different from the `server.host` value.

|===

[NOTE]
============
Reporting authenticates requests on the Kibana page only when the hostname matches the
`xpack.reporting.kibanaServer.hostname` setting. Therefore Reporting would fail 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"`.
============


[float]
[[reporting-job-queue-settings]]
==== Background job settings

Reporting generates reports in the background and jobs are coordinated using documents
in {es}. Depending on how often you generate reports and the overall number of
reports, you might need to change the following settings.

[cols="2*<"]
|===
| `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` {ess-icon}
  | Set to `true` (default) to enable the {kib} instance to to poll the index for
  pending jobs and claim them for execution. Setting this to `false` allows the
  {kib} instance to only add new jobs to the reporting queue, list jobs, and
  provide the downloads to completed report through the UI.

|===

[NOTE]
============
Running multiple instances of {kib} in a cluster for load balancing of
reporting requires identical values for `xpack.reporting.encryptionKey` and, if
security is enabled, `xpack.security.encryptionKey`.
============

[cols="2*<"]
|===
| `xpack.reporting.queue.pollInterval`
  | Specifies the number of milliseconds that the reporting poller waits between polling the
  index for any pending Reporting jobs. Defaults to `3000` (3 seconds).

| [[xpack-reporting-q-timeout]] `xpack.reporting.queue.timeout` {ess-icon}
  | 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. Specified in milliseconds.
  If a Reporting job execution time goes over this time limit, the job will be
  marked as a failure and there will not be a download available.
  Defaults to `120000` (two minutes).

|===

[float]
[[reporting-capture-settings]]
==== Capture settings

Reporting works by capturing screenshots from {kib}. The following settings
control the capturing process.

[cols="2*<"]
|===
a| `xpack.reporting.capture.timeouts`
`.openUrl` {ess-icon}
  | Specify how long to allow the Reporting browser to wait for the "Loading..." screen
  to dismiss and find the initial data for the Kibana page.  If the time is
  exceeded, a page screenshot is captured showing the current state, and the download link shows a warning message.
  Defaults to `60000` (1 minute).

a| `xpack.reporting.capture.timeouts`
`.waitForElements` {ess-icon}
  | Specify how long to allow the Reporting browser to wait for all visualization
  panels to load on the Kibana page. If the time is exceeded, a page screenshot
  is captured showing the current state, and the download link shows a warning message. Defaults to `30000` (30
  seconds).

a| `xpack.reporting.capture.timeouts`
`.renderComplete` {ess-icon}
  | Specify how long to allow the Reporting browser to wait for all visualizations to
  fetch and render the data. If the time is exceeded, a
  page screenshot is captured showing the current state, and the download link shows a warning message. Defaults to
  `30000` (30 seconds).

|===

[NOTE]
============
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.
============

[cols="2*<"]
|===
| `xpack.reporting.capture.maxAttempts` {ess-icon}
  | If capturing a report fails for any reason, {kib} will re-attempt other reporting
  job, as many times as this setting. Defaults to `3`.

| `xpack.reporting.capture.loadDelay`
  | When visualizations are not evented, this is the amount of time before
  taking a screenshot. All visualizations that ship with {kib} 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 `3000` (3 seconds).

| [[xpack-reporting-browser]] `xpack.reporting.capture.browser.type` {ess-icon}
  | Specifies the browser to use to capture screenshots. This setting exists for
  backward compatibility. The only valid option is `chromium`.

|===

[float]
[[reporting-chromium-settings]]
==== Chromium settings

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

[cols="2*<"]
|===
a| `xpack.reporting.capture.browser`
`.chromium.disableSandbox`
  | It is recommended that you research the feasibility of enabling unprivileged user namespaces.
  See Chromium Sandbox for additional information. Defaults to false for all operating systems except Debian,
  Red Hat Linux, and CentOS which use true.

a| `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`.

a| `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.

a| `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".

|===

[float]
[[reporting-csv-settings]]
==== CSV settings

[cols="2*<"]
|===
| [[xpack-reporting-csv]] `xpack.reporting.csv.maxSizeBytes` {ess-icon}
  | The maximum size of a CSV file before being truncated. This setting exists to prevent
  large exports from causing performance and storage issues.
  Defaults to `10485760` (10mB).

| `xpack.reporting.csv.scroll.size`
  | Number of documents retrieved from {es} for each scroll iteration during a CSV
  export.
  Defaults to `500`.

| `xpack.reporting.csv.scroll.duration`
  | Amount of time allowed before {kib} 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.
  Defaults to `true`.

|===

[float]
[[reporting-advanced-settings]]
==== Advanced settings

[cols="2*<"]
|===
| `xpack.reporting.index`
  | Reporting uses a weekly index in {es} to store the reporting job and
  the report content. The index is automatically created if it does not already
  exist. Configure this to a unique value, beginning with `.reporting-`, for every
  {kib} instance that has a unique `kibana.index` setting. Defaults to `.reporting`.

| `xpack.reporting.roles.allow`
  | Specifies the roles in addition to superusers that can use reporting.
  Defaults to `[ "reporting_user" ]`. +

|===

[NOTE]
============
Each user has access to only their own reports.
============