LogoLogo
Login to CortexBook a DemoCortex Academycortex.io
  • Cortex Docs
  • Cortex Quick Start
  • Ingesting data into Cortex
    • Managing Entities
      • Adding entities
        • Add services
        • Add domains
        • Add teams
        • Add custom entity types
        • Defining dependencies
      • Entity details page
      • Defining ownership
      • Defining relationship types
      • Grouping entities
      • Adding external documentation
      • Adding Deploy data
      • Adding custom data
      • Viewing discovered entities
      • Archiving entities
      • Relationship graph
      • Using On-call Assistant for incidents
      • Managing Terraform infra in Cortex
    • Managing Catalogs
    • Integrations
      • Internally hosted integrations
      • ArgoCD
      • AWS
      • Azure DevOps
      • Azure Resources
      • BambooHR
      • Bitbucket
      • BugSnag
      • Buildkite
      • Checkmarx
      • CircleCI
      • ClickUp
      • Codecov
      • Coralogix
      • Custom webhook integrations
      • Datadog
      • Dynatrace
      • Entra ID (Azure AD)
      • FireHydrant
      • GitHub
      • GitLab
      • Google
      • Grafana
      • incident.io
      • Instana
      • Jenkins
      • Jira
      • Kubernetes
      • LaunchDarkly
      • Lightstep
      • Mend
      • Microsoft Teams
      • New Relic
      • Okta
      • Opsgenie
      • PagerDuty
      • Prometheus
      • Rollbar
      • Rootly
      • Sentry
      • ServiceNow
      • Slack
      • Snyk
      • SonarQube
      • Splunk Observability Cloud (SignalFx)
      • Splunk On-Call (VictorOps)
      • Sumo Logic
      • Veracode
      • Wiz
      • Workday
      • xMatters
  • Scorecards
    • Initiatives and Action items
      • Creating issues based on Initiatives
    • Scorecard rule exemptions
    • Scorecard rule filters
    • Scorecard examples
    • Scorecards as code
  • Reports
    • Executive report
    • All Scorecards report
    • Bird's eye report
    • Progress report
    • Report card
  • Eng Intelligence
    • Custom Metrics
    • Jira Metrics
    • Metrics Explorer (Beta)
  • Cortex Query Language (CQL)
    • Using CQL reports
    • Using JQ in Cortex
  • Workflows
    • Creating a Workflow
      • Workflows as code
    • Blocks
    • Running a Workflow
    • Registering a Scaffolder template
      • Scaffolder advanced usage
    • Using a Workflow to sync in ArgoCD
    • Kicking off a Jenkins pipeline in a Workflow
    • Calling internal service endpoints in a Workflow
  • Plugins
    • Creating a plugin
      • Creating a plugin proxy
    • Migrating Backstage plugins to Cortex
  • Engineering homepage
  • Workspace Settings
    • Using GitOps for Cortex
      • GitOps logs
    • Managing users
      • Roles and permissions
        • Custom roles
        • Team ownership entity editing
      • Configuring SSO
        • Microsoft Entra ID
        • Google
        • Other OIDC providers
        • Okta
          • Okta SCIM
      • Configuring identity mappings
      • Onboarding management
    • API keys, secrets, and tokens
      • Secrets
      • Personal tokens
    • Audit logs
    • Entity settings
      • Data verification
      • Auto archiving entities
    • IP allowlist
    • Notifications
      • Notification logs
    • Customizing your workspace
    • Using search in Cortex
  • Cortex API
    • REST API operations
      • API Keys
      • Audit Logs
      • Catalog Entities
      • Custom Data
        • Custom Data (Advanced)
      • Custom Events
      • Custom Metrics
      • Dependencies
      • Deploys
      • Discovery Audit
      • Docs
      • Eng Intel: User Labels
      • Entity Relationship Types (Beta)
      • Entity Relationships (Beta)
      • Entity Types
      • GitOps Logs
      • Groups
      • Initiatives
      • Integrations APIs
        • Azure Active Directory (Entra ID) API
        • Azure Resources API
        • AWS API
        • Azure DevOps API
        • CircleCI API
        • Coralogix API
        • Datadog API
        • GitHub API
        • GitLab API
        • incident.io API
        • LaunchDarkly API
        • New Relic API
        • PagerDuty API
        • Prometheus API
        • SonarQube API
      • IP Allowlist
      • Notification Logs
      • On call
      • Packages
      • Plugins
      • Queries
      • SCIM
      • Scorecards
      • Secrets
      • Team Hierarchies
      • Teams
      • Workflows
Powered by GitBook
On this page
  • Create a CQL report
  • View CQL reports
  • Refresh a CQL report
  • Enable auto refresh for CQL reports
  • Edit a CQL report
  • Using CQL reports to debug Scorecards

Was this helpful?

Export as PDF
  1. Cortex Query Language (CQL)

Using CQL reports

Last updated 2 months ago

Was this helpful?

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

    • 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

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:

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.

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

While , you can schedule an auto refresh. By default, auto refresh is disabled.

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:

creating a CQL report
While configuring the CQL report, you can enable auto refresh.
The page displays the last refresh and the next evaluation time.