Overview

If you’re new to Datadog, you can automatically populate Software Catalog by setting up Datadog Application Performance Monitoring (APM), Universal Service Monitoring (USM), Real User Monitoring (RUM), infrastructure metrics, or logs.

Alternatively, you can add components to Software Catalog by:

• Manually creating service definitions through the Datadog UI, 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 telemetry data from Datadog or external sources manually using entity definition YAML files.

Build a 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 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 the Datadog UI

Alternatively, create service definitions in the Datadog UI:

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:

Datadog UI validation

If you create service definitions in the Datadog UI, Datadog automatically flags invalid data.

IDE extension validation

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

GitHub Integration validation

To validate your service definitions ingested by Datadog’s GitHub integration, you can view events when services are updated or when there is an error. To view validation errors in Event Management, filter 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.

To import Backstage definitions:

• API or Terraform: Replace the YAMLs in your requests with Backstage YAMLs.
• GitHub integration: Save your Backstage YAMLs in a repository with Datadog read permissions. Datadog scans for files named catalog-info.yaml located at the root folder of the repository.

During import, Datadog maps Backstage data to Datadog data:

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 Configuration Management Database (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