엔터티 모델

문서 > Internal Developer Portal > Catalog > 엔터티 모델

개요

Catalog는 정의 스키마를 사용하여 엔터티와 관련된 메타데이터를 저장하고 표시합니다. 이 스키마에는 유효한 값만 허용되도록 보장하는 기본 제공 유효성 검사 규칙이 포함되어 있습니다. 선택한 서비스에 대해 Catalog 사이드 패널의 Definition 탭에서 경고를 조회할 수 있습니다.

links 필드를 사용하여 GitHub 또는 GitLab 리포지토리에 대한 소스 링크를 추가하십시오.

Catalog 구성 요소가 서로 연결되고 클라우드 환경과 연결되는 방식을 보여주는 흐름도

지원되는 버전

Datadog은 정의 스키마의 네 가지 버전을 지원합니다.

v3.0: 확장된 데이터 모델, 다중 소유권 지원, 수동 종속성 선언 및 복잡한 인프라를 위한 향상된 기능을 제공하는 최신 버전입니다.
v2.2: 사용자 지정 메타데이터를 위한 사용자 주석과 서비스를 빌드 프로세스에 연결하기 위한 CI 파이프라인 연결을 지원합니다.
v2.1: 향상된 구성 관리를 위한 서비스 그룹화를 지원하며 보다 포괄적인 서비스 설명을 위한 추가 필드를 도입합니다.
v2: 기본 서비스 메타데이터 및 문서화를 위한 필수 필드를 제공하는 가장 초기 버전입니다.

각 버전은 이전 버전을 기반으로 하여 새로운 기능을 추가하면서도 이전 버전과의 호환성을 유지합니다. 자신의 필요와 인프라 복잡성에 가장 적합한 버전을 선택하세요.

버전 비교

각 버전에서 지원되는 기능은 다음과 같습니다.

기능	v3.0	v2.2	v2.1	v2.0
기본 메타데이터
서비스 그룹화
사용자 주석
CI 파이프라인 연결
확장된 데이터 모델
다중 소유자
수동 종속성 선언

각 버전에 대한 자세한 정보(전체 스키마 및 YAML 예시 파일 포함)는 지원되는 버전의 개별 버전 페이지를 참조하세요.

버전 세부 정보

주요 기능

확장된 데이터 모델: v3.0은 여러 종류의 엔터티를 지원합니다. 시스템, 서비스, 대기열, 데이터스토어 등의 다양한 구성 요소를 사용하여 시스템을 구성할 수 있습니다.
다중 소유자: v3.0 스키마를 통해 정의된 모든 객체에 여러 소유자를 할당하여 여러 연락 창구를 지정할 수 있습니다.
향상된 관계 매핑: APM 및 USM 데이터를 사용하여 구성 요소 간의 종속성을 자동으로 탐지할 수 있습니다. v3.0은 자동으로 탐지된 시스템 토폴로지를 보완하기 위해 수동 선언을 지원하여 시스템 내의 구성 요소가 상호 작용하는 방식을 완전하게 파악하도록 할 수 있습니다.
시스템 메타데이터의 상속: 시스템 내의 구성 요소는 시스템의 메타데이터를 자동으로 상속합니다. v2.1 및 v2.2와 같이 모든 관련 구성 요소에 대해 메타데이터를 하나씩 선언할 필요가 없습니다.
정확한 코드 위치: 서비스에 대한 코드 위치 매핑을 추가합니다. v3.0의 codeLocations 섹션은 코드가 포함된 리포지토리와 관련 paths 정보를 사용하여 코드 위치를 지정합니다. paths 속성은 리포지토리 내 경로와 일치해야 하는 glob 목록입니다.
필터링된 로그 및 이벤트: system에 대한 저장된 로그 및 이벤트 쿼리를 logs 및 events 섹션을 통해 선언하고 System 페이지에서 결과를 확인합니다.
사용자 지정 엔터티: Service, System, Datastore, Queue, API 외에 사용자 지정 엔터티 유형을 정의합니다. 특정 엔터티 유형으로 scorecard와 액션의 범위를 한정합니다.
(예정) 통합: 타사 도구와 통합하여 구성 요소와 관련된 정보를 동적으로 소싱합니다(예: GitHub 풀 요청, PagerDuty 인시던트 및 GitLab 파이프라인). 모든 타사 소스를 대상으로 보고서를 생성하거나 scorecard 규칙을 작성합니다.
(예정) 제품 또는 도메인별 그룹화: 제품별로 구성 요소를 조직하여 여러 단계의 계층 구조로 그룹화할 수 있습니다.

스키마 구조

Github에서 전체 스키마 정의를 확인할 수 있습니다.

v3.0에는 v2.2 대비 다음과 같은 변경 사항이 포함되어 있습니다.

schema_version는 apiVersion로 변경되었습니다.
kind 필드가 새로 추가되었으며 구성 요소 유형(서비스, 대기열, 데이터스토어, 시스템 또는 API)을 정의합니다.
dd-service는 metadata.name으로 변경되었습니다.
team은 owner로 변경되었으며, 여러 팀이 있는 경우 additionalOwners를 사용할 수 있습니다.
lifecycle, tier, languages, type은 이제 spec 아래에 있습니다.
links, contacts, description, tags는 이제 metadata 아래에 있습니다.
application은 독립적인 유형인 system으로 확장되었습니다. 더 이상 서비스의 개별 필드로 존재하지 않습니다.

예시 YAML 파일

다음의 구성 요소: `kind:system`

entity.datadog.yaml

apiVersion: v3
kind: system
metadata:
  name: myapp
  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:
  codeLocations:
    - repositoryURL: https://github.com/myorganization/myrepo.git
      paths:
        - path/to/service/code/**
  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

다음의 구성 요소: `kind:library`

entity.datadog.yaml

apiVersion: v3
kind: library
metadata:
  name: my-library
  displayName: My Library
  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

여러 시스템에 속한 구성 요소

하나의 구성 요소가 여러 시스템에 속하는 경우 각 시스템의 YAML에 해당 구성 요소를 지정해야 합니다. 예를 들어, 데이터스토어 orders-postgres가 Postgres 플릿과 웹 애플리케이션 모두의 구성 요소인 경우 두 개의 YAML을 지정해야 합니다.

Postgres 플릿(managed-postgres)에 대해 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

웹 애플리케이션(shopping-cart)에 대해 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
---

명시적 및 암시적 메타데이터 상속

명시적 상속

inheritFrom 필드는 수집 파이프라인에 <entity_kind>:<name>에서 참조된 엔터티의 메타데이터를 상속하도록 지시합니다.

entity.datadog.yaml

inheritFrom:<entity_kind>:<name>

암시적 상속

구성 요소(kind:service, kind:datastore, kind:queue, kind:ui)는 다음 조건에서 자신이 속한 시스템의 모든 메타데이터를 상속합니다.

YAML 파일에 정의된 시스템이 하나뿐인 경우
YAML 파일에 inheritFrom:<entity_kind>:<name> 절이 없는 경우

v3.0으로 마이그레이션

v3.0은 GitHub, GitLab, API, Terraform, Backstage, ServiceNow 및 UI를 포함하여 이전 버전과 동일한 메타데이터 생성 방법을 지원합니다. 그러나 v3.0에 새로운 API 엔드포인트와 새로운 Terraform 리소스가 추가되었습니다.

기존 서비스 YAML 파일을 v1, v2, v2.1 또는 v2.2에서 v3로 마이그레이션하려면 서비스 정의를 v3로 마이그레이션을 참조하세요.

API 참조 문서

엔드포인트, 시스템, 데이터스토어, 대기열 등 모든 엔터티 유형에 대한 정의를 생성, 조회 및 삭제하려면 Catalog API 참조를 참조하세요.

주요 기능

사용자 주석
자동 탐지된 서비스 유형 및 언어를 type 및 languages을 사용하여 덮어쓰기
ci-pipeline-fingerprints를 사용하여 CI 파이프라인을 서비스와 연결
contact.type 및 link.type에 대해 덜 엄격한 유효성 검사 로직

스키마 구조

전체 스키마는 GitHub에서 확인할 수 있습니다.

다음은 예시 YAML입니다.

schema-version: v2.2
dd-service: shopping-cart
team: e-commerce
application: shopping-app
tier: "1"
type: web
languages:
  - go
  - python
contacts:
  - type: slack
    contact: https://yourorg.slack.com/archives/e-commerce
  - type: email
    contact: ecommerce@example.com
  - type: microsoft-teams
    contact: https://teams.microsoft.com/example
links:
  - name: Runbook
    type: runbook
    url: http://runbook/shopping-cart
  - name: Source
    type: repo
    provider: github
    url: https://github.com/shopping-cart
  - name: Deployment
    type: repo
    provider: github
    url: https://github.com/shopping-cart
  - name: Config
    type: repo
    provider: github
    url: https://github.com/consul-config/shopping-cart
  - name: E-Commerce Team
    type: doc
    provider: wiki
    url: https://wiki/ecommerce
  - name: Shopping Cart Architecture
    type: doc
    provider: wiki
    url: https://wiki/ecommerce/shopping-cart
  - name: Shopping Cart RFC
    type: doc
    provider: google doc
    url: https://doc.google.com/shopping-cart
tags:
  - business-unit:retail
  - cost-center:engineering
integrations:
  pagerduty:
    service-url: https://www.pagerduty.com/service-directory/PSHOPPINGCART
  opsgenie:
    service-url: "https://www.opsgenie.com/service/uuid"
    region: "US"
ci-pipeline-fingerprints:
  - id1
  - id2
extensions:
  additionalProperties:
    customField1: customValue1
    customField2: customValue2

API 참조 문서

서비스 정의를 생성, 조회 및 삭제하려면 Service Definitions API 참조를 참조하세요.
시스템, 데이터스토어, 대기열 등 새로운 구성 요소 유형의 정의를 생성, 조회 및 삭제하려면 Catalog API 참조를 참조하세요.
서비스 scorecard 규칙 및 결과를 생성하고 업데이트하려면 Service Scorecards API 참조를 참조하세요.

주요 기능

서비스 그룹화 및 application, tier, lifecycle에 대한 필드와 같은 새로운 UI 요소
Application 및 Teams는 Catalog에서 그룹화 변수로 사용할 수 있습니다.
Lifecycle 필드는 production, experimental 또는 deprecated 서비스 간의 차별화를 위한 개발 단계를 나타냅니다
Tier 필드는 인시던트 분류 시 우선순위를 정하기 위한 서비스의 중요도를 나타냅니다.

스키마 구조

전체 스키마는 GitHub에서 확인할 수 있습니다.

다음은 예시 YAML입니다.

schema-version: v2.1
dd-service: delivery-state-machine
team: serverless
application: delivery-state-machine
tier: tier0
lifecycle: production
contacts:
  - type: slack
    contact: https://datadogincidents.slack.com/archives/C01EWN6319S
links:
  - name: Demo Dashboard
    type: dashboard
    url: https://app.datadoghq.com/dashboard/krp-bq6-362
  - name: Source
    provider: github
    url: https://github.com/DataDog/shopist-serverless/tree/main/delivery-state-machine
    type: repo
  - name: Deployment
    provider: github
    url: https://github.com/DataDog/shopist-serverless/blob/main/delivery-state-machine/serverless.yml
    type: repo
  - name: Datadog Doc
    provider: link
    url: https://docs.datadoghq.com/
    type: doc
tags:
  - "app:serverless-delivery"
  - "tier:3"
  - "business-unit:operations"

API 참조 문서

서비스 정의를 생성, 조회 및 삭제하려면 Service Definitions API 참조를 참조하세요.
시스템, 데이터스토어, 대기열 등 새로운 구성 요소 유형의 정의를 생성, 조회 및 삭제하려면 Catalog API 참조를 참조하세요.
서비스 scorecard 규칙 및 결과를 생성하고 업데이트하려면 Service Scorecards API 참조를 참조하세요.

주요 기능

기본 서비스 메타데이터
팀 연결
연락처 정보
외부 링크

스키마 구조

전체 스키마는 GitHub에서 확인할 수 있습니다.

다음은 예시 YAML입니다.

schema-version: v2
dd-service: delivery-api
team: distribution-management
contacts:
  - type: slack
    contact: https://datadogincidents.slack.com/archives/C01EWN6319S
links:
  - name: Demo Dashboard
    type: dashboard
    url: https://app.datadoghq.com/dashboard/krp-bq6-362
repos:
  - name: Source
    provider: github
    url: https://github.com/DataDog/shopist/tree/prod/rails-storefront
docs:
  - name: Datadog Doc
    provider: link
    url: https://docs.datadoghq.com/
tags: []
integrations:
  pagerduty: https://datadog.pagerduty.com/service-directory/PXZNFXP

API 참조 문서

서비스 정의를 생성, 조회 및 삭제하려면 Service Definitions API 참조를 참조하세요.
시스템, 데이터스토어, 대기열 등 새로운 구성 요소 유형의 정의를 생성, 조회 및 삭제하려면 Catalog API 참조를 참조하세요.
서비스 scorecard 규칙 및 결과를 생성하고 업데이트하려면 Service Scorecards API 참조를 참조하세요.

사용자 지정 확장 구축

사용자 지정 확장은 모든 스키마 버전에서 제한된 가용성으로 제공됩니다.

사용자 지정 확장을 사용하면 조직별 메타데이터를 엔터티에 연결할 수 있어 사용자 지정 도구 및 워크플로를 지원할 수 있습니다. 예를 들어, extensions 필드를 사용하여 엔터티 정의에 릴리스 노트, 규정 준수 태그 또는 소유 모델을 포함할 수 있습니다.

Datadog은 특정 기능을 위한 전용 확장 키도 지원합니다. 여기에는 다음이 포함됩니다.

datadoghq.com/dora-metrics: DORA 메트릭을 계산할 때 Git 커밋을 필터링하기 위한 소스 코드 경로 패턴을 정의합니다.
datadoghq.com/cd-visibility: CD Visibility에서 배포의 일부로 간주되는 커밋을 제어합니다.

다음 예시는 환경별 릴리스 일정을 관리하는 데 사용되는 사용자 지정 확장을 정의합니다.

service.datadog.yaml

apiVersion: v3
kind: system
metadata:
  name: payment-platform
  displayName: "Payment Platform"
  links:
    - name: Runbook
      type: runbook
      url: https://runbook/payment-platform
  contacts:
    - name: Payment Team
      type: team
      contact: https://www.slack.com/archives/payments
  owner: payments-team
  additionalOwners:
    - name: finance-team
      type: stakeholder
spec:
  components:
    - service:payment-api
    - queue:payment-requests
    - datastore:payment-db
extensions:
  shopist.com/release-scheduler:
    release-manager:
      slack: "release-train-shopist"
      schedule: "* * * * *"
      env:
        - name: "staging"
          ci_pipeline: "ci-tool://shopist/k8s/staging-deploy"
          branch: "main"
          schedule: "0 9 * * 1"