9. 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.
You can find CQL reports under Tools in the main nav.
Select Create CQL report next to the search bar to build your own CQL report.
When creating a CQL report, you have the option to use a CQL report template or Start from scratch. 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.
Regardless of which option you choose, you’ll be prompted to enter a name and description for your report, so you can tell at a glance what each report is querying.
Select entity types to include or exclude under the Apply to specific entities section. You can also use Advanced options to further refine your selection.
From there, you’ll define the CQL expressions that will serve as your report columns. Select Add column to define a new expression, or use the pencil icon to edit an existing column.
Once each expression is saved, Cortex will run the query to generate results for that column. Queries run asynchronously, so the report will generate cell by cell to pull the specific values for each entity.
The same permissions that apply to the query builder apply to CQL reports. Only managers and admins have the ability to run reports that include third-party integrations.
Output cell values can be any type — they can be strings, numbers, booleans, or whatever else you want. Note that if the return value is too large (like a 5 MB JSON file) the cell 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.
As the queries run, you can access results and watch progress as it completes. Just like with the Query builder, Cortex won’t automatically refresh a CQL report, but you can manually refresh at any time.
The maximum data size for output cells in 2048 bytes.
During the creation flow, you also have the option to make your CQL report Public by switching the toggle below Save CQL report.
If you choose to keep the CQL report private, you’ll be the only user able to see the report. Just like with the query builder, public CQL reports will be available to everyone in your organization, so you can easily share your insights with others.
You can return at any point to reconfigure your CQL report, including changing its public/private status.
Using CQL reports to debug Scorecards
Some rules in Scorecards include a hover that identifies the value Cortex is returning.
In the above example, the "Brain Backend" entity is failing the "Has at least one dashboard" rule. When we hover, we can see that the value Cortex detects is 0.
CQL reports can be used to provide more granular information on the value of a rule when passing, or an associated error when failing, especially when this function is not available. Until published, CQL reports are private to the individual user.
Let's say we want to understand why entities are failing a rule that checks for a README file.
We could create a CQL report from scratch and - along with the general information needed to create a CQL report - we'll add a new column for the README CQL expression (without the qualifier).
Once we save the report, we can see the contents of available README files and see which entities have errors.
In this example, we can see the beginning of the README file for the "Backstage Backend Plugin," while the "Auth0 Java" service has an error. When we hover, we can see that the result is too large to store. Other entities may have an error because it has not been registered with the Git integration being used in the query.