# Adding services
Services are a default entity type in Cortex used to represent the codebase-like modules that make up your software ecosystem—microservices, libraries, components, etc. All entity types in Cortex, including services, are defined by a `cortex.yaml` file, which declares the entity's identity, ownership, dependencies, and links to the tools that support it (CI/CD, observability, on-call, documentation, and more). Once defined, a service becomes a first-class entity in your catalog, automatically enriched with live data pulled from your integrations.
Services are typically the most numerous entity type in a catalog and the closest match to how engineering teams already think about their work: as discrete units of code that do something specific, owned by someone, deployed somewhere, and depended on by other things. Modeling them consistently gives your organization a single place to answer questions that otherwise require digging through multiple tools—who owns this, what it depends on, whether it meets your standards, and where it runs. The result is a shared understanding that connects day-to-day engineering work to broader goals around quality, ownership, and operational maturity.
## Adding service entities to Cortex
Users with the `Edit Catalog` and `Edit Services` permissions can add service entities to Cortex.
Services can be added manually, imported, defined in YAML via GitOps, or created via the API.
### Importing services from an integration
1. From the main sidebar, expand **Catalogs**, then select **All entities**.
2. In the upper-right corner, click **Import entities**.
3. Select **Import discovered entities**.
4. Select the integration to import from.\
The **Select entities to import** page is displayed.
5. A list of entities from the integration are displayed. Select the checkboxes next to the entities you want to import. If you have a large volume of entities, click the **Filter icon** in the upper-right corner of the results list to select and apply entity type filters.
6. In the bottom-right corner, click **Next step**.\
The **Edit details** page is displayed.
7. Configure the following options. The options shown are filtered at runtime based on the `entityType` (e.g. 'Members' is team-only, 'Dependencies' excludes domains/teams) and whether the required integrations are enabled (e.g. 'Communications' requires Slack, 'On-call' requires Opsgenie/PagerDuty, etc.).
1. From the **Type** drop-down menu, select **Service.**
2. In the **Details** section**:**
1. Below **Entity name**, enter a name for the entity (required).
2. The **Cortex tag** field is auto-populated based on the name of the entity (required). Its a unique identifier for the entity. This is also known as the `x-cortex-tag`.
3. Below **Description**, enter a description of the entity to help others understand its purpose.
4. From the **Groups** drop-down menu**,** select a group or groups [to segment the entity](/ingesting-data-into-cortex/entities-overview/entities/groups.md).
3. In the **Repository** section:
1. From the **Provider** drop-down menu, select the repo provider.
2. From the **Alias** drop-down menu, select the alias of the connected provider account that has access to the repository.
3. From the **Repository** drop-down menu, select the repo associated with the entity. If you don't see it listed, click **Refresh repositories** to pull in the latest list.
4. Below **Basepath**, enter the subdirectory within the repo where the entity's code lives. Leave blank if the entity occupies the entire repo.
4. In the **Owners** section, define [ownership](/ingesting-data-into-cortex/entities-overview/entities/ownership.md) for the entity. Ownership can be assigned to either teams or individual users. It's recommended to select team owners to keep the ownership information up to date through any future personnel changes. To add a team or teams, click **Add** in the **Teams** area. To add an individual user or users, click **Add** in the **Users** area.
* Cortex may recommend owners [based on repository activity](/ingesting-data-into-cortex/entities-overview/entities/ownership.md#recommendation). You can accept or reject the recommendations.
5. In the **Links** section, click **Add** to add links to external documentation, such as runbooks, docs, logs, or custom categories.
6. In the **Slack channels** section, click **Add** to link a Slack channel to the entity. If enabled, you'll receive notifications about the entity in the selected Slack channel.
7. In the **Parents** section, select a parent domain or domains from the drop-down menu. This is where you configure the hierarchy for your entity, which can be visualized in the [relationship graph](/ingesting-data-into-cortex/entities-overview/entities/relationship-graph.md).
8. In the **Dependencies** section, click **Add entity** to select an entity or entities that this entity depends on. These can be visualized in the [relationship graph](/ingesting-data-into-cortex/entities-overview/entities/relationship-graph.md).
8. If you selected more than one entity, click **Next entity** in the bottom-right corner of the page.
9. Click **Confirm import**.\
The entity is imported into Cortex.
### Manually adding services
1. From the main sidebar, expand **Catalogs**, then select **All entities**.
2. In the upper-right corner, click **Import entities**.
3. Select **Create entities manually**. \
The **Edit details** page is displayed.
4. Configure the following options. The options shown are filtered at runtime based on the `entityType` (e.g. 'Members' is team-only, 'Dependencies' excludes domains/teams) and whether the required integrations are enabled (e.g. 'Communications' requires Slack, 'On-call' requires Opsgenie/PagerDuty, etc.).
1. From the **Type** drop-down menu, select **Service.**
2. **In the Details section:**
1. Below **Entity name**, enter a name for the entity (required).
2. The **Cortex tag** field is auto-populated based on the name of the entity (required). Its a unique identifier for the entity. This is also known as the `x-cortex-tag`.
3. Below **Description**, enter a description of the entity to help others understand its purpose.
4. From the **Groups** drop-down menu**,** select a group or groups [to segment the entity](/ingesting-data-into-cortex/entities-overview/entities/groups.md).
3. In the **Repository** section:
1. From the **Provider** drop-down menu, select the repo provider.
2. From the **Alias** drop-down menu, select the alias of the connected provider account that has access to the repository.
3. From the **Repository** drop-down menu, select the repo associated with the entity. If you don't see it listed, click **Refresh repositories** to pull in the latest list.
4. Below **Basepath**, enter the subdirectory within the repo where the entity's code lives. Leave blank if the entity occupies the entire repo.
4. In the **Owners** section, define [ownership](/ingesting-data-into-cortex/entities-overview/entities/ownership.md) for the entity. Ownership can be assigned to either teams or individual users. It's recommended to select team owners to keep the ownership information up to date through any future personnel changes. To add a team or teams, click **Add** in the **Teams** area. To add an individual user or users, click **Add** in the **Users** area.
* Cortex may recommend owners [based on repository activity](/ingesting-data-into-cortex/entities-overview/entities/ownership.md#recommendation). You can accept or reject the recommendations.
5. In the **Links** section, click **Add** to add links to external documentation, such as runbooks, docs, logs, or custom categories.
6. In the **Slack channels** section, click **Add** to link a Slack channel to the entity. If enabled, you'll receive notifications about the entity in the selected Slack channel.
7. In the **Parents** section, select a parent domain or domains from the drop-down menu. This is where you configure the hierarchy for your entity, which can be visualized in the [relationship graph](/ingesting-data-into-cortex/entities-overview/entities/relationship-graph.md).
8. In the **Dependencies** section, click **Add entity** to select an entity or entities that this entity depends on. These can be visualized in the [relationship graph](/ingesting-data-into-cortex/entities-overview/entities/relationship-graph.md).
5. Optionally, if you'd like to add another entity, click **Add entity** in the upper-right corner of the page.
6. Click **Confirm import**.\
The entity is imported into Cortex. If there are any errors, a banner appears at the bottom of the page with the errors that need to be fixed.
### Adding a service in YAML via GitOps
**Service entity descriptor**
A barebones spec file has the OpenAPI version, along with an `info` section that contains some basic details.
```yaml
openapi: 3.0.1
info:
title: Account Service
description: Brief summary of what this service does and who depends on it.
x-cortex-tag: account-service
x-cortex-type: service
```
**Required fields**
The following fields are required under `info`: `title`, `x-cortex-tag`, and `x-cortex-type`. The description is optional, but highly recommended as a best practice.
Expand to see the example YAML
```yaml
openapi: 3.0.1
info:
title: Chat Service
description: Chat service is responsible for handling the chat feature.
x-cortex-tag: chat-service
x-cortex-type: service
x-cortex-parents: # parents can be of type domain only
- tag: notifications-domain
- tag: support-domain
x-cortex-groups:
- python
x-cortex-owners:
- type: group
name: Delta
provider: OKTA
description: Delta Team
x-cortex-slack:
channels:
- name: delta-team
notificationsEnabled: true
description: This is a description for the delta-team Slack channel # optional
x-cortex-link:
- name: Chat ServiceAPI Spec
type: OPENAPI
url: ./docs/chat-service-openapi-spec.yaml
x-cortex-custom-metadata:
core-service: true
x-cortex-dependency:
- tag: authentication-service
- tag: chat-database
x-cortex-git:
github:
repository: org/chat-service
x-cortex-oncall:
pagerduty:
id: ASDF1234
type: SCHEDULE
x-cortex-apm:
datadog:
monitors:
- 12345
x-cortex-issues:
jira:
projects:
- CS
```
### Adding a service via the Cortex API
You can create, update, and delete services using the Cortex API. See [Catalog entities](/api/readme/catalog-entities.md) for more information.
## Viewing services
The **Services** page lists every service entity that's been imported into Cortex. To open it, expand **Catalogs** in the main sidebar and select **Services**. The page opens to the **Mine** tab if you own any services, and defaults to the **All** tab otherwise. Each row shows the service's name and tag.
### Searching across and filtering services
There are several ways to search and filter your services list.
1. From the main sidebar, expand **Catalogs**, then select **Services.**
2. Do one of the following:
* Select the **All** tab to search and filter across all of your organization's services.
* Select the **Mine** tab to search and filter only the services you own.
3. Do any or all of the following:
* To find specific services, use the search bar in the upper-right corner of the services list and type to search.
* Click **Name** to select whether you want to sort by name or identifier, and whether to sort by ascending or descending order.
* Click **Display** to choose whether to show archived services in the list, and select which columns to display alongside services.
* Click into a row to learn more about:
* **Incidents** - Displays how many active incidents are associated with a given service. This information is pulled from FireHydrant, incident.io, PagerDuty, and Rootly.
* **Health** - When you click into this column in an service's row, you can view more information about:
* **Monitors** - Shows how services are performing against monitors you’ve created in your APM. When a service is passing all monitors, this cell will display `All OK`; otherwise, it displays `Failing`, `Warning`, or `No Data`, along with how many monitors the service 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.
* Columns that rely on an integration display **Not connected** when the integration hasn't been set up. If the integration is connected but the entity has no associated data or configuration, the cell displays **None** instead.
* Click **Filter** to narrow down your list by by domain, entity type, group, owner, or team.
## Editing a service entity
Users with the `Edit Catalog` and `Edit Services` permissions can edit service entities.
Service entities can be modified at any time. Follow the steps below to edit a service entity.
1. Navigate to the entity's page.
2. In the upper-right corner, click **Configure entity**.\
The entity details page opens.
3. In the upper-right corner, select either **UI editor** or **YAML editor**.
4. Make your changes. Note that the Cortex tag is uneditable.
5. Click **Save changes**.\
The service entity is updated.
{% hint style="info" %}
It's possible to change the entity type via the Cortex YAML. See [Changing an entity's type](/ingesting-data-into-cortex/entities-overview/entities.md#changing-an-entitys-type) for more information.
{% endhint %}
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/adding-entities/add-services.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.