IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

› ›

Automating report generation

edit

Automating report generation

edit

Automatically generate PDF and CSV reports by submitting HTTP POST requests using Watcher or a script.

The interval between report requests must be longer than the time it takes to generate the reports—otherwise, the report queue can back up. To avoid this, increase the time between report requests.

By default, report generation times out if the report cannot be generated within two minutes. If you are generating reports that contain many complex visualizations or your machine is slow or under constant heavy load, it might take longer than two minutes to generate a report. You can increase the timeout by setting xpack.reporting.queue.timeout in kibana.yml.

Create a POST URL

edit

Create the POST URL that triggers a report to generate PDF and CSV reports.

To create the POST URL for PDF reports:

Open the dashboard, visualization, or Canvas workpad.
From the Kibana toolbar, click Share, then select PDF Reports.
If you are using Canvas, click Advanced options.
Click Copy POST URL.

To create the POST URL for CSV reports:

In Discover, open the saved search.
From the Kibana toolbar, click Share, then select CSV Reports.
Click Copy POST URL.

Use Watcher

edit

To automatically generate reports with a watch, you need to configure Watcher to trust the Kibana server’s certificate. For more information, see Securing Reporting.

To configure a watch to email reports, you use the reporting attachment type in an email action. For more information, see Configuring email accounts.

For example, the following watch generates a PDF report and emails the report every hour:

PUT _watcher/watch/error_report
{
  "trigger" : {
    "schedule": {
      "interval": "1h"
    }
  },
  "actions" : {
    "email_admin" : { 
      "email": {
        "to": "'Recipient Name <recipient@example.com>'",
        "subject": "Error Monitoring Report",
        "attachments" : {
          "error_report.pdf" : {
            "reporting" : {
              "url": "http://0.0.0.0:5601/api/reporting/generate/printablePdf?jobParams=...", 
              "retries":40, 
              "interval":"15s", 
              "auth":{ 
                "basic":{
                  "username":"elastic",
                  "password":"changeme"
                }
              }
            }
          }
        }
      }
    }
  }
}

	You must configure at least one email account to enable Watcher to send email. For more information, see Configuring email accounts.
	This is an example POST URL. You can copy and paste the URL for any report from the Kibana UI.
	Optional, default is 40
	Optional, default is 15s
	Provide user credentials for a user with permission to access Kibana and the reporting features.

Reporting is integrated with Watcher only as an email attachment type.

The report Generation URL might contain date-math expressions that cause the watch to fail with a parse_exception. Remove curly braces { } from date-math expressions and URL-encode characters to avoid this. For example: ...(range:(%27@timestamp%27:(gte:now-15m%2Fd,lte:now%2Fd))))...

For more information about configuring watches, see How Watcher works.

Use a script

edit

To automatically generate reports from a script, you’ll make a request to the POST URL. The response from this request will be JSON, and will contain a path property with a URL to use to download the generated report. Use the GET method in the HTTP request to download the report.

The request method must be POST and it must include a kbn-xsrf header for Kibana to allow the request.

The following example queues CSV report generation using the POST URL with cURL:

curl \
-XPOST \ 
-u elastic \ 
-H 'kbn-xsrf: true' \ 
'http://0.0.0.0:5601/api/reporting/generate/csv?jobParams=...'

	`POST` method is required.
	Provide user credentials for a user with permission to access Kibana and reporting features.
	The `kbn-xsrf` header is required for all `POST` requests to Kibana. For more information, see API Request Headers.
	The POST URL. You can copy and paste the URL for any report from the Kibana UI.

Here is an example response for a successfully queued report:

{
  "path": "/api/reporting/jobs/download/jxzaofkc0ykpf4062305t068", 
  "job": {
    "id": "jxzaofkc0ykpf4062305t068",
    "index": ".reporting-2018.11.11",
    "jobtype": "csv",
    "created_by": "elastic",
    "payload": ..., 
    "timeout": 120000,
    "max_attempts": 3,
    "priority": 10
  }
}

	The relative path on the Kibana host for downloading the report.
	(Not included in the example) Internal representation of the reporting job, as found in the `.reporting-*` index.

HTTP response codes

edit

The reporting APIs use HTTP response codes to give feedback. In automation, this helps external systems track the various possible job states:

200 (OK): As expected, Kibana returns 200 status in the response for successful requests to queue or download reports.

Kibana will send a 200 response status for successfully queuing a Reporting job via the POST URL. This is true even if the job somehow fails later, since report generation happens asynchronously from queuing.
400 (Bad Request): When sending requests to the POST URL, if you don’t use POST as the HTTP method, or if your request is missing the kbn-xsrf header, Kibana will return a code 400 status response for the request.
503 (Service Unavailable): When using the path to request the download, you will get a 503 status response if report generation hasn’t completed yet. The response will include a Retry-After header. You can set the script to wait the number of seconds in the Retry-After header, and then repeat if needed, until the report is complete.
500 (Internal Server Error): When using the path to request the download, you will get a 500 status response if the report isn’t available due to an error when generating the report. More information is available at Management > Kibana > Reporting.

Deprecated report URLs

edit

The following POST URL paths are deprecated. If there are any problems with using these paths after you upgrade Kibana, use Kibana to regenerate the POST URL for a particular report.

Dashboard reports: /api/reporting/generate/dashboard/<dashboard-id>
Visualize reports: /api/reporting/generate/visualization/<visualization-id>
Saved Search reports: /api/reporting/generate/search/<saved-search-id>

Previously there was a &sync parameter appended to generation URLs which would hold the request open until the document was fully generated. This feature has been removed. Existing use of the &sync parameter, in Watcher for example, will need to be updated.

« Reporting Reporting configuration »