1. Catalog customization

Overview

A catalog is a defined selection of entities. You can use catalogs to track and store information about all of the components that make up your infrastructure. This includes everything from services and domains to AWS S3 buckets and RDS, Google Cloud resources, or Azure Resources.

Catalogs themselves are not defined by a YAML file and must be created in the Cortex UI. Think of catalogs as a folder containing a collection of entities, with each entity defined by its own YAML file. An entity can belong to multiple catalogs, so you can also think of a catalog as a filter that defines which entity types to group together.

To customize your Cortex instance to your organization's needs, you can define custom catalogs in Cortex to represent your infrastructure. For each catalog, you set the criteria that determines which entities belong to that catalog. In addition, you can define custom entity types to categorize the entities that live in your catalogs.

View catalogs

Click Catalogs from the main nav to view your list of catalogs. You must have the View catalogs permission.

Default catalogs

Regardless of how your catalogs are customized, all Cortex users will have a few common catalogs. These catalogs appear by default when you begin using Cortex:

• Services
  • Services is a catalog that contains all service entities, such as microservices, libraries, and components. Learn more about services in the Entities documentation.
• Infrastructure
  • Infrastructure is a catalog that represents your infrastructure assets, such as Kafka topics, databases, and storage.
• Teams
  • Teams is a catalog that contains all team entities. It serves as both a method for representing your organization in the platform, and as a way to track owners for different entities in the catalogs. Learn more in the Teams documentation.
• Domains
  • Domains is a catalog that allows you to group your services, resources, and other domains into hierarchical, logical units. Learn more about domains in the Entities documentation

Manage entities across all 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

Use the search bar to find specific entities. You can also use the Sort by function to sort the entire list by identifier or use the Filter by function to narrow the list down by types, domains, groups, teams, and users.

Key performance indicators listed for all entities

The All entities page displays some key performance indicators:

• Active incidents: Displays how many active incidents are associated with a given entity. This information is pulled from PagerDuty.
• 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.”

Default entity types

The "All entities" page is also where you can manage entity types, which determine the types entities you’ll import into Cortex.

Cortex comes with built-in entity types to get you started quickly. These entity types do not have a definition schema, and instead fetch details on demand from the original source. You can also create your own entity types.

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

Create entity types

When creating an entity type, keep in mind that these will ultimately dictate how you import specific entities later on.

To create, edit, and delete entity types, you must have the Edit entity types permission.

To create a new entity type:

1. In Cortex, navigate to Catalogs > All entities.
2. Click the Entity types tab, then click Create entity type.
   
3. Configure the "Create entity type" form:
   • Name: Enter a human-readable name that will appear in the catalog for this entity type.
   • Type: Enter a unique identifier that corresponds to the entity type. This will be used to specify the type defined in the YAML definitions for imported entities.
   • Description: Optionally, enter a description for the entity type.
   • Display icon: Select an icon to appear alongside the entity type throughout the app.
   • Schema: Define a JSON schema that will be used to validate the x-cortex-validation block of a given entity’s YAML.
     • This is not required to create an entity type, but will be useful if you want to enforce certain attributes about entities, such as a region or version number. Attributes defined in the schema will be required when creating an entity of that type, which can then be validated in Scorecards.
       
     • In the example screen shot, we’ve created a custom entity called Employee — this is what we’ll use to represent individuals at our organization. In the schema section, you can see that each profile is required to include an employee’s location and their dream vacation. This means every time you create an Employee entity, you’ll define each employee’s location and dream vacation in a schema for that entity.
4. At the bottom of the page, click Save.

After saving, the entity type will appear in the Entity types tab under Catalogs > All entities, and you will be able to import entities of that type.

If you want entities of the new entity type to automatically belong to a specific catalog, you can configure the catalog's defined entity types while creating a new catalog or you can edit an existing catalog to update the entity types.

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.

Manage all catalogs

On the All catalogs page, you’ll find all pre-defined and custom catalogs in Cortex.

This page will reflect the same list of catalogs you find in the Catalogs dropdown menu in the main nav.

Just like "All entities", "All catalogs" includes a search bar and a sort function, as well as a toggle for displaying or hiding Drafts.

From this page, you can create new catalogs and edit existing ones.

Create catalogs

You can create catalogs in the Cortex UI. Because catalogs are not defined by a YAML file, it is not possible to create them via a GitOps workflow.

To create, edit, and delete catalogs, you must have the Edit catalogs permission.

To create a new catalog:

1. At the top of the "All catalogs" page, click Create catalog.
2. Configure the "Create catalog" form:
   • Name: Enter a name for the catalog.
   • Description: Optionally, enter a description of the catalog.
   • Display icon: an icon to appear alongside the catalog throughout the app.
   • URL: Enter a unique URL slug.
     • By default, the URL slug will be generated based on the catalog’s name, but you can use the URL field to create a custom slug.
   • Add entity types: In this section, you will define the entities that are included in your catalog. All entities that match the criteria defined in this section will be automatically included in the catalog. To create a catalog, you need to add at least one entity type. Catalogs can include a combination of any entity types, or can include just one type.
     • Selection type: Choose whether to include or exclude the entity types you select.
     • Entity types: Select from the entity types you've created.
     • Include or Exclude groups: Choose groups to include or exclude.
     • CQL expression: Optionally, enter a specific CQL expression to fine-tune your catalog based on specific criteria.
   • Draft: Choose whether to save the catalog as a draft or publish it. Only admins and managers have the ability to view drafts.
3. Click Save catalog.

Once the catalog is created, you’ll find it under Catalogs > All catalogs, automatically populated with all entities that apply based on the entity types you've created.

Edit catalogs

To edit a catalog:

1. In Cortex, go to Catalogs > All catalogs. Click into the catalog you want to edit, then click Edit catalog at the top of the page.
   • This will bring you back to the catalog creation page, with all the details from your last save.
2. Make any changes necessary to the catalog.
3. At the bottom of the page, click Save catalog.

Track catalog changes

You can use the Audit log to track changes made to any of your catalogs. Catalog updates will be listed as CATALOG in the Type column, and the updated catalog will be listed under the Entity column.

The Action column will indicate whether a catalog was created, deleted, or updated.

Configure catalog display

You must have the Configure appearance settings permission to configure the catalog display.

By default, catalogs will appear in alphabetical order, but you can manually adjust the order that the catalogs appear in the main nav.

In the upper right corner of the "All catalogs" page, click Configure catalog display to go directly to Catalog menu nav settings, where you can adjust the order of the catalogs list. You can drag catalogs to reorder them, and you can see a preview of how the list will appear in the dropdown.