Service Definitions and Supported Versions

문서 > Datadog 서비스 카탈로그 > Service Definitions and Supported Versions

이 페이지는 아직 한국어로 제공되지 않으며 번역 작업 중입니다. 번역에 관한 질문이나 의견이 있으시면 언제든지 저희에게 연락해 주십시오.

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 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!

Request Access

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.

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: 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>'