LogoLogo
Login to CortexBook a DemoCortex Academycortex.io
  • Cortex Docs
  • Cortex Quick Start
  • Ingesting data into Cortex
    • Managing Entities
      • Adding entities
        • Add services
        • Add domains
        • Add teams
        • Add custom entity types
        • Defining dependencies
      • Entity details page
      • Defining ownership
      • Defining relationship types
      • Grouping entities
      • Adding external documentation
      • Adding Deploy data
      • Adding custom data
      • Viewing discovered entities
      • Archiving entities
      • Relationship graph
      • Using On-call Assistant for incidents
      • Managing Terraform infra in Cortex
    • Managing Catalogs
    • Integrations
      • Internally hosted integrations
      • ArgoCD
      • AWS
      • Azure DevOps
      • Azure Resources
      • BambooHR
      • Bitbucket
      • BugSnag
      • Buildkite
      • Checkmarx
      • CircleCI
      • ClickUp
      • Codecov
      • Coralogix
      • Custom webhook integrations
      • Datadog
      • Dynatrace
      • Entra ID (Azure AD)
      • FireHydrant
      • GitHub
      • GitLab
      • Google
      • Grafana
      • incident.io
      • Instana
      • Jenkins
      • Jira
      • Kubernetes
      • LaunchDarkly
      • Lightstep
      • Mend
      • Microsoft Teams
      • New Relic
      • Okta
      • Opsgenie
      • PagerDuty
      • Prometheus
      • Rollbar
      • Rootly
      • Sentry
      • ServiceNow
      • Slack
      • Snyk
      • SonarQube
      • Splunk Observability Cloud (SignalFx)
      • Splunk On-Call (VictorOps)
      • Sumo Logic
      • Veracode
      • Wiz
      • Workday
      • xMatters
  • Scorecards
    • Initiatives and Action items
      • Creating issues based on Initiatives
    • Scorecard rule exemptions
    • Scorecard rule filters
    • Scorecard examples
    • Scorecards as code
  • Reports
    • Executive report
    • All Scorecards report
    • Bird's eye report
    • Progress report
    • Report card
  • Eng Intelligence
    • Custom Metrics
    • Jira Metrics
    • Metrics Explorer (Beta)
  • Cortex Query Language (CQL)
    • Using CQL reports
    • Using JQ in Cortex
  • Workflows
    • Creating a Workflow
      • Workflows as code
    • Blocks
    • Running a Workflow
    • Registering a Scaffolder template
      • Scaffolder advanced usage
    • Using a Workflow to sync in ArgoCD
    • Kicking off a Jenkins pipeline in a Workflow
    • Calling internal service endpoints in a Workflow
  • Plugins
    • Creating a plugin
      • Creating a plugin proxy
    • Migrating Backstage plugins to Cortex
  • Engineering homepage
  • Workspace Settings
    • Using GitOps for Cortex
      • GitOps logs
    • Managing users
      • Roles and permissions
        • Custom roles
        • Team ownership entity editing
      • Configuring SSO
        • Microsoft Entra ID
        • Google
        • Other OIDC providers
        • Okta
          • Okta SCIM
      • Configuring identity mappings
      • Onboarding management
    • API keys, secrets, and tokens
      • Secrets
      • Personal tokens
    • Audit logs
    • Entity settings
      • Data verification
      • Auto archiving entities
    • IP allowlist
    • Notifications
      • Notification logs
    • Customizing your workspace
    • Using search in Cortex
  • Cortex API
    • REST API operations
      • API Keys
      • Audit Logs
      • Catalog Entities
      • Custom Data
        • Custom Data (Advanced)
      • Custom Events
      • Custom Metrics
      • Dependencies
      • Deploys
      • Discovery Audit
      • Docs
      • Eng Intel: User Labels
      • Entity Relationship Types (Beta)
      • Entity Relationships (Beta)
      • Entity Types
      • GitOps Logs
      • Groups
      • Initiatives
      • Integrations APIs
        • Azure Active Directory (Entra ID) API
        • Azure Resources API
        • AWS API
        • Azure DevOps API
        • CircleCI API
        • Coralogix API
        • Datadog API
        • GitHub API
        • GitLab API
        • incident.io API
        • LaunchDarkly API
        • New Relic API
        • PagerDuty API
        • Prometheus API
        • SonarQube API
      • IP Allowlist
      • Notification Logs
      • On call
      • Packages
      • Plugins
      • Queries
      • SCIM
      • Scorecards
      • Secrets
      • Team Hierarchies
      • Teams
      • Workflows
Powered by GitBook
On this page
  • View links on an entity
  • Add links to an entity
  • Git-driven markdown docs
  • Documentation types
  • OpenAPI docs
  • AsyncAPI docs
  • Embedded dashboards
  • Accessing docs links via Slack

Was this helpful?

Export as PDF
  1. Ingesting data into Cortex
  2. Managing Entities

Adding external documentation

Last updated 26 days ago

Was this helpful?

Cortex is your source of truth to external docs. Instead of digging through wikis and other resources, you can aggregate docs on the relevant entities in Cortex in the following ways:

If you have configured the , you can use Slack Bot commands to .

View links on an entity

Links appear on an entity details page in the Links & docs section:

Add links to an entity

On entities, you can add links to docs, runbooks, tech specs, dashboards, and more.

  1. In Cortex, navigate to an entity.

  2. In the upper right corner of the entity details page, click Configure entity.

  3. Click the Links tab.

  4. Click +Add.

  5. Configure the link:

      • To create a new type, enter the type name then click the name in the dropdown.

    • Name: Enter a name for the link.

    • URL: Enter the URL.

    • Description: Add a description of the link.

  6. Click Add.

In the entity descriptor, add a list of link objects:

x-cortex-link:
  - name: Human Readable Name
    type: runbook
    url: https://cortex.io
    description: Optional Description

name, type, and url are required.

Git-driven markdown docs

Cortex automatically embeds markdown files from the docs folder of your repo or from the root directory. If Cortex detects relevant files, these docs show up under the Links & docs page in an entity's sidebar.

Documentation types

OpenAPI docs

Embed specs from a git repository

If you have specs checked into your git repository, you can embed it by adding it as a relative URL with type openapi. For example:

x-cortex-link:
  - name: My Spec
    type: OPENAPI
    url: ./docs/my-openapi-spec.yaml

Relative links in another repo

In addition to providing the ability to link to specs within the service repo, Cortex also allows for links that reference other git repositories that aren't necessarily associated with your entity but still within your organization.

Power users can also specify a branch parameter between the second and the third colon separated group, in the form github:org/repo:branch:path/to/file. If this parameter is omitted, we will use the repository's default branch.

Relative link YAML examples
x-cortex-link:
  - name: My GitHub Spec
    type: OPENAPI
    url: github:org/repo:path/to/file
x-cortex-link:
  - name: My GitLab Spec
    type: OPENAPI
    url: gitlab:namespace/project:path/to/file
x-cortex-link:
  - name: My Azure DevOps Spec
    type: OPENAPI
    url: azuredevops:project/repository:path/to/file
x-cortex-link:
  - name: My Bitbucket Spec
    type: OPENAPI
    url: bitbucket:workspace/repo:path/to/file

Adding OpenAPI via the Cortex API

The request body is the following, in JSON format. See API Docs for authentication details.

Field
Type
Description

spec

string

The json or yaml as a string

Converting YAML or JSON to string You can use a lightweight utility like jq to take your yaml/json and generate a string that can be used for your request:

e.g. $(cat my_file.yaml | jq -Rsa)

AsyncAPI docs

If you have specs checked into your Git repository, you can embed it by adding it as a relative URL with type async_api. For example:

x-cortex-link:
  - name: My Spec
    type: ASYNC_API
    url: ./docs/my-spec.yml

Embedded dashboards

x-cortex-dashboards:
  embeds:
    - type: datadog | grafana | newrelic (optional)
      url: https://example.com
  • The type field is an optional enum of three types: datadog, grafana, or newrelic.

  • The url field is the src value for the iframe embed generated by your dashboard tool.

    • You must use your tool's embed URL for individual charts.

Note that you can embed individual charts, not dashboards.

Embed content from other sources

It is possible to display content from a source other than Datadog, Grafana, or New Relic. To do this, do not specify an option for the type field. The URL you add must be publicly accessible or provide cross-platform authentication for Cortex to view and display the iframe. For example, if the content is accessible via VPN, then you should be able to view it in Cortex while on the VPN.

Accessing docs links via Slack

  • /slack links <tag-or-id> to list all documentation links for an entity

  • /slack links [type] <tag-or-id> to list specific types of documentation links for an entity

For example:

  • To list all documentation links for an entity with ID en29f044598b112345, you could run the following command in Slack: /cortex links en29f044598b112345

  • To list the OpenAPI specs for an entity with tag plugin-extension, you could run the following command in Slack: /cortex links openapi plugin-extension

Before editing an entity via the UI, make sure that UI editing is enabled under .

Type: Select the .

Learn more about , , and types below.

The value of type can be defined based on your organization's preferences. Common examples include dashboard, documentation, healthcheck, logs, metrics, and runbook. See the sections below on this page describing , , and .

You can quickly look up links using the .

Cortex uses the for rendering the documents.

When , Cortex supports embedding OpenAPI or AsyncAPI specs, embedding specs from your repository, adding relative links to a repository that isn't associated with the entity, and embedding charts (from Datadog, Grafana, New Relic, or other sources). You can also create a custom type while .

Cortex supports displaying Swagger/OpenAPI or AsyncAPI specs for each entity in the API explorer on an . You can also authorize your API and run queries directly in the API explorer.

You can use your file as an OpenAPI spec file. As mentioned in the , the entity descriptor file extends the OpenAPI spec, so you can implement the spec directly in this file.

You may have existing or external specs you want to display in the API explorer from sources such as Swagger Hub or GitHub Raw URL. Add these to the JSON or YAML spec file under the block, with the type openapi.

Using your , you can also send your OpenAPI JSON or YAML file to the public /api/v1/catalog/documentation/openapi for each of your entities. One API doc per entity can be uploaded and it will automatically show up as an API Doc entry in the dropdown in the API explorer.

You may have existing or external specs you want to display in the API explorer from sources such as Swagger Hub or GitHub Raw URL. Add these to the JSON or YAML spec file under the block, with the type async_api.

Cortex supports embedding charts from , , or directly into an entity for quick access. To view embedded charts, click the Dashboard page in the .

If you're using Grafana and seeing errors in your Grafana embeds, make sure your Grafana instance .

If you have configured the , you can use commands to list documentation directly in Slack:

The type corresponds to the type of documentation (e.g., openapi, documentation, etc.). Replace <tag-or-id> with the .

The Slack Bot links command works for any docs links listed under x-cortex-links. Note that it does not list the listed under x-cortex-dashboards.

Settings > GitOps
React markdown library
entity details page
has embeds enabled
type of link
OpenAPI
AsyncAPI
dashboard chart
OpenAPI
AsyncAPI
dashboard charts
Cortex Slack Bot
adding links to an entity
adding a link
x-cortex-link
x-cortex-link
charts
Slack integration
Adding links to an entity
Displaying Swagger, OpenAPI, or AsyncAPI specs on an entity
Embedding git-driven markdown
Embedding dashboard charts
list an entity's docs links directly in Slack
documentation on entities
Datadog
Grafana
New Relic
Slack integration
endpoint for managing OpenAPI documentation
entity descriptor
entity tag
entity's tag or ID
Slack Bot
Click "Links & docs" on the left side of an entity page.
entity's sidebar