Skip to content

Commit

Permalink
[Docs/Reporting] More information about HTTP / script stuff (elastic#…
Browse files Browse the repository at this point in the history
…41200)

* [Docs/Reporting] More information about HTTP / script stuff

* "post url" formatting consistency

* consistent wording from 1 paragraph to another

* Update docs/reporting/response-codes.asciidoc

Co-Authored-By: gchaps <[email protected]>

* pr feedback

* subs=attributes, version in command example

* "Retry-After" content

* another feedback
  • Loading branch information
tsullivan committed Jul 18, 2019
1 parent f1d6c05 commit abdad5b
Show file tree
Hide file tree
Showing 3 changed files with 40 additions and 23 deletions.
7 changes: 6 additions & 1 deletion docs/reporting/automating-report-generation.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
[[automating-report-generation]]
== Automating Report Generation
You can automatically generate reports with {watcher}, or by submitting
HTTP POST requests from a script.
HTTP `POST` requests from a script.

include::report-intervals.asciidoc[]

Expand Down Expand Up @@ -38,6 +38,11 @@ include::watch-example.asciidoc[]

include::script-example.asciidoc[]

[float]
=== HTTP Response Codes

include::response-codes.asciidoc[]

[float]
== Deprecated Report URLs

Expand Down
23 changes: 23 additions & 0 deletions docs/reporting/response-codes.asciidoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
The 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 returns `200` status in the response for
successful requests to queue or download reports.
+
NOTE: 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 use
`POST` as the HTTP method, or if your request is missing the `kbn-version` header,
Kibana will return a code `400` status response for the request.
- **`503` (Service Unavailable)**: When using the `path` to request the download, you
will get a `503` status response if report generation hasn't completed yet. The
response will include a `Retry-After` header. You can set the script to wait the
number of seconds in the `Retry-After` header, and then repeat if needed, until the
report is complete.
- **`500` (Internal Server Error)**: When using the `path` to request the download, you
will get a `500` status response if the report isn't available due to an error when
generating the report. More information is available at **Management > Kibana > Reporting**.
33 changes: 11 additions & 22 deletions docs/reporting/script-example.asciidoc
Original file line number Diff line number Diff line change
@@ -1,28 +1,30 @@
To automatically generate reports from a script, you'll make a request to the POST URL.
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.
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-version` header for Kibana
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:
The following example queues CSV report generation using the `POST` URL with cURL:

[source,shell]
["source","sh",subs="attributes"]
---------------------------------------------------------
curl \
-XPOST \ <1>
-u elastic \ <2>
-H 'kbn-version: 8.0.0' \ <3>
-H 'kbn-version: {version}' \ <3>
'http://0.0.0.0:5601/api/reporting/generate/csv?jobParams=...' <4>
---------------------------------------------------------
// CONSOLE

<1> POST method is required.
<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.
<3> The `kbn-version` header is required for all `POST` requests to Kibana.
**The value must match the dotted-numeral version of the Kibana instance.**
<4> The POST URL. You can copy and paste the URL for any report from the Kibana UI.

Here is an example response:
Here is an example response for a successfully queued report:

[source,json]
---------------------------------------------------------
Expand All @@ -45,16 +47,3 @@ Here is an example response:
<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*
===================

0 comments on commit abdad5b

Please sign in to comment.