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
  • Entity types
  • Default entity types
  • Custom entity types
  • Defining entities via YAML file
  • Adding metadata to the entity descriptor
  • Managing entities
  • Editing in the UI or via GitOps
  • Unique identifiers for entities
  • Adding entities to catalogs
  • Managing all entities across catalogs
  • View entity types
  • View relationship types
  • Archive entities
  • Understanding the entity types
  • Adjusting general settings for entities

Was this helpful?

Export as PDF
  1. Ingesting data into Cortex

Managing Entities

Last updated 1 month ago

Was this helpful?

An entity is an object that represents a software construct. A defined collection of entities is known as a . All entities are represented in YAML, can pull in data from integrations, and can be .

Each entity has its own page that centralizes data related to it, allowing you to quickly access the information you're looking for. Learn more in the documentation.

Entity types

You can or use one of the default entity types.

Default entity types

By default, Cortex supports the following entity types:

  • Services: The default type and the core of your catalog, used for entities such as microservices, libraries, components, etc – essentially any codebase-like module. Learn more in .

  • Domains: An entity that allows you to group your services, resources, and other domains into hierarchical, logical units. Learn more in .

  • Teams: An entity to store all of your team data. Learn more in .

  • Cortex also supports pulling in resources directly from AWS, Azure Resources, and Google Cloud as their corresponding types.

    • For AWS, you can select which entity types to include in your .

    • For Azure Resources, you can select which entity types to include in your .

    • For Google, see the list of .

Custom entity types

In addition, you can create custom entity types to fit your organization's needs. Learn more in .

Defining entities via YAML file

Each file is a fully compliant OpenAPI 3 spec file, with our own Cortex-specific extensions.

You can still use Cortex if you don't use OpenAPI/Swagger. We use the OpenAPI spec as a base for entity metadata, since it's an open spec with official support for extensions. That lets us extend it to be an entity descriptor spec with optional usage of actual OpenAPI fields.

Adding metadata to the entity descriptor

Any additional metadata you want to add to your descriptor belongs in the info section. Throughout the docs, you'll see snippets that start with x-cortex-* – make sure to add this to the info section.

Note that it is not currently supported to include comments in YAML files.

Managing entities

Editing in the UI or via GitOps

By default, your account is configured to edit entities through the UI. We recommend starting with the UI editor, which includes a built-in YAML editor, then switching over to GitOps when ready for a wider rollout.

  1. Scroll down to the "Options by entity type" tile.

  2. To only allow editing of entities via GitOps, toggle off the setting next to Enable UI editing for new entity types.

  3. To only allow creation of entities via GitOps, toggle off the setting next to Enable UI importing for new entities.

  • Domain definitions should live in the .cortex/domains directory in your repository.

  • Team definitions should live in the .cortex/teams directory in your repository.

You may store all of your entity definitions in a single repository or you can store the YAML in the repository of the corresponding service.

See the single repository example below:

.
└── .cortex
    ├── catalog
    │   ├── database.yml
    │   ├── s3-bucket.yml
    │   ├── auth-service.yml
    │   └── billing-service.yml
    ├── domains
    │   ├── billing-domain.yml
    │   └── health-domain.yml
    ├── teams
    │   ├── eng-team.yml
    │   └── sre-team.yml

Unique identifiers for entities

Entity tag

The entity tag must be globally unique across all entities.

Cortex ID

In Cortex, the CID for an entity appears in the URL for an entity and at the top of an entity page:

The CID does not appear in an entity's YAML file, as it cannot be modified.

Adding entities to catalogs

For the default catalogs, the entity type criteria is set by default:

  • The Services catalog contains service entity types

  • The Domains catalog contains domain entity types

  • The Teams catalog contains team entity types

  • The Infrastructure catalog contains any entities that are not the types service, domain, or team.

Managing all entities across catalogs

Once you’ve imported entities, you’ll be able to see the entity’s name and tag. In the beginning, you may have just a few dozen entities, but eventually you may have hundreds, if not thousands, of entities across all catalogs.

Search across and filter all entities

There are several ways to search and filter your entities list:

  • To find specific entities, use the search bar in the upper right corner of the entities list and type to search.

  • Click Name to select whether you want to sort by name or identifier, and whether to sort ascending or descending.

  • Click Filter to narrow down your list by associated Git repository, unowned entities, AWS account ID or region, domain, entity type, group, team, or user.

Key performance indicators listed for all entities

Click Display to select whether to display the following key performance indicators as columns alongside entities:

  • Health: When you click into this column in an entity's row, you can view more information on:

    • Monitors: Shows how entities are performing against monitors you’ve created in your APM. When an entity is passing all monitors, this cell will display All OK; otherwise, it will display Failing, Warning, or No Data, along with how many monitors the entity is not hitting. This information is pulled from Datadog.

    • Error rate: Shows the percentage of transactions that result in a failure during a pre-specified window. This information is pulled from New Relic.

If you have not set up an integration needed to populate a column, that column will not appear on the "All entities" page or on specific catalogs. If an integration is established, but the data and/or configuration for an entity do not exist, the cell will display “None.”

View entity types

A Cortex logo appears next to built-in entity types. When you hover over the logo, you will see a "Powered by Cortex" banner:

View relationship types

The ability to add relationship types is available in beta. Please reach out to Cortex Customer Engineering with any feedback.

Relationship types allow you to define, manage, and visualize relationships between entities within your Cortex workspace.

Archive entities

Understanding the entity types

To learn more about adding each type of entity, see their documentation pages:

Adjusting general settings for entities

Whether you use to manage entities, every entity in your Cortex catalogs is defined by a YAML file called the Cortex entity descriptor, also referred to as an entity's Cortex YAML (stemming from cortex.yaml, the name of the file that powers the .)

If you want to use to manage your entity YAML files, you can change this setting:

In Cortex, navigate to .

If you want to adjust these settings per entity type, you can disable the toggles for individual entity types. In the list of entity types, disable the toggles next to UI editing and UI importing to use a GitOps approach instead of the UI.

When using , you can define any number of entities in any repository.

Read more in .

The entity tag - the value of x-cortex-tag in an entity's YAML file - is a customizable unique identifier that's used throughout Cortex. For example, the entity tag is used to declare dependencies on other entities or look up information using the Cortex .

You cannot change an entity's x-cortex-tag. Attempting to update the x-cortex-tag value will result in a new entity being created with that new tag value. To change an entity's x-cortex-tag, you must or delete the entity then create a new entity with the desired tag.

A Cortex ID (CID) is a unique, immutable entity ID that can be used outside of Cortex for historical tracking and reporting. It can be used in the API, in CQL queries, in-app, and you can use it with the Cortex . The ID is automatically generated by Cortex and it is 18 characters in length.

After an entity is imported or created, it will automatically belong to a catalog based on the entity type criteria set for each catalog. When you , you can set the entity type criteria.

By default, any you create will belong to the Infrastructure catalog. If you do not want the entity type to belong to this catalog, you can add the entity type to a different catalog.

The lists all entities that have been imported into Cortex, across all types. This page will open to the Mine tab when a user owns any entities; otherwise, it will default to the All entities tab.

Click Display to choose whether to show archived entities in the list, and select which columns to display alongside entities. Learn more about the below.

Incidents: Displays how many active incidents are associated with a given entity. This information is pulled from , , , and .

Apdex (Application Performance Index): Ratio of the number of satisfied and tolerating requests to the total number requests made. This information is pulled from New Relic.

To view all entity types, go to Catalogs > All Entities then click the .

The other entity types in the list are . To learn more about creating entity types, see .

To view all relationship types, go to Catalogs > All entities then click the .

To learn more, see .

It's possible to delete entities, but for historical posterity you may want to archive entities. To keep your data up to date without manual effort, we recommend configuring when they are no longer detected in your integrations or when their corresponding YAML files are deleted.

It is also possible to manually archive entities in the Cortex UI or via the API. Learn more in .

Admins, or users with the Configure settings permission, can adjust system-wide settings for entities under . Learn more in .

GitOps
Settings > GitOps
GitOps
Using GitOps for Cortex
Slack Bot
archive
Slack Bot
All entities page
FireHydrant
incident.io
PagerDuty
Rootly
Entity types tab
custom types
Add custom entity types
Relationship types tab
Defining relationship types
auto-archival of entities
Archiving entities
Add services
Add domains
Add teams
Add custom entity types
Settings > Entities > General
Entity settings
the UI or GitOps
GitOps approach
create a custom catalog
custom entity types
performance indicator columns
catalog
Scorecarded
Entity details page
Add services
Add domains
Add teams
AWS integration settings
Azure Resources integration settings
Add custom entity types
create your own entity types
supported entity types here
The CID is in the URL and the entity details page.
Use the search and filter options in the upper right side of the entities list.