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 four 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 systems, queues, and datastores. Any components within a system 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. In v3.0, application is replaced with system.
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.
Change to Field Name in the v3.0 Schema
For beta customers using v3.0, application has been replaced with system in the documentation to match the updated public schema terminology.
New features in v3.0
Expanded data model
v3.0 supports multiple kinds of entities. You can organize your systems using various components such as systems, services, queues, and datastores.
Multi-ownership
You can assign multiple owners to any objects defined through the v3.0 schema to specify multiple points of contact.
Enhanced relationship mapping
With APM and USM data, you can automatically detect dependencies among components. v3.0 supports manual declaration to augment auto-detected system topology to ensure a complete overview of how components interact within your systems.
Inheritance of system metadata
Components within a system automatically inherit the system’s metadata. It’s no longer necessary to declare metadata for all related components one-by-one as in v2.1 and v2.2.
Precise code location
You can add the mapping of your code location for your service. The codeLocations section in v3.0 specifies the locations of the code with the repository that contains the code and its associated paths. The paths attribute is a list of globs that should match paths in the repository. Learn more about how this addition improves your experience with Datadog Code Analysis.
Example YAML for kind:system
entity.datadog.yaml
apiVersion:v3kind:systemmetadata:name:myappnamespace:defaultdisplayName: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:code:- paths:- baz/*.c- bat/**/*- ../plop/*.javaevents:- 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
Specify common components that are part of multiple systems
If a single component is part of multiple systems, you must specify that component in the YAML for each system. For example, if the datastore orders-postgres is a component of both a postgres fleet and a web application, specify two YAMLs:
For the postgres fleet (managed-postgres), specify a definition for kind:system:
The inheritFrom field instructs the ingestion pipeline to inherit metadata from the entity’s metadata referenced by <entity_kind>:<name>.
Note: The entity reference only applies to an entity from the same YAML file.
Implicit Inheritance
Components (kind:service, kind:datastore, kind:queue, kind:ui) inherit all metadata from the system that they belong to under the following conditions:
There is only one system defined in the YAML file.
The clause inheritFrom:<entity_kind>:<name> is absent in the YAML file.
