diff --git a/docs/reporting/automating-report-generation.asciidoc b/docs/reporting/automating-report-generation.asciidoc index 02fa2c97f37f2..194702c96afe6 100644 --- a/docs/reporting/automating-report-generation.asciidoc +++ b/docs/reporting/automating-report-generation.asciidoc @@ -4,40 +4,46 @@ You can automatically generate reports with {watcher}, or by submitting HTTP POST requests from a script. -To automatically generate reports with a watch, you need to configure -{watcher} to trust the {kib} server’s certificate. For more information, -see <>. - include::report-intervals.asciidoc[] -To get the URL for triggering a report generation during a given time period: +[float] +=== Getting the POST URL + +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: -. Load the saved object. +. Load the saved object in the Visualize editor, or load a Dashboard. . Use the timepicker to specify a relative or absolute time period. . Click *Share* in the Kibana toolbar. . Select *PDF Reports*. . Click **Copy POST URL**. -NOTE: The response from this request with be JSON, and will contain a `path` property -with a URL to use to download the generated report. When requesting that path, -you will get a 503 response if it's not completed yet. In this case, retry after the -number of seconds in the `Retry-After` header in the response until the PDF is returned. +To get the URL for triggering CSV report generation during a given time period: -To configure a watch to email reports, you use the `reporting` attachment type -in an `email` action. For more information, see -{stack-ov}/actions-email.html#configuring-email[Configuring Email Accounts]. +. Load a saved search in Discover. +. Use the timepicker to specify a relative or absolute time period. +. Click *Share* in the Kibana toolbar. +. Select *CSV Reports*. +. Click **Copy POST URL**. + +[float] +=== Using Watcher include::watch-example.asciidoc[] -For more information about configuring watches, see -{stack-ov}/how-watcher-works.html[How Watcher Works]. +[float] +=== Using a Script -== Deprecated Report URLs +include::script-example.asciidoc[] -The following is deprecated in 6.0, and you should now use {kib} to get the URL for a -particular report. +[float] +== Deprecated Report URLs -You may request PDF reports optimized for printing through three {reporting} endpoints: +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 +{kib} to re-generate the POST URL for a particular report. * Dashboard Reports: `/api/reporting/generate/dashboard/` * Visualization Reports: `/api/reporting/generate/visualization/` @@ -49,11 +55,3 @@ Previously there was a `&sync` parameter appended to generation URLs which would 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. =================== - -To specify the time period you want to include in the report, you use the `_g` -parameter in the request. For example: - -[source,shell] ---------------------------------------------------------- -http://0.0.0.0:5601/api/reporting/generate/dashboard/error-monitoring?_g=(time:(from:now-1d%2Fd,mode:quick,to:now-1d%2Fd)) ---------------------------------------------------------- diff --git a/docs/reporting/script-example.asciidoc b/docs/reporting/script-example.asciidoc new file mode 100644 index 0000000000000..8682578735b66 --- /dev/null +++ b/docs/reporting/script-example.asciidoc @@ -0,0 +1,60 @@ +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 when it is complete. + +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: + +[source,shell] +--------------------------------------------------------- +curl \ +-XPOST \ <1> +-u elastic \ <2> +-H 'kbn-version: 8.0.0' \ <3> +'http://0.0.0.0:5601/api/reporting/generate/csv?jobParams=...' <4> +--------------------------------------------------------- +// CONSOLE + +<1> POST method is required. +<2> Provide user credentials for a user with permission to access Kibana and X-Pack reporting. +<3> The `kbn-version` header is required for all POST requests to Kibana. +<4> The POST URL. You can copy and paste the URL for any report from the Kibana UI. + +Here is an example response: + +[source,json] +--------------------------------------------------------- +{ + "path": "/api/reporting/jobs/download/jxzaofkc0ykpf4062305t068", <1> + "job": { + "id": "jxzaofkc0ykpf4062305t068", + "index": ".reporting-2018.11.11", + "jobtype": "csv", + "created_by": "elastic", + "payload": ..., <2> + "timeout": 120000, + "max_attempts": 3, + "priority": 10 + } +} +--------------------------------------------------------- +// CONSOLE + +<1> The relative path on the Kibana host for downloading the report. +<2> (Not included in the example) Internal representation of the reporting job, as +found in the `.reporting-*` index. + +[IMPORTANT] +=================== +When using the `path` to request the download, you will get a 503 (Service Unavailable) +response if report generation hasn't completed yet. In that case, retry after the +number of seconds in the `Retry-After` header in the download API response until the +report is complete. + +If there was an error in generating the report, the download URL will return a 500 +(Internal Server Error) response. More information is available in the +Reporting management page in Kibana: *Management > Kibana > Reporting* +=================== + diff --git a/docs/reporting/watch-example.asciidoc b/docs/reporting/watch-example.asciidoc index 1243d03b454d7..dc64973baa3e9 100644 --- a/docs/reporting/watch-example.asciidoc +++ b/docs/reporting/watch-example.asciidoc @@ -1,5 +1,12 @@ -For example, the following watch generates a report that contains the -*Error Monitoring* dashboard and emails the report every hour: +To automatically generate reports with a watch, you need to configure +{watcher} to trust the {kib} server’s certificate. For more information, +see <>. + +To configure a watch to email reports, you use the `reporting` attachment type +in an `email` action. For more information, see +{stack-ov}/actions-email.html#configuring-email[Configuring Email Accounts]. + +For example, the following watch generates a PDF report and emails the report every hour: [source,js] --------------------------------------------------------- @@ -18,7 +25,7 @@ PUT _watcher/watch/error_report "attachments" : { "error_report.pdf" : { "reporting" : { - "url": "http://0.0.0.0:5601/api/reporting/generate/dashboard/Error-Monitoring?_g=(time:(from:now-1d%2Fd,mode:quick,to:now))", <2> + "url": "http://0.0.0.0:5601/api/reporting/generate/printablePdf?jobParams=...", <2> "retries":6, <3> "interval":"1s", <4> "auth":{ <5> @@ -40,7 +47,7 @@ PUT _watcher/watch/error_report <1> You must configure at least one email account to enable Watcher to send email. For more information, see {xpack-ref}/actions-email.html#configuring-email[Configuring Email Accounts]. -<2> This is an example Generation URL. You can copy and paste the URL for any +<2> This is an example POST URL. You can copy and paste the URL for any report from the Kibana UI. <3> Optional, default is 40 <4> Optional, default is 15s @@ -48,3 +55,8 @@ report from the Kibana UI. {reporting}. //For more information, see <>. //<>. + +NOTE: Reporting is integrated with Watcher only as an email attachment type. + +For more information about configuring watches, see +{stack-ov}/how-watcher-works.html[How Watcher Works].