Managing Entities

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

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 Entity details page documentation.

Entity types

You can create your own entity types 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 Add services.

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

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

• 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 AWS integration settings.

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

  • For Google, see the list of supported entity types here.

Custom entity types

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

Defining entities via YAML file

Whether you use the UI or GitOps 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 GitOps approach.)

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.

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

1. In Cortex, navigate to Settings > GitOps.
2. Scroll down to the "Options by entity type" tile.

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

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

5. 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 GitOps, you can define any number of entities in any repository.

• 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

Read more in Using GitOps for Cortex.

Unique identifiers for entities

Entity tag

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 Slack Bot.

The entity tag must be globally unique across all entities.

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 archive or delete the entity then create a new entity with the desired tag.

Cortex ID

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 Slack Bot. The ID is automatically generated by Cortex and it is 18 characters in length.

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

The CID is in the URL and the entity details page.

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

Adding entities to catalogs

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 create a custom catalog, you can set the entity type criteria.

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.

  • By default, any custom entity types 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.

Managing all entities across catalogs

The All entities page 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.

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:

Use the search and filter options in the upper right side of the 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 Display to choose whether to show archived entities in the list, and select which columns to display alongside entities. Learn more about the performance indicator columns below.
• 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:

• Incidents: Displays how many active incidents are associated with a given entity. This information is pulled from FireHydrant, incident.io, PagerDuty, and Rootly.
• 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.

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

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

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

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

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

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.

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

To learn more, see Defining relationship types.

Archive entities

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 auto-archival of entities 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 Archiving entities.

Understanding the entity types

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

• Add services
• Add domains
• Add teams
• Add custom entity types

Adjusting general settings for entities

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