This documentation contains work-in-progress information for future Elastic Stack and Cloud releases. Use the version selector to view supported release docs. It also contains some Elastic Cloud serverless information. Check out our serverless docs for more details.
« Reporting and sharing Troubleshooting reporting features »
Elastic Docs ›Kibana Guide [master] ›Reporting and sharing

Automatically generate reports

edit

Automatically generate reports

edit

To automatically generate PDF and CSV reports, generate a POST URL, then submit the HTTP POST request using Watcher or a script.

Create a POST URL

edit

Create the POST URL that triggers a report to generate PDF and CSV reports.

To create the POST URL for PDF reports:

  1. Open the main menu, then click Dashboard, Visualize Library, or Canvas.
  2. Open the dashboard, visualization, or Canvas workpad you want to view as a report.

  3. From the toolbar, click Share > PDF Reports, then choose an option:

    • If you are using Dashboard or Visulize Library, click Copy POST URL.
    • If you are using Canvas, click Advanced options > Copy POST URL.

To create the POST URL for CSV reports:

  1. Open the main menu, then click Discover.
  2. Open the saved search you want to share.
  3. In the toolbar, click Share > CSV Reports > Copy POST URL.

Use Watcher

edit

To configure a watch to email reports, use the reporting attachment type in an email action. For more information, refer to Configuring email accounts.

For example, the following watch generates a PDF report and emails the report every hour:

PUT _watcher/watch/error_report
{
  "trigger" : {
    "schedule": {
      "interval": "1h"
    }
  },
  "actions" : {
    "email_admin" : { 
      "email": {
        "to": "'Recipient Name <recipient@example.com>'",
        "subject": "Error Monitoring Report",
        "attachments" : {
          "error_report.pdf" : {
            "reporting" : {
              "url": "http://0.0.0.0:5601/api/reporting/generate/printablePdfV2?jobParams=...", 
              "retries":40, 
              "interval":"15s", 
              "auth":{ 
                "basic":{
                  "username":"elastic",
                  "password":"changeme"
                }
              }
            }
          }
        }
      }
    }
  }
}

Configure at least one email account to enable Watcher to send email. For more information, refer to Configuring email accounts.

An example POST URL. You can copy and paste the URL for any report.

Optional, default is 40.

Optional, default is 15s.

User credentials for a user with permission to access Kibana and the reporting features. For more information, refer to Configure reporting.

Reporting is integrated with Watcher only as an email attachment type.

The report generation URL might contain date-math expressions that cause the watch to fail with a parse_exception. To avoid a failed watch, remove curly braces { } from date-math expressions and URL-encode characters. For example, ...(range:(%27@timestamp%27:(gte:now-15m%2Fd,lte:now%2Fd))))...

For more information about configuring watches, refer to How Watcher works.

Use a script

edit

To automatically generate reports from a script, make a request to the POST URL. The request returns a JSON and contains a path property with a URL that you use to download the report. Use the GET method in the HTTP request to download the report.

To queue CSV report generation using the POST URL with cURL:

curl \
-XPOST \ 
-u elastic \ 
-H 'kbn-xsrf: true' \ 
'http://0.0.0.0:5601/api/reporting/generate/csv?jobParams=...'

The required POST method.

The user credentials for a user with permission to access Kibana and reporting features.

The required kbn-xsrf header for all POST requests to Kibana. For more information, refer to API Request Headers.

The POST URL. You can copy and paste the URL for any report.

An example response for a successfully queued report:

{
  "path": "/api/reporting/jobs/download/jxzaofkc0ykpf4062305t068", 
  "job": {
    "id": "jxzaofkc0ykpf4062305t068",
    "index": ".reporting-2018.11.11",
    "jobtype": "csv",
    "created_by": "elastic",
    "payload": ..., 
    "timeout": 120000,
    "max_attempts": 3
  }
}

The relative path on the Kibana host for downloading the report.

(Not included in the example) Internal representation of the reporting job, as found in the .reporting-* storage.

HTTP response codes

edit

The response payload of a request to generate a report includes the path to download a report. The API to download a report uses 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.

    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-xsrf 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.

Deprecated report URLs

edit

If you experience issues with the deprecated report URLs after you upgrade Kibana, regenerate the POST URL for your reports.

  • Dashboard reports: /api/reporting/generate/dashboard/<dashboard-id>
  • Visualize Library reports: /api/reporting/generate/visualization/<visualization-id>
  • Discover saved search reports: /api/reporting/generate/search/<saved-search-id>

IMPORTANT: In earlier Kibana versions, you could use the &sync parameter to append to report URLs that held the request open until the document was fully generated. The &sync parameter is now unsupported. If you use the &sync parameter in Watcher, you must update the parameter.

« Reporting and sharing Troubleshooting reporting features »