You can add metadata to existing Service Catalog entries through the Datadog UI, API, or use automated pipelines through the GitHub integration or Terraform.
Metadata structure and supported versions
Service Catalog uses service definition schemas to store and display relevant metadata about your services. The schemas have built-in validation rules to ensure that only valid values are accepted and you can view warnings in the Definition tab on the side panel for any selected services.
There are three supported versions of the schema:
V2 is the earliest version, and contains some experimental features, such as dd-team, which are removed from v2.1.
V2.1 supports additional UI elements such as service groupings and fields like application, tier, and lifecycle. Application, along with Teams, can be used as grouping variables in Service Catalog. Lifecycle helps you differentiate between production, experimental, or deprecated services to indicate development stages and apply different reliability and availability requirements. Tier indicates the criticality of services, to prioritize during incident triage. For example, tier 1 typically represents the most critical services whose failure would result in severe customer impact, whereas tier 4 services typically have no impacts on actual customer experience.
V2.2 supports user annotation and overwriting auto-detected service type and languages using the fields type and languages. It also adds support for associating CI pipelines with a service using the field ci-pipeline-fingerprints. This version also includes less restrictive validation logic for contact.type and link.type, so users should expect fewer warnings while submitting YAML.
V3.0 adds a kind field that supports schemas for additional component types including applications, internal and external libraries, queues, and datastores. Any components within an application implicitly inherit its metadata. Furthermore, this version supports manually declaring dependency relationships, in addition to the auto-detected topology through Distributed Tracing and Universal Service Monitoring.
For more information about the latest updates, see the schemas on GitHub.
Opt in to the private beta for metadata schema v3.0!
The Entity Definition Schema is a structure that contains basic information about an entity. See the full schema on GitHub.
New features in v3.0
Analysis units
Beyond services, you can organize your systems using various components such as applications, services, queues, and datastores. This holistic view supports better analysis and management.
Map relationships
With APM/USM data, you can automatically detect dependencies among components. The schema supports manual declaration to augment auto-detected application topology. This ensures a complete overview of how components interact within your applications.
Inheritance of application metadata
Components within an application automatically inherit the application’s metadata, simplifying management and visibility.
Multi-ownership
For improved collaboration, you can assign multiple owners to any entity within your system, ensuring responsibilities are accurately defined.
Custom filters for APM metrics, logs, and events
With the datadog field in v3.0 schema, you can specify custom filters for logs and events associated with each component.
Example entity definition (kind:application)
entity.datadog.yaml
apiVersion:v3kind:applicationmetadata:name:myappdisplayName:My Apptags:- tag:valuelinks:- name:shopping-cart runbooktype:runbookurl:https://runbook/shopping-cart- name:shopping-cart architectureprovider:gdocurl:https://google.drive/shopping-cart-architecturetype:doc- name:shopping-cart Wikiprovider:wikiurl:https://wiki/shopping-carttype:doc- name:shopping-cart source codeprovider:githuburl:http://github/shopping-carttype:repocontacts:- name:Support Emailtype:emailcontact:team@shopping.com- name:Support Slacktype:slackcontact:https://www.slack.com/archives/shopping-cartowner:myteamadditionalOwners:- name:opsTeamtype:operatorintegrations:pagerduty:serviceURL:https://www.pagerduty.com/service-directory/Pshopping-cartopsgenie:serviceURL:https://www.opsgenie.com/service/shopping-cartregion:USspec:components:- service:myservice- service:otherserviceextensions:datadoghq.com/shopping-cart:customField:customValuedatadog:performanceData:tags:- 'service:shopping-cart'- 'hostname:shopping-cart'events:- name:"deployment events"query:"app:myapp AND type:github"- name:"event type B"query:"app:myapp AND type:github"logs:- name:"critical logs"query:"app:myapp AND type:github"- name:"ops logs"query:"app:myapp AND type:github"pipelines:fingerprints:- fp1- fp2
Example entity definition (kind:service, kind:datastore, kind:queue)
entity.datadog.yaml
apiVersion:v3kind:servicemetadata:name:shopping-cartdisplayName:Shopping CartinheritFrom:service:otherServicetags:- tag:valuelinks:- name:shopping-cart runbooktype:runbookurl:https://runbook/shopping-cart- name:shopping-cart architectureprovider:gdocurl:https://google.drive/shopping-cart-architecturetype:doc- name:shopping-cart Wikiprovider:wikiurl:https://wiki/shopping-carttype:doc- name:shopping-cart source codeprovider:githuburl:http://github/shopping-carttype:repocontacts:- name:Support Emailtype:emailcontact:team@shopping.com- name:Support Slacktype:slackcontact:https://www.slack.com/archives/shopping-cartowner:myteamadditionalOwners:- name:opsTeamtype:operatorintegrations:pagerduty:serviceURL:https://www.pagerduty.com/service-directory/Pshopping-cartopsgenie:serviceURL:https://www.opsgenie.com/service/shopping-cartregion:USextensions:datadoghq.com/shopping-cart:customField:customValuespec:lifecycle:productiontier:"1"type:weblanguages:- go- pythondependsOn:- service:serviceA- service:serviceBdatadog:performanceData:tags:- 'service:shopping-cart'- 'hostname:shopping-cart'events:- name:"deployment events"query:"app:myapp AND type:github"- name:"event type B"query:"app:myapp AND type:github"logs:- name:"critical logs"query:"app:myapp AND type:github"- name:"ops logs"query:"app:myapp AND type:github"pipelines:fingerprints:- fp1- fp2code:paths:- baz/*.c- bat/**/*- ../plop/*.java
Service Definition Schema (v2.2) (Recommended)
The Service Definition Schema is a structure that contains basic information about a service. See the full schema on GitHub.
If your service is listed in Service Catalog and already has metadata associated with it, the original source is listed in the Metadata Source column on the Ownership view. Return to that source to make any updates you need to make.
If the service has not been assigned any service definition metadata, or if the service isn’t listed in the Service Catalog yet, you can add it:
On the Service Catalog page, click Setup & Config. The Manage Entries tabs shows you how many services are without metadata.
Click Create New Entry.
Specify which service you are adding metadata to. This can be the name of a service already listed in the Service Catalog that doesn’t have service definition metadata defined for it yet, or it can be the name of a service not sending any data.
Enter details for Team, On-call, Contacts, Documentation, Code repo, and Other links.
Switch to the Code view to see the JSON and cURL generated for the metadata you’ve entered. You can copy this code as a jumping off point for programmatically providing service definitions by API, Terraform, or GitHub, without having to learn the schema for service definitions.
If you have the Service Catalog Write permission, you can submit the metadata by clicking Save Entry, or by running the cURL command provided on the Code view.
Automation options for adding metadata
Store and edit service definitions in GitHub
Configure the GitHub integration to directly link from where you view the service’s definition in the Service Catalog to where it’s stored and editable in GitHub.
To install the GitHub integration, navigate to the integration tile and click Link GitHub Account in the Repo Configuration tab.
Service definition YAML files
Datadog scans for the service.datadog.yaml file at the root of each repository with read permissions. You can register multiple services in one YAML file by creating multiple YAML documents. Separate each document with three dashes (---).
Modify service definition
When the GitHub integration is set up for your service definitions, an Edit in Github button appears in the service’s Definition tab and links you to GitHub to commit changes.
After you update the YAML files for your repositories, your changes propagate to the Service Catalog.
To prevent accidental overwriting, create and modify your service definition files with either the GitHub integration or the Service Definition API endpoints. Updating the same service using both the GitHub and the API may result in unintended overwriting.
Automate service definition updates with Terraform
The Service Catalog provides a service definition as a Terraform resource. Creating and managing services in the Service Catalog through automated pipelines requires Datadog Provider v3.16.0 or later.
This GitHub Action allows you to register your services with the Service Catalog using a GitHub Action, with full control over when this information is sent to Datadog, and implement other compliance checks unique to your organization.
Build custom extensions
The extensions field is supported in all versions including v2. You can incorporate this custom field into deployment processes to standardize and codify best practices.
