Entity Model

Documentation > Internal Developer Portal > Catalog > Entity Model

Cette traduction n'est pas à jour. Pour consulter la dernière version en anglais, cliquez ici

Présentation

Catalog utilise des schémas de définition pour stocker et afficher les métadonnées sur vos entités. Les schémas disposent de règles de validation intégrées pour garantir que seules des valeurs valides sont acceptées. Vous pouvez consulter les avertissements dans l’onglet Définition du panneau latéral de Catalog pour tous les services sélectionnés.

Utilisez le champ links pour ajouter des liens de code source vers des dépôts GitHub ou GitLab.

Un organigramme montrant comment les composants de Catalog se connectent entre eux et avec votre environnement cloud

Versions prises en charge

Datadog prend en charge quatre versions du schéma de définition :

v3.0 : Dernière version avec un modèle de données étendu, la prise en charge de la propriété multiple, la déclaration manuelle des dépendances et des fonctionnalités améliorées pour les infrastructures complexes.
v2.2 : Prend en charge les annotations utilisateur pour les métadonnées personnalisées et les associations de pipelines CI pour lier les services à leurs processus de construction.
v2.1 : Prend en charge le regroupement de services pour une meilleure organisation et introduit des champs supplémentaires pour des descriptions de service plus complètes.
v2 : Première version prise en charge, fournissant les champs essentiels pour les métadonnées de service de base et la documentation.

Chaque version s’appuie sur la précédente, ajoutant de nouvelles fonctionnalités tout en maintenant la rétrocompatibilité. Choisissez la version qui correspond le mieux à vos besoins et à la complexité de votre infrastructure.

Comparaison des versions

Les fonctionnalités suivantes sont prises en charge dans chaque version :

Fonctionnalité	v3.0	v2.2	v2.1	v2.0
Métadonnées de base
Regroupements de services
Annotations utilisateur
Associations de pipeline CI
Modèle de données étendu
Propriété multiple
Déclaration manuelle de dépendance

Pour des informations détaillées sur chaque version, y compris les schémas complets et des exemples de fichiers YAML, consultez les pages de version individuelles dans Versions prises en charge.

Détails de la version

Inscrivez-vous à la version préliminaire pour obtenir la dernière version de Catalog.

Request Access

Fonctionnalités clés

Modèle de données étendu : v3.0 prend en charge plusieurs types d’entités. Vous pouvez organiser vos systèmes en utilisant divers composants tels que des systèmes, des services, des files d’attente et des banques de données.
Propriété multiple : vous pouvez affecter plusieurs propriétaires à tout objet défini via le schéma v3.0 afin de spécifier plusieurs points de contact.
Mappage amélioré des relations : avec les données APM et USM, vous pouvez détecter automatiquement les dépendances entre les composants. La v3.0 prend en charge la déclaration manuelle pour augmenter la topologie système détectée automatiquement afin de garantir une vue d’ensemble complète de la manière dont les composants interagissent au sein de vos systèmes.
Héritage des métadonnées système : les composants au sein d’un système héritent automatiquement des métadonnées du système. Il n’est plus nécessaire de déclarer les métadonnées pour tous les composants associés un par un comme dans les versions v2.1 et v2.2.
Emplacement précis du code : ajoutez le mappage de l’emplacement de votre code pour votre service. La section codeLocations dans la v3.0 spécifie les emplacements du code avec le dépôt qui contient le code et son paths associé. L’attribut paths est une liste de globs qui doivent correspondre aux chemins dans le dépôt.
Logs et événements filtrés : déclarez des logs enregistrés et des requêtes d’événements pour un system via les sections logs et events et affichez les résultats sur la page Système.
Entités personnalisées : définissez des types d’entités personnalisés au-delà de Service, System, Datastore, Queue et API. Restreignez l’application des cartes de score et des actions aux types d’entités spécifiques.
(À venir) Integrations : intégrez des outils tiers pour obtenir dynamiquement des informations relatives à vos composants (par exemple, GitHub pull requests, incidents PagerDuty et pipelines GitLab). Générez des rapports et rédigez des règles de cartes de score pour toute source tierce.
(À venir) Regroupement par produit ou domaine : organisez les composants par produit, ce qui permet plusieurs niveaux de regroupement hiérarchique.

Structure du schéma

Vous pouvez consulter les définitions complètes du schéma sur Github.

La v3.0 contient les changements suivants par rapport à la v2.2 :

schema_version est maintenant apiVersion Le champ - kind est nouveau et définit le type de composant : service, queue, datastore, system ou API
dd-service est maintenant metadata.name
team est maintenant owner et additionalOwners s’il y a plusieurs équipes
lifecycle, tier, languages et type sont maintenant sous spec
links, contacts, description et tags sont maintenant sous métadonnées
application a été amélioré pour devenir son propre type : system. Il n’existe plus en tant que champ distinct sur un service.

Exemples de fichiers YAML

Composant de `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

Composant de `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

Composants faisant partie de plusieurs systèmes

Si un seul composant fait partie de plusieurs systèmes, vous devez spécifier ce composant dans le YAML pour chaque système. Par exemple, si la banque de données orders-postgres est un composant aussi bien d’un parc postgres que d’une application web, spécifiez deux YAML :

Pour le parc postgres (managed-postgres), spécifiez une définition pour 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

Pour l’application web (shopping-cart), déclarez une définition distincte pour 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
---

Héritage de métadonnées explicite et implicite

Héritage explicite

Le champ inheritFrom indique au pipeline d’ingestion d’hériter des métadonnées de l’entité référencée par <entity_kind>:<name>.

entity.datadog.yaml

inheritFrom:<entity_kind>:<name>

Héritage implicite

Les composants (kind:service, kind:datastore, kind:queue, kind:ui) héritent de toutes les métadonnées du système auquel ils appartiennent dans les conditions suivantes :

Il n’y a qu’un seul système défini dans le fichier YAML.
La clause inheritFrom:<entity_kind>:<name> est absente du fichier YAML.

Migration vers la v3.0

La v3.0 prend en charge les mêmes méthodes de création de métadonnées que les versions précédentes, notamment GitHub, GitLab, API, Terraform, Backstage, ServiceNow et la UI. Cependant, il existe de nouveaux endpoints d’API et une nouvelle ressource Terraform pour la v3.0.

Pour migrer les fichiers YAML de service existants de la v1, v2, v2.1 ou v2.2 vers la v3, consultez Migrer vos définitions de service vers la v3.

Documentation de référence de l’API

Pour créer, obtenir et supprimer des définitions pour tous les types d’entités tels que les endpoints, les systèmes, les banques de données et les files d’attente, consultez la référence de l’API Catalog.

Fonctionnalités clés

Annotations utilisateur
Remplacement du type de service et des langages détectés automatiquement à l’aide de type et languages
Associer un pipeline CI à un service à l’aide de ci-pipeline-fingerprints
Logique de validation moins restrictive pour contact.type et link.type

Structure du schéma

Le schéma complet est disponible sur GitHub.

Exemple de 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

Documentation de référence de l’API

Pour créer, obtenir et supprimer des définitions de service, consultez la référence de l’API Service Definitions.
Pour créer, obtenir et supprimer des définitions pour de nouveaux types de composants tels que les systèmes, les banques de données et les files d’attente, consultez la référence de l’API Catalog.
Pour créer et mettre à jour les règles et les résultats des cartes de score de service, consultez la référence de l’API Service Scorecards.

Fonctionnalités clés

Nouveaux éléments d’interface utilisateur tels que les regroupements de services et les champs pour application, tier et lifecycle
Application et Teams peuvent être utilisés comme variables de regroupement dans Catalog Le champ - Lifecycle indique la phase de développement pour différencier les services production, experimental ou deprecated Le champ - Tier indique la criticité du service pour la priorisation lors du triage des incidents

Structure du schéma

Le schéma complet est disponible sur GitHub.

Exemple de 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"

Documentation de référence de l’API

Pour créer, obtenir et supprimer des définitions de service, consultez la référence de l’API Service Definitions.
Pour créer, obtenir et supprimer des définitions pour de nouveaux types de composants tels que les systèmes, les banques de données et les files d’attente, consultez la référence de l’API Catalog.
Pour créer et mettre à jour les règles et les résultats des cartes de score de service, consultez la référence de l’API Service Scorecards.

Fonctionnalités clés

Métadonnées de service de base
Associations d’équipe
Informations de contact
Liens externes

Structure du schéma

Le schéma complet est disponible sur GitHub.

Exemple de 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

Documentation de référence de l’API

Pour créer, obtenir et supprimer des définitions de service, consultez la référence de l’API Service Definitions.
Pour créer, obtenir et supprimer des définitions pour de nouveaux types de composants tels que les systèmes, les banques de données et les files d’attente, consultez la référence de l’API Catalog.
Pour créer et mettre à jour les règles et les résultats des cartes de score de service, consultez la référence de l’API Service Scorecards.

Créez des extensions personnalisées

Les extensions personnalisées sont en disponibilité limitée pour toutes les versions de schéma.

Les extensions personnalisées vous permettent d’attacher des métadonnées spécifiques à l’organisation aux entités, permettant la prise en charge d’outils et de workflows personnalisés. Par exemple, utilisez le champ extensions pour inclure des notes de version, des tags de conformité ou des modèles de propriété dans vos définitions d’entité.

Datadog prend également en charge des clés d’extension spécifiques pour certaines fonctionnalités. Celles-ci incluent :

datadoghq.com/dora-metrics : Définissez des modèles de chemin de code source pour filtrer les commits Git lors du calcul des métriques DORA.
datadoghq.com/cd-visibility : Contrôlez quels commits sont considérés comme faisant partie d’un déploiement dans CD Visibility.

L’exemple suivant définit une extension personnalisée utilisée pour gérer la planification des versions dans les environnements :

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"

Validation de schéma via un plugin IDE

Datadog fournit un JSON Schema pour les définitions afin que, lorsque vous modifiez une définition dans un IDE pris en charge, des fonctionnalités telles que la saisie semi-automatique et la validation soient fournies.