Automating Report Generationedit

You can automatically generate reports with Watcher, or by submitting HTTP POST requests from a script.

Important

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.

Getting the POST URLedit

Generating a report either through Watcher or a script requires capturing the POST URL, which is the URL to queue a report for generation.

To get the URL for triggering PDF report generation during a given time period:

  1. Load the saved object in the Visualize editor, or load a Dashboard.
  2. Use the timepicker to specify a relative or absolute time period.
  3. Click Share in the Kibana toolbar.
  4. Select PDF Reports.
  5. Click Copy POST URL.

To get the URL for triggering CSV report generation during a given time period:

  1. Load a saved search in Discover.
  2. Use the timepicker to specify a relative or absolute time period.
  3. Click Share in the Kibana toolbar.
  4. Select CSV Reports.
  5. Click Copy POST URL.

Using Watcheredit

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":6, 
              "interval":"1s", 
              "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 X-Pack reporting.

Note

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

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

Using a Scriptedit

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:

curl \
-XPOST \ 
-u elastic \ 
-H 'kbn-version: 8.0.0-alpha1' \ 
'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 X-Pack reporting.

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:

{
  "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 Codesedit

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.

    Note

    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 URLsedit

The following POST URL paths were once supported but are now deprecated. If there are any problems with using these paths after upgrading Kibana’s version, you should use Kibana to re-generate 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>
Important

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.