Automating report generation

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

Create the POST URL that triggers a report to generate.

To create the POST URL for PDF reports:

  1. Go to Visualize or Dashboard, then open the visualization or dashboard.

    To specify a relative or absolute time period, use the time filter.

  2. From the Kibana toolbar, click Share, then select PDF Reports.

  3. Click Copy POST URL.

    Generate Visualize and Dashboard reports

To create the POST URL for CSV reports:

  1. Load the saved search in Discover.

    To specify a relative or absolute time period, use the time filter.

  2. From the Kibana toolbar, click Share, then select CSV Reports.

  3. Click Copy POST URL.

    Generate Discover reports

Use Watcher

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:

  1. PUT _watcher/watch/error_report
  2. {
  3.   "trigger" : {
  4.     "schedule": {
  5.       "interval": "1h"
  6.     }
  7.   },
  8.   "actions" : {
  9.     "email_admin" : { 
  10.       "email": {
  11.         "to": "'Recipient Name <recipient@example.com>'",
  12.         "subject": "Error Monitoring Report",
  13.         "attachments" : {
  14.           "error_report.pdf" : {
  15.             "reporting" : {
  16.               "url": "http://0.0.0.0:5601/api/reporting/generate/printablePdf?jobParams=...", 
  17.               "retries":40, 
  18.               "interval":"15s", 
  19.               "auth":{ 
  20.                 "basic":{
  21.                   "username":"elastic",
  22.                   "password":"changeme"
  23.                 }
  24.               }
  25.             }
  26.           }
  27.         }
  28.       }
  29.     }
  30.   }
  31. }

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

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-version header for Kibana to allow the request.

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

  1. curl \
  2. -XPOST \ 
  3. -u elastic \ 
  4. -H 'kbn-version: 7.9.1' \ 
  5. '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-version header is required for all POST requests to Kibana. The value must match the dotted-numeral version of the Kibana instance.

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:

  1. {
  2.   "path": "/api/reporting/jobs/download/jxzaofkc0ykpf4062305t068", 
  3.   "job": {
  4.     "id": "jxzaofkc0ykpf4062305t068",
  5.     "index": ".reporting-2018.11.11",
  6.     "jobtype": "csv",
  7.     "created_by": "elastic",
  8.     "payload": ..., 
  9.     "timeout": 120000,
  10.     "max_attempts": 3,
  11.     "priority": 10
  12.   }
  13. }

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

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-version 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

The following POST URL paths were once supported but are now deprecated. If there are any problems with using these paths after upgrading Kibana, use Kibana 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>
  • 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.

Most Popular