Managing Entities
Last updated
Last updated
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.
You can create your own entity types or use one of the 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 out of the box.
In addition, you can create custom entity types to fit your organization's needs. Learn more in Add custom entity types.
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.
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.
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:
In Cortex, navigate to Settings > GitOps.
Scroll down to the "Options by entity type" tile.
To only allow editing of entities via GitOps, toggle off the setting next to Enable UI editing for new entity types.
To only allow creation of entities via GitOps, toggle off the setting next to Enable UI importing for new entities.
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:
Read more in Using GitOps for Cortex.
Entity tag
The entity tag - the value of x-cortex-tag in an entity's YAML file - is a 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. It is possible to customize the entity 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 does not appear in an entity's YAML file, as it cannot be modified.
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.
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.
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 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 AWS account ID or region, domain, entity type, group, team, or user.
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, 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.
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.”
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 adding each type of entity, see their documentation pages:
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.
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.
