エンティティモデル

エンティティモデルスキーマ v3.0 は、選択されたサイトでは現在利用できません。

概要

Software Catalog は、エンティティに関する関連メタデータを保存および表示するために定義スキーマを使用します。スキーマには、有効な値のみが受け入れられることを保証するための組み込みの検証ルールがあります。選択したサービスについて、Software Catalog のサイドパネルの [Definition] (定義) タブで警告を確認できます。

Software Catalog のコンポーネントが互いに、そしてクラウド環境とどのように接続しているかを示すフローチャート

サポートされるバージョン

Datadog は以下の 4 つの定義スキーマのバージョンをサポートしています。

  • v3.0: 拡張されたデータモデル、マルチオーナーシップサポート、手動の依存関係宣言、複雑なインフラストラクチャー向けの拡張機能を備えた最新バージョン。
  • v2.2: カスタムメタデータのためのユーザー注釈と、サービスをビルドプロセスに関連付けるための CI パイプライン連携をサポート。
  • v2.1: サービスのグループ化による整理機能と、より包括的なサービス説明のための追加フィールドを導入。
  • v2: 基本的なサービスメタデータとドキュメンテーション用の必須フィールドを提供する、最も初期のサポートバージョン。

各バージョンは前のバージョンを基に構築され、新しい機能を追加しながら後方互換性を維持しています。ニーズとインフラストラクチャーの複雑さに合わせて、最適なバージョンを選択してください。

バージョン比較

以下は各バージョンでサポートされる機能一覧です。

機能v3.0v2.2v2.1v2.0
基本的なメタデータ
サービスのグループ化
ユーザー注釈
CI パイプラインの連携
拡張データモデル
複数のオーナーシップ
手動による依存関係宣言

完全なスキーマや YAML ファイルの例など、各バージョンの詳細な情報については、Supported versionsの各バージョンのページを参照してください。

バージョンの詳細

最新バージョンの Software Catalog のプレビューにご参加ください。

Request Access

    主な特徴

    • 拡張データモデル: v3.0 は複数の種類のエンティティをサポートしています。システム、サービス、キュー、データストアなどのさまざまなコンポーネントを使用して、システムを整理できます。
    • 複数のオーナーシップ: v3.0 スキーマで定義された任意のオブジェクトに複数の所有者を割り当てて、複数の連絡先を指定できます。
    • 強化された関係マッピング: APM および USM データを使用して、コンポーネント間の依存関係を自動的に検出できます。v3.0 では、自動検出されたトポロジ―を補完するための手動による宣言が可能で、システム内でコンポーネントがどのように相互作用しているかを完全に把握できます。
    • システムメタデータの継承: システム内のコンポーネントは、自動的にシステムのメタデータを継承します。v2.1 や v2.2 のように、関連するコンポーネントごとに個別でメタデータを宣言する必要はなくなりました。
    • 正確なコードの場所: サービスのコードが存在する場所をマッピングできます。v3.0 の codeLocations セクションでは、コードを含むリポジトリおよびその関連する paths と共に、コードの場所を指定します。paths 属性は、リポジトリ内のパスに一致する globs のリストです。
    • ログとイベントのフィルタリング: logs および events セクションで system の保存済みログやイベントクエリを宣言でき、[System] (システム) ページで結果を確認できます。
    • カスタムエンティティ: サービス、システム、データストア、キュー、API に加えて、カスタムのエンティティタイプを定義できます。スコープスコアカードやアクションを、特定のエンティティタイプに適用できます。
    • (今後対応予定) 統合機能: サードパーティツール (GitHub のプルリクエスト、PagerDuty のインシデント、GitLab のパイプラインなど) と統合し、コンポーネントに関連するソース情報を動的に取得します。サードパーティソースに対してレポートを作成し、スコアカードルールを記述できます。
    • (今後対応予定) 製品やドメインごとのグループ化: 製品ごとにコンポーネントを整理し、複数レイヤーの階層構造によるグループ化を可能にします。

    スキーマ構造

    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 はメタデータ配下に移動しました。
    • application は機能拡張され、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

    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 のフリートと 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
---

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

    明示的継承

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

    entity.datadog.yaml

    inheritFrom:<entity_kind>:<name>

    暗黙的継承

    コンポーネント (kind:service、kind:datastore、kind:queue、kind:ui) は、次の条件下で、所属するシステムからすべてのメタデータを継承します。

    • YAML ファイルに定義されたシステムが 1 つだけである。
    • YAML ファイルに inheritFrom:<entity_kind>:<name> の指定が存在しない。

    v3.0 への移行

    v3.0 は、これまでのバージョンと同様の方法で、Github、API、Terraform、Backstage、ServiceNow、UI などを利用してメタデータを作成できます。ただし、v3.0 には新しい API エンドポイント と新しい Terraform リソース があります。

    API リファレンスドキュメント

    エンドポイント、システム、データストア、キューなどのすべてのエンティティタイプの定義を作成、取得、削除する方法については、Software 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 リファレンスドキュメント

    主な特徴

    • サービスのグループ化やapplication、tier、lifecycle の各フィールドなど、新しい UI 要素が追加されました。
    • Application および Teamsは、Software 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 リファレンスドキュメント

    主な特徴

    • 基本的なサービスメタデータ
    • チームの関連付け
    • 連絡先情報
    • 外部リンク

    スキーマ構造

    完全なスキーマは 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 リファレンスドキュメント

    カスタム拡張機能を構築する

    カスタム拡張機能は、すべてのスキーマバージョンで限定的に利用可能です。

    カスタム拡張機能を使用すると、組織固有のメタデータをエンティティに追加でき、カスタムツールやワークフローのサポートが可能になります。たとえば、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"

    IDE プラグインによるスキーマ検証

    Datadog は定義用の JSON スキーマ を提供しており、対応する IDE 上で定義を編集する際に、オートコンプリートや検証などの機能が利用できるようになっています。

    VSCode で修正すべき問題を検出

    Datadog 定義用の JSON スキーマ はオープンソースの Schema Store に登録されています。

    参考資料

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

    Terraform による定義の作成と管理外部サイト more more 定義 API についてAPI more more GitHub インテグレーションについてドキュメント more more Backstage の YAML ファイルを Datadog にインポートするブログ more more Service Catalog のスキーマバージョン 3.0 で開発者体験とコラボレーションを向上させるブログ more more Datadog Software Catalog でカスタムエンティティを使用してアーキテクチャをモデル化するブログ more more