From 6fe98c8fe8c25ca23bbccedab459391ad0d9083e Mon Sep 17 00:00:00 2001 From: Timothy Sullivan Date: Thu, 11 Jul 2019 14:53:00 -0700 Subject: [PATCH 1/6] [Docs/Reporting] Improve docs on automating Reporting --- .../automating-report-generation.asciidoc | 45 +++++++------- docs/reporting/script-example.asciidoc | 60 +++++++++++++++++++ docs/reporting/watch-example.asciidoc | 20 +++++-- 3 files changed, 98 insertions(+), 27 deletions(-) create mode 100644 docs/reporting/script-example.asciidoc diff --git a/docs/reporting/automating-report-generation.asciidoc b/docs/reporting/automating-report-generation.asciidoc index 02fa2c97f37f2..9895d67f86a91 100644 --- a/docs/reporting/automating-report-generation.asciidoc +++ b/docs/reporting/automating-report-generation.asciidoc @@ -4,34 +4,41 @@ 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: + +. 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**. -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]. +[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 + +include::script-example.asciidoc[] +[float] == Deprecated Report URLs The following is deprecated in 6.0, and you should now use {kib} to get the URL for a @@ -49,11 +56,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..040fb383eead8 --- /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 with 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 will be available in the 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]. From 53617aa32a125c70827ceee7319f162542456870 Mon Sep 17 00:00:00 2001 From: Tim Sullivan Date: Fri, 12 Jul 2019 12:34:58 -0700 Subject: [PATCH 2/6] Update docs/reporting/automating-report-generation.asciidoc Co-Authored-By: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/reporting/automating-report-generation.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reporting/automating-report-generation.asciidoc b/docs/reporting/automating-report-generation.asciidoc index 9895d67f86a91..8da441d8e3c39 100644 --- a/docs/reporting/automating-report-generation.asciidoc +++ b/docs/reporting/automating-report-generation.asciidoc @@ -22,7 +22,7 @@ To get the URL for triggering PDF report generation during a given time period: To get the URL for triggering CSV report generation during a given time period: -. Load a saved search in Discover +. 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*. From fb8f57994d42886ce39230618c2ae79bdedccc5e Mon Sep 17 00:00:00 2001 From: Tim Sullivan Date: Fri, 12 Jul 2019 12:36:31 -0700 Subject: [PATCH 3/6] Update docs/reporting/script-example.asciidoc Co-Authored-By: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/reporting/script-example.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reporting/script-example.asciidoc b/docs/reporting/script-example.asciidoc index 040fb383eead8..9ffb42d348b45 100644 --- a/docs/reporting/script-example.asciidoc +++ b/docs/reporting/script-example.asciidoc @@ -1,5 +1,5 @@ To automatically generate reports from a script, you'll make a request to the POST URL. -The response from this request with be JSON, and will contain a `path` property with a +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 From fcaace166db62fed1867fcef7a66a797c66977a2 Mon Sep 17 00:00:00 2001 From: Tim Sullivan Date: Fri, 12 Jul 2019 12:37:02 -0700 Subject: [PATCH 4/6] Update docs/reporting/script-example.asciidoc Co-Authored-By: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/reporting/script-example.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reporting/script-example.asciidoc b/docs/reporting/script-example.asciidoc index 9ffb42d348b45..8682578735b66 100644 --- a/docs/reporting/script-example.asciidoc +++ b/docs/reporting/script-example.asciidoc @@ -54,7 +54,7 @@ number of seconds in the `Retry-After` header in the download API response until 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 will be available in the the +(Internal Server Error) response. More information is available in the Reporting management page in Kibana: *Management > Kibana > Reporting* =================== From c28b97904a6bb6670165aca8724d634d3f6d56de Mon Sep 17 00:00:00 2001 From: Timothy Sullivan Date: Fri, 12 Jul 2019 13:27:29 -0700 Subject: [PATCH 5/6] --wip-- [skip ci] --- docs/reporting/automating-report-generation.asciidoc | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/reporting/automating-report-generation.asciidoc b/docs/reporting/automating-report-generation.asciidoc index 8da441d8e3c39..06bf175e0cfb4 100644 --- a/docs/reporting/automating-report-generation.asciidoc +++ b/docs/reporting/automating-report-generation.asciidoc @@ -41,10 +41,9 @@ include::script-example.asciidoc[] [float] == Deprecated Report URLs -The following is deprecated in 6.0, and you should now use {kib} to get the URL for a -particular report. - -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, 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/` From 6dced7ca1c0497d0a0a87f66f3ecd94e2a8f8d57 Mon Sep 17 00:00:00 2001 From: Timothy Sullivan Date: Mon, 15 Jul 2019 12:29:15 -0700 Subject: [PATCH 6/6] word change --- docs/reporting/automating-report-generation.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reporting/automating-report-generation.asciidoc b/docs/reporting/automating-report-generation.asciidoc index 06bf175e0cfb4..194702c96afe6 100644 --- a/docs/reporting/automating-report-generation.asciidoc +++ b/docs/reporting/automating-report-generation.asciidoc @@ -42,8 +42,8 @@ include::script-example.asciidoc[] == 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, you should use {kib} to -re-generate the POST URL for a particular report. +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/`