Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Docs/Reporting] Improve docs on automating Reporting #40931

Merged
merged 8 commits into from
Jul 15, 2019
Merged

[Docs/Reporting] Improve docs on automating Reporting #40931

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
6fe98c8
[Docs/Reporting] Improve docs on automating Reporting
tsullivan Jul 11, 2019
53617aa
Update docs/reporting/automating-report-generation.asciidoc
tsullivan Jul 12, 2019
fb8f579
Update docs/reporting/script-example.asciidoc
tsullivan Jul 12, 2019
fcaace1
Update docs/reporting/script-example.asciidoc
tsullivan Jul 12, 2019
c28b979
--wip-- [skip ci]
tsullivan Jul 12, 2019
a989217
Merge branch 'master' of github.com:elastic/kibana into docs/reportin…
tsullivan Jul 15, 2019
8b0f562
Merge branch 'docs/reporting-post-url' of github.com:tsullivan/kibana…
tsullivan Jul 15, 2019
6dced7c
word change
tsullivan Jul 15, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 22 additions & 23 deletions docs/reporting/automating-report-generation.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <<securing-reporting, Securing Reporting>>.

include::report-intervals.asciidoc[]

To get the URL for triggering a report generation during a given time period:
[float]
=== Getting the POST URL
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Entirely new section to talk about what is 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
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Moved to watch-example

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]
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The lack of this [float] caused this section to be its own page, which seemed wrong

== Deprecated Report URLs

The following is deprecated in 6.0, and you should now use {kib} to get the URL for a
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's not clear "the following is deprecated" refers to.

Copy link
Member Author

@tsullivan tsullivan Jul 12, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What about:

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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, that's much better.

Expand All @@ -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))
---------------------------------------------------------
60 changes: 60 additions & 0 deletions docs/reporting/script-example.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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*
Copy link
Member Author

@tsullivan tsullivan Jul 11, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Info about 503 was pre-existing. Info about the 500 is new

Wrapping this in IMPORTANT is also new

===================

20 changes: 16 additions & 4 deletions docs/reporting/watch-example.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 <<securing-reporting, Securing Reporting>>.

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]
---------------------------------------------------------
Expand All @@ -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>
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

#40661

"retries":6, <3>
"interval":"1s", <4>
"auth":{ <5>
Expand All @@ -40,11 +47,16 @@ 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
<5> Provide user credentials for a user with permission to access Kibana and
{reporting}.
//For more information, see <<secure-reporting>>.
//<<reporting-app-users, Setting up a Reporting Role>>.

NOTE: Reporting is integrated with Watcher only as an email attachment type.
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A new NOTE I felt it important to mention


For more information about configuring watches, see
{stack-ov}/how-watcher-works.html[How Watcher Works].