Using CQL reports

CQL reports offer a new level of visibility into your entities, extending the power of CQL and the Query Builder into reporting. CQL reports allow you to query all of the raw data in Cortex and build custom reports on top of it. Whereas Query Builder and Scorceards require expressions to evaluate to a boolean, CQL report expressions allow you to view any expression result, allowing you to to query, for example, the exact number of incidents services had in the last week.

To see CQL reports, navigate to Tools > CQL reports in the main nav.

Create a CQL report

You will need the Run query builder permission. If you are running queries on third-party integrations, you will also need the Run query builder with third-party integrations permission.

1. In the upper right corner of the page, click Create CQL report.

2. Choose whether to start from scratch or use a template.

   • If you opt to work from a template, you’ll be able to select from any of your organization’s available templates — along with templates built into Cortex — making it easier to ensure all best practices are being followed.

3. Configure the report details:

   • CQL report name: Enter a name for the report.

   • Description: Enter a description for the report. This helps others in your workspace understand the purpose of the report.

   • Enable auto refresh: Enable this toggle setting if this report should be automatically evaluated on a specified interval.

     • Evaluation window: Set how often you want this report to be evaluated. The minimum refresh window is 12 hours, and the maximum is 336 hours (2 weeks).

       

       While configuring the CQL report, you can enable auto refresh.
   • Apply to specific entities: Optionally narrow the scope of your report by selecting specific entities. If left blank, the report will apply to all entities.

     • Advanced options: You can further refine your selection by including or excluding groups.

   • Columns:

     • Click Add column to start adding new CQL expressions to the report.

       • If you used a template, you can click the pencil icon next to an existing rule to edit it.

     • When adding or editing columns, you can write a CQL expression or use the form builder, which allows you to select rules from your configured integrations. To use the form builder, click the Form tab:

     • When you are done adding a column, click Save column at the bottom of the side panel.

4. When you are done adding columns, click Create at the bottom of the page.

   1. If you want your report to be publicly available to other users in your workspace, enable the toggle next to Public.

Note that if the return value is too large (like a 5 MB JSON file) the cell in the report results will error out, so we recommend defining raw values for outputs. The maximum data size that can be the value of a cell is 2048 bytes.

View CQL reports

You can view previously created CQL reports at Tools > CQL reports. Click into a report name to view its results.

Refresh a CQL report

Cortex does not automatically refresh a CQL report. If you did not configure auto refresh for the report, you can refresh it manually: While viewing the results page, click the 3 dots icon, then click Refresh CQL report.

If a report contains expressions written using an outdated version of CQL, you will see a warning banner at the top of the page stating that the report cannot be refreshed. After you update any outdated CQL queries, you will be able to refresh the report.

Enable auto refresh for CQL reports

While creating a CQL report, you can schedule an auto refresh. By default, auto refresh is disabled.

If you didn't add auto refresh when creating the CQL report, you can also edit the report later on to enable the setting.

With auto refresh enabled, in the upper right corner of a CQL report page, you will see the last refresh time and the next scheduled evaluation:

The page displays the last refresh and the next evaluation time.

Edit a CQL report

To edit an existing CQL report:

1. Navigate to Tools > CQL Reports. Click the CQL report you want to edit.

2. In the upper right corner of the CQL report, click Edit.

3. Make any necessary changes, then at the bottom of the page, click Save.

Using CQL reports to debug Scorecards

You can use CQL reports to help interpret unexpected results from Scorecards.

For example, let's say you have a service that is failing the rule Readme created. However, you believe the service does have a readme file, and you aren't sure why it's failing this rule.

• We could create a CQL report from scratch and add a new column for the README CQL expression to check for README.md in the git repo:
• After saving the CQL report, you can view the results to see the contents of readme files for each entity. In this report, you will be able to see if the readme contains an error such as "The result is too large to store," which would explain why the entity is failing that rule in the Scorecard.