1. Catalog customization

Catalogs are the backbone of the Cortex platform — here, you can 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. You can even define custom types of entities in Cortex to accurately represent your infra.

You can create simple catalogs to group services, domains, and other entities, or you can create more complex catalogs with all kinds of entities.

You can access Catalogs from the main nav.

Regardless of how your catalogs are customized, all Cortex users will have a few common catalogs: All entities, All catalogs, and Teams. These will be the first catalogs available when you begin using Cortex.

All entities

The All entities page lists all of the entities that you have imported into Cortex, across all types. This catalog 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 into this catalog, 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 in this catalog.

To navigate the catalog, you can use the search bar to find specific entities, or use the sort and filter tools to refine the view.

You can 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. When text is entered in the search input, you can also sort by relevance.

The All entities page will also display some key performance indicators:

• Active incidents: Displays how many active incidents are associated with a given entity. This information comes from PagerDuty or Incident.io.
• 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 prespecified window. These data are pulled from New Relic.
• Apdex (Application Performance Index): Ratio of the number of satisfied and tolerating requests to the total number requests made. This data are also 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.”

The All entities catalog is also where you can manage entity types, which determine all the kinds of entities you’ll import into Cortex.

Cortex comes with a suite of 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.

The built-in entity types include:

• AWS ECS Service
• AWS ElastiCache for Redis
• AWS Kafka
• AWS MemoryDB for Redis
• Domain
• DynamoDB Table
• Elastic Load Balancer
• Google Cloud Functions
• Google Cloud HTTP(S) Load Balancing
• Google Cloud Pub/Sub Topics
• Google Cloud SQL
• Google Cloud Storage
• Lambda
• RDS
• S3
• Service
• Team

Creating entity types

In addition to these built-in entity types, you can create your own entity types. To create a new entity type, select Create entity type next to the search bar from the Entity types page.

You have full power over how you create and define an entity type — just keep in mind that these will ultimately dictate how you import specific entities later on.

You’ll first be prompted to enter a Name for the type; this is the human-readable name that will appear in the catalog. Under Type, input 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.

Next, you can enter an optional Description for the entity type. This is a good space to describe the entity type and elaborate on how it is used.

Finally, select an icon that matches the entity type you’re creating.

In the Schema section, you can 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 this example, 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.

Select Save to complete the creation flow. You can then find the entity type you created in the Entity types tab of the All entities catalog.

Once an entity type is created, you can import entities of that type.

All catalogs

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

Like entity types, Cortex has a suite of pre-defined catalogs:

• Domains
• Infrastructure
• Services
• Teams

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.

Creating catalogs

To create a new catalog, select Create catalog at the top of the page.

Just like with creating entity types, you’ll first be prompted to add a Name, Description, and Icon for the new catalog.

Each catalog has a unique URL. By default, the URL slug will be generated based off of the catalog’s Name, but you can use the URL field to create a custom slug.

The Add entity types is where you’ll define the entities that are included in your 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 determines whether you’re Including or Excluding the entity types selected in the dropdown below.

Under the Entity types dropdown, you can select from all the entity types you’ve created in the All entities catalog.

The Advanced options give you the ability to refine your catalog even further. You can choose to Include groups and Exclude groups, or leave both fields blank for the catalog to apply to all groups. You can define groups during the entity import stage.

Under CQL expression, you can enter specific expressions to fine-tune your catalog based on specific criteria. We recommend creating a few straightforward catalogs at first and getting more comfortable with Cortex before adding CQL expressions.

Before selecting Save, you can decide whether to save the catalog as a draft, or publish it. Only admins and managers have the ability to view drafts.

Once the catalog is created, you’ll find it under All catalogs populated with all entities that apply based on the entity types you created earlier. The catalog will also appear in the dropdown under Catalogs.

In this example, we’ve added entities to the built-in Services catalog. Just like with the All entities page, each catalog will show active incidents, monitors, error rate, and Apdex.

Note

All entities that meet the criteria you defined in the Add entity types section will automatically appear in the catalog.

Edit catalogs

To edit a catalog, navigate to the specific catalog and select 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.

You can change anything about the catalog at any point, from name to entity types.

Tracking 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

By default, catalogs will appear in alphabetical order, but you can manually adjust the order of the catalogs in the dropdown menu and the All catalogs list. Select Configure catalog display to go directly to Catalog menu nav settings.

tip

You can edit the catalog menu nav from the Appearance page in the Workspace section of settings.

You can drag catalogs to reorder them, and you can see a preview of how the list will appear in the dropdown.

The ability to configure catalog display is a specific permission that can be granted to users (Configure appearance).

Teams

The Teams page 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. Teams offers a centralized place to gather the most important information about each group, making it easier for everyone to find what they need.

Because ownership is a crucial part of Cortex, all users have a Teams catalog. We’ll cover Teams more extensively in a later article, but for now, know that this is where you can create and manage teams.