定義スキーマ v3.0

概要

スキーマ v3.0 は、柔軟性と詳細な定義を提供するために、いくつかの新機能と拡張を導入します。

主な特徴

  • 拡張されたデータ モデル: v3.0 は複数種のエンティティをサポートします。システム、サービス、キュー、データ ストアなどのさまざまなコンポーネントでシステムを編成できます。

  • 複数所有者: v3.0 スキーマで定義した任意のオブジェクトに複数の所有者を割り当て、複数の連絡先を指定できます。

  • 関係性のマッピング強化: APM と USM のデータにより、コンポーネント間の依存関係を自動検出できます。v3.0 では、自動検出されたシステム トポロジーを補強するための手動宣言をサポートし、システム内でコンポーネントがどのように相互作用するかの全体像を把握できます。

  • システム メタデータの継承: システム内のコンポーネントは、そのシステムのメタデータを自動的に継承します。v2.1 や v2.2 のときのように、関連コンポーネントそれぞれにメタデータを一つずつ宣言する必要はありません。

  • コード ロケーションの明確化: サービスのコード ロケーションのマッピングを追加できます。v3.0 の codeLocations セクションでは、コードを含むリポジトリと、その関連する paths を指定します。paths 属性は、リポジトリ内のパスにマッチさせるための グロブ のリストです。

  • (プレビュー) カスタム エンティティ: Service、System、Datastore、Queue、API 以外のカスタムなエンティティ タイプを定義できます。スコアカードやアクションの適用範囲を特定のエンティティ タイプに限定できます。

  • (プレビュー) インテグレーション: サードパーティ ツールと連携し、コンポーネントに関連する情報を動的に取り込めます (例: GitHub の pull request、PagerDuty のインシデント、GitLab のパイプライン)。任意のサードパーティ ソースに対してレポートし、スコアカード ルールを作成できます。

  • (プレビュー) 製品またはドメインでのグループ化: コンポーネントを製品別に整理し、複数層の階層グループ化を可能にします。

Software Catalog の最新バージョンの Preview にオプトイン

Request Access

メタデータ スキーマ v3.0

Entity Definition Schema は、エンティティの基本情報を格納する構造体です。GitHub にあるフルスキーマを参照してください。

v3.0 では、更新された公開スキーマの用語に合わせ、ドキュメント内の application フィールドは system に置き換えられました。

kind:system の YAML 例

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:custom.library の YAML 例

entity.datadog.yaml

apiVersion: v3
kind: custom.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

複数のシステムに属する共通コンポーネントの指定

1 つのコンポーネントが複数のシステムに属する場合は、各システムの YAML にそのコンポーネントを記述する必要があります。たとえば、データ ストア orders-postgres が postgres フリートと Web アプリケーションの両方のコンポーネントである場合は、2 つの 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

Web アプリケーション (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
---

明示的・暗黙的なメタデータの継承

明示的継承

entity.datadog.yaml

inheritFrom:<entity_kind>:<name>

inheritFrom フィールドは、<entity_kind>:<name> で参照されるエンティティのメタデータを継承するように取り込みパイプラインに指示します。

暗黙的継承

コンポーネント（kind:service、kind:datastore、kind:queue、kind:ui）は、次の条件を満たす場合に、所属するシステムのすべてのメタデータを継承します:

  • YAML ファイル内で定義されているシステムが 1 つだけであること。
  • YAML ファイルに inheritFrom:<entity_kind>:<name> という句が存在しないこと。

v3.0 の API エンドポイント

v3.0 の API エンドポイントについては、最新の API ドキュメント を参照してください。

スキーマ概要

GitHub 上のスキーマ定義全文 を参照できます。以下はスキーマ構造の概要です:

  • api_version: スキーマのバージョン (2.0、2.1、3.0)。
  • kind: 新しいフィールドで、コンポーネントの種類を定義します (service、queue、datastore、system、API)。
  • metadata: 命名、説明、所有者、リンク (ドキュメント、ランブック、リポジトリ、連絡先、ダッシュボード)、およびタグを含みます。
  • spec: 階層、ライフサイクル、言語、タイプ、他コンポーネントとの関係を含みます。
  • integrations: PagerDuty と OpsGenie への接続を含みます。
  • datadog: コード ロケーション、パイプライン、ログ、イベントなど、他の Datadog データへのフィルターやリンク方法を含みます。

v3.0 への移行

v3.0 は、従来バージョンと同じメタデータ作成方法をサポートします (GitHub、API、Terraform、Backstage、ServiceNow、UI など)。ただし、v3.0 には新しい API エンドポイント と新しい Terraform モジュール があります。

GitHub 上のスキーマ定義全文 も参照できます。v3.0 では v2.2 から次の変更があります:

  • schema_version は apiVersion になりました。
  • kind フィールドが新設され、コンポーネントの種類 (service、queue、datastore、system、API) を定義します。
  • dd-service は metadata.name になりました。
  • team は owner に変更され、チームが複数ある場合は additionalOwners が使われます。
  • lifecycle、tier、languages、type は spec の下になりました。
  • links、contacts、description、tags は metadata の下になりました。
  • application は強化され、独立した kind である system になりました。サービス上の個別フィールドとしては存在しません。

Software Catalog の System ページと API ページ

kind:system と kind:api のエンティティを定義すると、service、queue、datastore、endpoint を含むエンティティの階層的なグルーピングが作成されます。システムまたは API 内のコンポーネントを定義するには、エンティティの v3 定義の spec フィールドにある components キーに値を指定します。

kind:system の YAML 例:

entity.datadog.yaml

apiVersion: v3
kind: system
metadata:
  name: product-recommendation
  description: Surfaces personalized product suggestions in Shopist
  displayName: "Product Recommendation"
  tags:
  - product:recommendations
  - business-line:shared-components
  owner: shopist
  additionalOwners:
    - name: Shopist Support Team
      type: Operator
spec:
  lifecycle: production
  tier: "0"
  components:
  - service: product-recommendation
  - service: orders-app
  - api: products
  - system: shopist-user-trends

上記のユーザー定義のシステムは、以下のとおり Software Catalog に表示されます。このページには、システムと上流/下流の依存関係の間のコンポーネントの関係データに加えて、すべてのシステム コンポーネントを横断して集計されたスコア カード、ログ、イベントが保持されます。

Software Catalog の Product Recommendations システムの System ページ

kind:api の YAML 例:

entity.datadog.yaml

{
 "apiVersion": "v3",
 "kind": "api",
 "metadata": {
   "name": "payments",
   "displayName": "Payments",
   "owner": "Payments Team",
   "links": [
     {
       "name": "Deployment Information",
       "type": "doc",
       "url": "https://wiki/products
"
     },
     {
       "name": "Source",
       "type": "repo",
       "provider": "github",
       "url": "https://github.com/"
     },
     {
       "name": "Performance Dashboard",
       "type": "dashboard",
       "url": "https://datadoghq.com"
     }
   ]
 },
 "integrations": {
   "pagerduty": {
     "serviceURL": "https://www.pagerduty.com/service-directory/products"
   }
 },
 "spec": {
   "type": "openapi",
   "implementedBy": [
     "service:payment",
     "service:payments-go"
   ],
   "interface": {
     "definition": {
       "info": {
         "title": "Payments"
       },
       "openapi": "3.0.0",
       "paths": {
         "/add_item": {
           "post": {
             "responses": {
               "200": {
                 "description": "OK"
               }
             }
           }
         },
         "/add_purchases": {
           "post": {
             "responses": {
               "200": {
                 "description": "OK"
               }
             }
           }
         },
         "/admin/update_user": {
           "post": {
             "responses": {
               "200": {
                 "description": "OK"
               }
             }
           }
         },
         "/carts": {
           "get": {
             "responses": {
               "200": {
                 "description": "OK"
               }
             }
           }
         }
       }
     }
   },
   "lifecycle": "production",
   "tier": "Tier 0"
 }
}

ユーザー定義の API は、以下のとおり Software Catalog に表示されます。このページには、API が依存関係とどのように相互作用するかに関する関係データ、API コンポーネント、OpenAPI プレビュー、そして全エンド ポイントを横断して集計されたログとイベントが含まれます。

Software Catalog の Payments API の API ページ

参考資料

お役に立つドキュメント、リンクや記事:

Terraform を用いた定義の作成および管理外部サイト more more Definition API についてAPI more more GitHub インテグレーションについてドキュメント more more Backstage の YAML ファイルを Datadog にインポートブログ more more Service Catalog スキーマ v3.0 で開発者体験とコラボレーションを向上ブログ more more