Automating report generation
editAutomating report generation
editAutomatically 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
editCreate the POST URL that triggers a report to generate.
To create the POST URL for PDF reports:
-
Go to Visualize or Dashboard, then open the visualization or dashboard.
To specify a relative or absolute time period, use the time filter.
- From the Kibana toolbar, click Share, then select PDF Reports.
-
Click Copy POST URL.
To create the POST URL for CSV reports:
-
Load the saved search in Discover.
To specify a relative or absolute time period, use the time filter.
- From the Kibana toolbar, click Share, then select CSV Reports.
-
Click Copy POST URL.
Use Watcher
editTo 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
editTo 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=...'
|
|
Provide user credentials for a user with permission to access Kibana and reporting features. |
|
The |
|
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 |
HTTP response codes
editThe 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 returns200
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 usePOST
as the HTTP method, or if your request is missing thekbn-xsrf
header, Kibana will return a code400
status response for the request. -
503
(Service Unavailable): When using thepath
to request the download, you will get a503
status response if report generation hasn’t completed yet. The response will include aRetry-After
header. You can set the script to wait the number of seconds in theRetry-After
header, and then repeat if needed, until the report is complete. -
500
(Internal Server Error): When using thepath
to request the download, you will get a500
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
editThe 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.