Reports Microservices

Note: Reports Microservices is currently a beta feature of CDAP 6.2.0, and is subject to change without notice.

Reports provides administrators and developers a way to generate comprehensive report of program runs, specify filters based on various options such as namespaces, program status and type of program, within a given time range such as 24 hours or one week or a custom time range. You can also specify the columns that you would like to include in the generated report.

Reports are backed by the ReportGenerationApp system application, which is a Spark service (named ReportGenerationSpark) with endpoints to generate, list, view, download, share, save or delete reports.

All methods or endpoints described in this API have a base URL (typically http://<host>:11015 or https://<host>:10443) that precedes the resource identifier, as described in the Microservices Conventions. These methods return a status code, as listed in the Microservices Status Codes.

Generating Reports

POST /v3/namespaces/system/apps/ReportGenerationApp/spark/ReportGenerationSpark/methods/reports

With Request Json provided as part of the request body.

Request JSON with explanation of JSON fields:

{
  "name":<Name of the report>,
  "start":<start-time-in-seconds>,
  "end":<end-time-in-seconds>,

  "fields":[
     <include-this-field-1-in-report>,
      <...>,
     <include-this-field-N-in-report>
  ],

  "filters":[
     {
        // value filter
        "fieldName":<name-of-the-field-to-filter-on>,
        "whitelist":[
           <acceptable-value-1>,
           <..>
           <acceptable-value-N>
        ]
     },
     {
        // value filter
        "fieldName":<name-of-the-field-to-filter-on>,
        "blacklist":[
           <non-acceptable-value-1>,
           <...>
           <non-acceptable-value-N>
        ]
     },
     {
        // range filter
        "fieldName":"<name-of-the-field-to-filter-on>",
        "range":{
           "min":<minimum-allowed-value>
           "max":<maximum-allowed-value>
        }
     }
  ],
  "sort":[
     {
        "order":"ASCENDING (or) DESCENDING",
        "fieldName":"<name-of-the-field-to-sort-by>"
     }
  ]
}

Example request JSON:

{
  "name":"Failed, Stopped, Running, Succeeded runs - Jul 23, 2018 00:00am to Jul 24, 2018 21:00pm",
  "start":1532329200,
  "end":1532491200,
  "fields":[
     "artifactName",
     "applicationName",
     "program",
     "programType",
     "namespace",
     "status",
     "start",
     "end"
  ],
  "filters":[
     {
        "fieldName":"status",
        "whitelist":[
           "FAILED",
           "STOPPED",
           "RUNNING",
           "COMPLETED",
           "KILLED"
        ]
     },
     {
        "fieldName":"namespace",
        "whitelist":[
           "default"
        ]
     }
  ]
}

On submitting this request, the backend asynchronously launches a spark job to process and generate the report. The immediate response contains the report id.

You can use this report-id to check the status of the report, if it is running, completed or failed using the info endpoint and download completed reports to get information using download endpoint.

Note: Currently sort cannot be performed on more than one field.

Listing Reports

Query Param	Description

Query Param	Description
offset	offset to read reports from
limit	limit on the number of reports to return

Response JSON with explanation for fields:

Example Response JSON:

Sharing Reports

On Authentication enabled clusters, reports are isolated by logged-in users who generated the reports, If you wish, you can generate an encrypted share-id for your report, that can be used by others to access the report.

Response JSON:

Viewing Report Status

The info endpoint can be used to get the report status and summary for a report. It can be queried either by providing the report-id or by providing a share-id through query param.

For reports that are currently running, the response does not contain a report summary

For failed reports, the response contains the error information.

Downloading Report Contents

The download endpoint can be used to download the report contents. You can either provide a report id or a share id through a query parameter.

Example JSON response:

Saving Reports

By default reports expire after 2 weeks, however they can be saved by using the following Microservices endpoint:

with request body containing the name and description for saving the report:

Deleting Reports

Unneeded reports (whether generated or failed) can be deleted by making a call to the following endpoint: