Creating a Report

Data analytics

The CloudBees Analytics Report editor lets you define a report based on criteria such as filters (search criteria), aggregations, and sorting. You create the query definition for a report by using the Report Editor.

These reports are based on Elasticsearch Query DSL and provide an interface to common Elasticsearch queries. The Report Editor includes an Advanced mode, which lets you edit the query DSL directly.

You can add, remove, or alter reporting filters or parameters for command center dashboards in the same manner as the standard types of dashboards. But you cannot add, remove, or alter reporting filters or parameters for the out-of-the-box Release Command Center dashboard. However, you can edit a custom copy of the Release Command Center dashboard, because CloudBees Software Delivery Automation creates a copy of the Release Command Center dashboard when you edit and save it for the first time.

You select from a list of available reports when you create a CloudBees Analytics dashboard widget.

The Reports list

To open the reports list, from the main menu select Analytics Reports; the Reports list opens.

The reports list shows all of the reports that are available in the currently-selected project or projects. The list comprises reports included with CloudBees Software Delivery Automation as well as any custom reports that you have created. By default, the reports are listed for all projects. You can filter this list by any combination of projects via the projects menu.

A variety of out-of-the-box reports are included with CloudBees Software Delivery Automation. These reports can help you learn about the reporting functionality and how to create your own reports. You can also make copies of these reports to use as templates for creating reports. These reports are in the CloudBees project and are not editable.

Click Views of a specific report for quick access to its Report editor and Tabular preview.

Creating a custom report

To create a report:

  1. From within the reports list, click New.

  2. Select Report Create New. The CloudBees Analytics Report Editor appears.

    This shows the standard editing mode, which is the default mode when you open the report editor. The editor lets you define any number of search criteria and aggregation types for creating custom reports.

Make sure you have a good understanding how your report queries, data, and resulting response can affect system performance when report is run.

Editing a report query

  • Use the report editor to create your report’s query. As you create the report, the Code View window shows a read-only view of the underlying DSL code for your query. This view changes dynamically as you modify the report.

  • Click Save on the right side of the page to save your changes: you must save the report if you want to subsequently edit the underlying DSL code directly.

Report search criteria

The list of search criteria determines the matching for specific object attribute values. You can add one or more search criteria by clicking the Search Criterion button in the report editor.

Object attribute fields

The Fields pulldown menu displays the list of available object attributes. Examples are Build Name, Build Status, Controller URL, and so on.

If the pipeline run, job, or process has output parameters, they appear in the Fields pulldown menu and can be used in the report definition just like any other field. For example, for an output parameter named test, Output Parameter: test is available from the menu. If a desired output parameter is not available in this list, see Sending Additional Data for Pipeline Runs, Deployments, and Jobs to the CloudBees Analytics server for instructions.

Object attribute fields are only available with the CloudBees CD/RO capability.

Search operators

The following search operators are available:

OperatorApplicable Attribute Data Types

Equals

All

Exists

All

Not Exists

All

Greater than

All data types except BOOLEAN

Greater than or Equals

All data types except BOOLEAN

Less than

All data types except BOOLEAN

Less than or Equals

All data types except BOOLEAN

Between

All data types except BOOLEAN

Values to match

The field in the Value column represents the particular search value to match.

Adding search conditions

You can add conditions to the search criteria by clicking the Add Condition button:

Aggregations and sorting

Aggregations and sorting determine the grouping or order of the query results, respecteively. You can choose either aggregation or sorting, but not both.

Query result aggregations

You can add aggregations by clicking the Add Aggregation button.

You can add functions by clicking the Add Function button. The following functions are available:

FunctionApplicable for Attribute Types

Average

NUMERIC, PERCENT

Count

All

Distinct Count

All

Max

NUMERIC, PERCENT, DATE, DATETIME

Min

NUMERIC, PERCENT, DATE, DATETIME

Sum

NUMERIC, PERCENT

Query result sorting

As an alternative to aggregating the query results, you can sort them. For example:

You can sort the query results by a specific object attribute field in ascending or descending order. You can specify the number of rows for the query to return. To add a secondary sorting field, click Sorting.

Editing advanced mode report queries

Advanced mode shows a view of the underlying query DSL code. You enter and exit advanced mode by clicking the Advanced slider button in the upper right corner of the UI. You can now edit the query DSL code directly.

Note that editing the query DSL code makes it incompatible with Standard mode in the Report Editor. The following warning is always present in Advanced mode as a reminder:

If you make modifications in Advanced Mode and save them, they will not carry over to the Report editor.

For details about Elasticsearch Query DSL, see the "Elastic Stack and Product Documentation" web page at https://www.elastic.co.

Using tabular preview

To check your query results, click Tabular preview at the top of the page. This view shows the first 20 rows of output so that you can test your report criteria. The tabular preview provides a preview of the report data from the CloudBees Analytics server.

The tables in the following examples describe some of the columns that might be returned based on the report that you have defined.

Example report: Build outcome

This report is included in CloudBees Analytics.

The following table shows some of the date-based fields stored in Elasticsearch for this report and their corresponding formatted fields.

ColumnDescription

Timestamp

Time of the build.

Build Number

Unique build number or identifier assigned to the build by CloudBees CI.

Build System Type

Name of the continuous integration system. For example, CloudBees CI.

Sending additional data

The data that CloudBees Software Delivery Automation manages for CloudBees Software Delivery Automation runtime objects (pipelines, jobs, and deployments) and sends automatically to the CloudBees Analytics server is predetermined based on the specific object type. However, adding output parameters to the runtime objects of your choice in the CloudBees Software Delivery Automation Deploy UI lets you capture their data so that it is sent to CloudBees Analytics in the same payload that is normally sent by CloudBees Software Delivery Automation for these objects. In this way, output parameters provide an extensible mechanism for adding fields for these objects to a report.

Adding an output parameter to a report is much simpler than adding an input parameter, because you actually create the output parameter ahead of time outside of the Report Editor. To send additional data from pipeline runs, deployments, and jobs to the CloudBees Analytics server:

Output parameter prerequisites

  • Declare the output parameter on the desired runtime object in the Floy UI at the object level.

    For details, see "Declaring an Output Parameter" in the CloudBees Software Delivery Automation User Guide .

  • Set the output parameter’s value in some manner on the object.

    For details, see "Creating or Editing an Output Parameter" in the CloudBees Software Delivery Automation User Guide .

    The menu display name for any output parameter that is available for use in reports is Output Parameter: < parameter_name >. For example, for an output parameter created in the CloudBees Software Delivery Automation UI named test, the menu display name in the Report Editor is Output Parameter: test. ++ Output parameters are sent as regular fields in the payload but are prefixed with ec_param_ for identification purposes. For example, for an output parameter named test, the value is saved as ec_param_test in the CloudBees Analytics server:

  • Run the pipeline, job, or deployment .

    For details, see "Running Pipelines" in the CloudBees Software Delivery Automation User Guide .

After the first runtime of that object, the parameter is pushed to the CloudBees Analytics server and is then available for addition to a report.

Adding the output parameters

Creating a custom report

Copying another report lets you create a custom report more quickly. You can copy your custom reports as well as reports that are included with CloudBees Software Delivery Automation. You cannot edit reports that are included with CloudBees Software Delivery Automation, but copying them provides a substitute for customizing their functionality while preserving them to use as templates for future custom reports.

  1. From within the Reports list, select New.

  2. Select Report Copy Existing: the From Report dialog box appears.

  3. Click the name of the report that you want to copy.

    You can narrow down the list of projects by selecting one or more projects from the projects pulldown menu or by entering search terms into the Search field: the New Report dialog box appears.

  4. Enter the new report name into the dialog box, and then select the project that will contain the report.

    By default, new reports are added to the CloudBees project. You can enter a report description into the comments field if needed.

  5. Click OK to save your changes: the new report appears in the Report editor.

  6. Customize the new report’s query as described in Report search criteria .

Editing a custom report

Any custom report is editable. To edit a report:

  • Open the reports list as described in the reports list .

  • Do one of the following to open the Report Editor:

    • Click the report.

    • Click the corresponding view selector button for the report, and select Report editor.

  • Edit the report as described in Editing a custom report .

Adding input parameters to reports

Parameters are free-form input values that can be fed to a dashboard or report to filter the data based on the parameter value. For example, the Release Command Center dashboard shows metrics and trends over the last 10 days.

You might want to view the trend over a different time interval such as the last month or last two weeks based on the duration of your releases. In this case, parameters let you define the time interval as a parameter that can be used by the dashboard or report viewer to change the time interval for viewing the Release Command Center metrics.

To add a parameter, open the Parameters dialog, click on the object menu located in the upper right corner of the report editor, and select Parameters.

Unresolved include directive in modules/accessing-data/pages/reports.adoc - include::cloudbees-cd::partial$user-guide/custom-parameters.adoc[]