mirror of
https://github.com/elastic/kibana.git
synced 2025-04-23 17:28:26 -04:00
* [Docs/Reporting] Improve docs on automating Reporting (#40931) * [Docs/Reporting] Improve docs on automating Reporting * Update docs/reporting/automating-report-generation.asciidoc Co-Authored-By: gchaps <33642766+gchaps@users.noreply.github.com> * Update docs/reporting/script-example.asciidoc Co-Authored-By: gchaps <33642766+gchaps@users.noreply.github.com> * Update docs/reporting/script-example.asciidoc Co-Authored-By: gchaps <33642766+gchaps@users.noreply.github.com> * --wip-- [skip ci] * word change * [DOCS] Fixes broken reporting links (#41195)
This commit is contained in:
Tim Sullivan
GitHub
parent
4a01832590
commit
e12f403ab6
4 changed files with 103 additions and 33 deletions
|
|
@ -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 <<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
|
||||
|
||||
. Load the saved object.
|
||||
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 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
|
||||
|
||||
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 Kibana's version, you should use
|
||||
{kib} 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>`
|
||||
|
|
@ -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))
|
||||
---------------------------------------------------------
|
||||
|
|
|
|||
|
|
@ -21,8 +21,8 @@ You can also {stack-ov}/automating-report-generation.html[generate reports autom
|
|||
IMPORTANT: Reports are stored in the `.reporting-*` indices. Any user with
|
||||
access to these indices has access to every report generated by all users.
|
||||
|
||||
To use {reporting} in a production environment, {stack-ov}/securing-reporting.html[secure
|
||||
the Reporting endpoints].
|
||||
To use {reporting} in a production environment,
|
||||
<<securing-reporting,secure the Reporting endpoints>>.
|
||||
--
|
||||
|
||||
include::getting-started.asciidoc[]
|
||||
|
|
|
|||
60
docs/reporting/script-example.asciidoc
Normal file
60
docs/reporting/script-example.asciidoc
Normal file
|
|
@ -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*
|
||||
===================
|
||||
|
||||
|
|
@ -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 {kibana-ref}/secure-reporting.html[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]
|
||||
---------------------------------------------------------
|
||||
|
|
@ -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 <<secure-reporting>>.
|
||||
//<<reporting-app-users, Setting up a Reporting Role>>.
|
||||
|
||||
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].
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue