If you’re new to Datadog, you can add components to Software Catalog by:

• Manually creating service definitions through the Datadog app, the Datadog API, Terraform, or a GitHub integration.
• Importing existing services from sources like ServiceNow or Backstage.

By default, these services are not associated with Datadog telemetry, but you can link telemetries from Datadog or external sources manually using entity definition YAML files.

Build your first Software Catalog

Create service definitions for each component you want to add to your Software Catalog.

Create service definitions through code

To create a service definition using the Datadog Service Definition API, Terraform, or a GitHub integration:

1. Create or find service.datadog.yaml or entity.datadog.yaml (Datadog accepts both file names).

2. Name your component in the dd-service (schema version v2.2 or prior) or name (schema version v3.0+) field.

   For example:

   service.datadog.yaml

   Copy

       schema-version: v2.2
       dd-service: my-unmonitored-cron-job
       team: e-commerce
       lifecycle: production
       application: shopping-app
       description: important cron job for shopist backend
       tier: "2"
       type: web
       contacts:
       - type: slack
       contact: https://datadogincidents.slack.com/archives/XXXXX
       links:
       - name: Common Operations
       type: runbook
       url: https://datadoghq.atlassian.net/wiki/
       - name: Disabling Deployments
       type: runbook
       url: https://datadoghq.atlassian.net/wiki/
       tags: []
       integrations:
       pagerduty:
       service-url: https://datadog.pagerduty.com/service-directory/XXXXXXX
       External Resources (Optional)
      

3. (Optional) Register multiple services in one YAML file by separating each definition with three dashes (---).

4. Import your service(s) through one of the following:

   • The Datadog API
   • Terraform
   • Datadog’s GitHub integration

Create service definitions in-app

Alternatively, create service definitions in the Datadog app:

1. Navigate to the Software Catalog Setup & Config page.
2. Click Create a New Entry.
3. Select the Code tab.
4. Paste the schema content.

Validate service definitions

A mistake in a service definition file could cause you to create a service with invalid data or introduce an error into the metadata of an existing service.

To prevent this, validate your service definition files in one of the following ways:

Validate through the Datadog app

If creating your service definition in-app, the UI will automatically flag invalid data.

Validate with an IDE extension

Built-in validation mechanisms prevent you from sending incorrect metadata into Software Catalog.

Validate with Datadog Event Management and Github Integration

To validate your service definitions ingested by Datadog’s Github integration, you can view events when services or updated or when there is an error. You can view validation errors in Event Management by filtering by source:software_catalog and status:error. Adjust the timeframe as needed.

Import Entries from Backstage

If you already have data or services registered in Backstage, you can import these services into Datadog directly.

If you use API or Terraform, replace the YAMLs in your requests.

If you use a GitHub integration, directly save your Backstage YAMLs to a repo with Datadog read permission. Datadog scans for files named catalog-info.yaml located at the root folder of a repo.

Upon import, the following occurs:

• Datadog recognizes kind:component and kind:system in Backstage YAML; kind:component in Backstage is recognized as a service in Datadog
• metadata.name gets mapped to dd-service
• metadata.namespace gets mapped to a custom tag with the format namespace:${metadata.namespace}
• spec.lifecycle gets mapped to lifecycle
• spec.owner gets mapped to team
• metadata.links gets mapped to links
  • The annotation github.com/project-slug maps to a link with type=repo and url=https://www.github.com/${github.com/project-slug}
  • The annotations pagerduty.com/service-id and pagerduty.com/account are combined and map to integration.pagerduty
• metadata.description gets mapped to description
• spec.system gets mapped to application
• spec.dependsOn gets mapped to dependsOn
• Other spec values get mapped to custom tags

Note: The Software Catalog processes the entire YAML file as a whole. If any section of the YAML file does not have kind:component or kind:system, the entire catalog-info.yaml file is rejected. Schema version v3.0 is required to use kind:system and the dependsOn field.

Example YAML for catalog-info.yaml

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: artist-web
  description: The place to be, for great artists
spec:
  type: service
  lifecycle: production
  owner: artist-relations-team
  system: artist-engagement-portal
  dependsOn:
    - service:email-service

Import Entries from ServiceNow

To populate your Datadog Software Catalog with services from your ServiceNow CMDB, use the Service Ingestion feature in the Datadog-ServiceNow integration.

Further reading

Additional helpful documentation, links, and articles:

Create and manage service definitions with TerraformEXTERNAL SITE Learn about the Service Definition APIAPI Learn about the GitHub IntegrationDOCUMENTATION Import Backstage YAML files into DatadogBLOG Manage your infrastructure with ServiceNow CMDB and DatadogBLOG Service Definition SchemaSOURCE CODE Manage Service Catalog entries with the Service Definition JSON SchemaBLOG