Service Definition Schema v3.0 (Beta)

Docs > Catalogue des services Datadog > Service Definitions and Supported Versions > Service Definition Schema v3.0 (Beta)

Cette page n'est pas encore disponible en français, sa traduction est en cours.
Si vous avez des questions ou des retours sur notre projet de traduction actuel, n'hésitez pas à nous contacter.

Overview

Schema v3.0 is the latest version of the Service Definition schema and is in beta. It introduces several new features and enhancements to provide more flexibility and detailed service definitions.

Opt in to the private beta for metadata schema v3.0!

Request Access

Key features

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.

Metadata Schema v3.0 (beta)

The Entity Definition Schema is a structure that contains basic information about an entity. See the full schema on GitHub.

In v3.0, the application field has been replaced with system in the documentation to match the updated public schema terminology.

Example YAML for `kind:system`

entity.datadog.yaml

apiVersion: v3
kind: system
metadata:
  name: myapp
  namespace: default
  displayName: My App
  tags:
    - tag:value
  links:
    - name: shopping-cart runbook
      type: runbook
      url: https://runbook/shopping-cart
    - name: shopping-cart architecture
      provider: gdoc
      url: https://google.drive/shopping-cart-architecture
      type: doc
    - name: shopping-cart Wiki
      provider: wiki
      url: https://wiki/shopping-cart
      type: doc
    - name: shopping-cart source code
      provider: github
      url: http://github/shopping-cart
      type: repo
  contacts:
    - name: Support Email
      type: email
      contact: team@shopping.com
    - name: Support Slack
      type: slack
      contact: https://www.slack.com/archives/shopping-cart
  owner: myteam
  additionalOwners:
    - name: opsTeam
      type: operator
integrations:
  pagerduty:
    serviceURL: https://www.pagerduty.com/service-directory/Pshopping-cart
  opsgenie:
    serviceURL: https://www.opsgenie.com/service/shopping-cart
    region: US
spec:
  components:
    - service:myservice
    - service:otherservice
extensions:
  datadoghq.com/shopping-cart:
    customField: customValue
datadog:
  code:
    - paths:
      - baz/*.c
      - bat/**/*
      - ../plop/*.java
  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

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:

entity.datadog.yaml

apiVersion: v3
kind: system
spec:
  components:
    - datastore:orders-postgres
    - datastore:foo-postgres
    - datastore:bar-postgres
metadata:
  name: managed-postgres
  owner: db-team

For the web application (shopping-cart), declare a separate definition for kind:system:

entity.datadog.yaml

apiVersion: v3
kind: system
spec:
  lifecycle: production
  tier: critical
  components:
    - service:shopping-cart-api
    - service:shopping-cart-processor
    - queue:orders-queue
    - datastore:orders-postgres
metadata:
  name: shopping-cart
  owner: shopping-team
  additionalOwners:
    - name: sre-team
      type: operator
---
apiVersion: v3
kind: datastore
metadata:
  name: orders-postgres
  additionalOwners:
    - name: db-team
      type: operator
---
apiVersion: v3
kind: service
metadata:
  name: shopping-cart-api
---
apiVersion: v3
kind: service
metadata:
  name: shopping-cart-processor
---

Explicit and implicit metadata inheritance

Explicit Inheritance

entity.datadog.yaml

inheritFrom:<entity_kind>:<name>

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.

v3.0 API endpoints (alpha)

Upsert entities

POST https://api.datadoghq.com/api/unstable/catalog/definition
Permission: SERVICE_CATALOG_WRITE

curl --location 'https://api.datadoghq.com/api/unstable/catalog/definition' \
--header 'DD-API-KEY: <KEY>' \
--header 'DD-APPLICATION-KEY: <APP_KEY>' \
--data-raw '
apiVersion: v3
kind: system
metadata:
  name: shopping-cart-app
  tags:
    - tag:value
  links:
    - name: shopping-cart runbook
      type: runbook
      url: https://runbook/shopping-cart
  contacts:
    - name: Support Email
      type: email
      contact: team@shopping.com
    - name: Support Slack
      type: slack
      contact: https://www.slack.com/archives/shopping-cart
  owner: myteam
spec:
  code: 
  components:
    - service:shopping-cart-processing
    - service:shopping-cart-checkout
---
apiVersion: v3
kind: service
metadata:
  name: shopping-cart-processing
---
apiVersion: v3
kind: service
metadata:
  name: shopping-cart-checkout
'

Get entities

GET https://api.datadoghq.com/api/unstable/catalog/definition
Permission: SERVICE_CATALOG_READ

curl --location 'https://api.datadoghq.com/api/unstable/catalog/definition' \
--header 'DD-API-KEY: <KEY>' \
--header 'DD-APPLICATION-KEY: <APP_KEY>'

Get entities by ID

GET https://api.datadoghq.com/api/unstable/catalog/definition/id/
Permission: SERVICE_CATALOG_READ

curl --location 'https://api.datadoghq.com/api/unstable/catalog/definition/id/<id>' \
--header 'DD-API-KEY: <KEY>' \
--header 'DD-APPLICATION-KEY: <APP_KEY>'

Get entities by reference

GET https://api.datadoghq.com/api/unstable/catalog/definition/ref/
Permission: SERVICE_CATALOG_READ

curl --location 'https://api.datadoghq.com/api/unstable/catalog/definition/ref/<ref>' \
--header 'DD-API-KEY: <KEY>' \
--header 'DD-APPLICATION-KEY: <APP_KEY>'

URL Parameter: ref <kind>:<name>

Delete entities by reference

DELETE https://api.datadoghq.com/api/unstable/catalog/definition/ref/
Permission: SERVICE_CATALOG_WRITE

curl --location --request DELETE 'https://api.datadoghq.com/api/unstable/catalog/definition/ref/<ref>' \
--header 'DD-API-KEY: <KEY>' \
--header 'DD-APPLICATION-KEY: <APP_KEY>'