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.

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] More information about HTTP / script stuff #41200

Merged
merged 12 commits into from
Jul 18, 2019
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.
tsullivan marked this conversation as resolved.
Show resolved Hide resolved

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

Choose a reason for hiding this comment

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

note: easy-to-miss soft line break here

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.**
tsullivan marked this conversation as resolved.
Show resolved Hide resolved
<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*
Copy link
Member Author

Choose a reason for hiding this comment

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

All this is moved to a standalone section, because it grew pretty large

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