External Documentation

Cortex is your source of truth to external documentation - instead of digging through your wikis, you can aggregate links and API documentation into one easily accessible place.

Documentation is easily accessible through the Catalog, on the homepage for each entity.

Links

You can easily add links to docs, runbooks, tech specs, dashboards, and more.

The Catalog Descriptors a list of Link objects:

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

The value of type can be anything you want – examples include:

• runbook
• documentation
• logs
• dashboard
• metrics
• healthcheck

tip

You can look up links easily using our Slackbot!

API Documentation

API documentation is a special case. Cortex supports displaying Swagger/OpenAPI/AsyncAPI specs for each entity, in the "API Explorer" tab. There are a few ways of adding API specs to Cortex

Swagger/OpenAPI Documentation

Catalog Descriptor

You can use your Catalog Descriptor file as an OpenAPI spec file. Since the Catalog Descriptor file extends the OpenAPI spec, you can simply implement the spec directly in this file.

Existing Specs

If you have existing or external specs you want to display in the API explorer (e.g. from Swagger Hub, GitHub Raw URL, etc), simply add a URL to the spec file (JSON or YAML) as an x-cortex-link, with type openapi. The spec will then automatically show up in the API Explorer.

Relative links

If you have specs checked into your Git repository, you can embed it by adding it as a relative URL with type openapi, like:

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

Upload via API

If you know your Entity Tag, you can also send your OpenAPI JSON or YAML file to our public endpoint for managing OpenAPI documentation /api/v1/catalog/{tag}/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.

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 Documentation

Existing Specs

If you have existing or external specs you want to display in the API explorer (e.g. from GitHub Raw URL, etc), simply add a URL to the spec file (JSON or YAML) as an x-cortex-link, with type async_api. The spec will then automatically show up in the API Explorer.

Relative links

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

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

Git-Driven Markdown Docs

Cortex automatically embeds markdown files from the docs folder of your repo in the Catalog. These docs show up under the "Docs" tab.

Embed Dashboards

Cortex supports embedding charts directly into the Catalog for quick access, making the Catalog a single pane of glass for your architecture.

x-cortex-dashboards:
  embeds:
    - type: datadog | grafana | newrelic (optional)
      url: https://blahblah.com

The type field is an optional enum of three types. The type field is used when generating screenshots for certain Slack integration points. If you do not plan to use this feature feel, leave the type field blank and only add the url, as it's ignored entirely when embedding in the catalog.

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

tip

Note that you can only embed charts, not dashboards. Your tool of choice likely has an option for generating embed URLs for individual charts, which is what you'd want to use here.

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