概要
スキーマ 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 のパイプライン)。任意のサードパーティ ソースに対してレポートし、スコアカード ルールを作成できます。
(プレビュー) 製品またはドメインでのグループ化: コンポーネントを製品別に整理し、複数層の階層グループ化を可能にします。
メタデータ スキーマ v3.0
Entity Definition Schema は、エンティティの基本情報を格納する構造体です。GitHub にあるフルスキーマを参照してください。
v3.0 では、更新された公開スキーマの用語に合わせ、ドキュメント内の application
フィールドは system
に置き換えられました。
kind:system
の 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 例
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
の定義を記述します:
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
定義を宣言します:
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>
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 例:
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 に表示されます。このページには、システムと上流/下流の依存関係の間のコンポーネントの関係データに加えて、すべてのシステム コンポーネントを横断して集計されたスコア カード、ログ、イベントが保持されます。
kind:api
の 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 プレビュー、そして全エンド ポイントを横断して集計されたログとイベントが含まれます。
参考資料