Modelo de Entidad

Documentos > Internal Developer Portal > Software Catalog > Modelo de Entidad

Resumen

El Software Catalog utiliza esquemas de definición para almacenar y mostrar metadatos relevantes sobre tus entidades. Los esquemas tienen reglas de validación integradas para asegurar que solo se acepten valores válidos. Puedes ver advertencias en la pestaña Definición en el panel lateral del Software Catalog para cualquier servicio seleccionado.

Un diagrama de flujo que muestra cómo los componentes del Software Catalog se conectan entre sí y con tu entorno en la nube.

Versiones soportadas

Datadog soporta cuatro versiones del esquema de definición:

v3.0: Última versión con un modelo de datos ampliado, soporte para múltiples propietarios, declaración manual de dependencias y características mejoradas para infraestructuras complejas.
v2.2: Soporta anotaciones de usuario para metadatos personalizados y asociaciones de canalización CI para vincular servicios con sus procesos de construcción.
v2.1: Soporta agrupaciones de servicios para una mejor organización e introduce campos adicionales para descripciones de servicio más completas.
v2: Versión más temprana soportada, proporcionando campos esenciales para metadatos y documentación básica de servicios.

Cada versión se basa en la anterior, añadiendo nueva funcionalidad mientras mantiene la compatibilidad hacia atrás. Elige la versión que mejor se adapte a tus necesidades y a la complejidad de tu infraestructura.

Comparación de versiones

Las siguientes características son soportadas en cada versión:

Característica	v3.0	v2.2	v2.1	v2.0
Metadatos Básicos
Agrupaciones de Servicios
Anotaciones de Usuario
Asociaciones de canalización CI
Modelo de Datos Ampliado
Multi-propiedad
Declaración Manual de Dependencias

Para obtener información detallada sobre cada versión, incluidos los esquemas completos y ejemplos de archivos YAML, consulte las páginas de versión individuales en Versiones soportadas.

Detalles de la versión

Características clave

Modelo de datos expandido: v3.0 soporta múltiples tipos de entidades. Puedes organizar tus sistemas utilizando varios componentes como sistemas, servicios, colas y Datastore.
Multi-propiedad: Puedes asignar múltiples propietarios a cualquier objeto definido a través del esquema v3.0 para especificar múltiples puntos de contacto.
Mapeo de relaciones mejorado: Con los datos de APM y USM, puedes detectar automáticamente las dependencias entre componentes. v3.0 soporta la declaración manual para aumentar la topología del sistema detectada automáticamente y asegurar una visión completa de cómo interactúan los componentes dentro de tus sistemas.
Herencia de metadatos del sistema: Los componentes dentro de un sistema heredan automáticamente los metadatos del sistema. Ya no es necesario declarar metadatos para todos los componentes relacionados uno por uno como en v2.1 y v2.2.
Ubicación de código precisa: Agrega el mapeo de la ubicación de tu código para tu servicio. La sección codeLocations en v3.0 especifica las ubicaciones del código con el repositorio que contiene el código y su paths asociado. El atributo paths es una lista de globs que deben coincidir con las rutas en el repositorio.
Registros y eventos filtrados: Declara registros guardados y consultas de eventos para un system a través de las secciones logs y events y visualiza los resultados en la página del Sistema.
Entidades personalizadas: Define tipos de entidades personalizadas más allá de Servicio, Sistema, Datastore, Cola y API. Define los Scorecards y acciones para tipos de entidades específicos.
(Próximamente) Integrations: Integra con herramientas de terceros para obtener dinámicamente información relacionada con tus componentes (por ejemplo, solicitudes de extracción de GitHub, incidentes de PagerDuty y canalizaciones de GitLab). Reporta y escribe reglas de Scorecard contra cualquier fuente de terceros.
(Próximo) Agrupar por producto o dominio: Organizar componentes por producto, permitiendo múltiples capas de agrupamiento jerárquico.

Estructura del esquema

Puedes ver las definiciones completas del esquema en Github.

V3.0 contiene los siguientes cambios respecto a v2.2:

schema_version ahora es apiVersion El campo - kind es nuevo y define el tipo de componente: servicio, cola, Datastore, sistema o API.
dd-service ahora es metadata.name
team ahora es owner y additionalOwners si hay múltiples equipos.
lifecycle, tier, languages y type ahora están bajo spec.
links, contacts, description y tags ahora están bajo metadatos.
application ha sido mejorado para convertirse en su propio tipo: system. Ya no existe como un campo discreto en un servicio.

Ejemplos de archivos YAML

Componente 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

Componente 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

Componentes que son parte de múltiples sistemas.

Si un solo componente es parte de múltiples sistemas, debes especificar ese componente en el YAML para cada sistema. Por ejemplo, si el Datastore orders-postgres es un componente tanto de una flota de postgres como de una aplicación web, especifica dos YAMLs:

Para la flota de postgres (managed-postgres), especifica una definición para 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

Para la aplicación web (shopping-cart), declara una definición separada para 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
---

Herencia de metadatos explícita e implícita

Herencia explícita

El campo inheritFrom instruye a la canalización de ingestión para heredar metadatos de los metadatos de la entidad referenciada por <entity_kind>:<name>.

entity.datadog.yaml

inheritFrom:<entity_kind>:<name>

Herencia implícita

Los componentes (kind:service, kind:datastore, kind:queue, kind:ui) heredan todos los metadatos del sistema al que pertenecen bajo las siguientes condiciones:

Solo hay un sistema definido en el archivo YAML.
La cláusula inheritFrom:<entity_kind>:<name> está ausente en el archivo YAML.

Migrando a v3.0

v3.0 soporta los mismos métodos de creación de metadatos que las versiones anteriores, incluyendo Github, API, Terraform, Backstage, ServiceNow y la UI. Sin embargo, hay nuevos puntos de conexión de API y un nuevo recurso de Terraform para v3.0.

Documentación de referencia de API

Para crear, obtener y eliminar definiciones para todos los tipos de entidades como puntos de conexión, sistemas, Datastore y colas, consulte la documentación de referencia de la API de Software Catalog.

Características clave

Anotaciones de usuario
Sobrescribiendo el tipo de servicio y los idiomas detectados automáticamente usando type y languages
Asociar la canalización CI con un servicio usando ci-pipeline-fingerprints
Lógica de validación menos restrictiva para contact.type y link.type

Estructura del esquema

El esquema completo está disponible en GitHub.

Ejemplo 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

Documentación de referencia de la API

Para crear, obtener y eliminar definiciones de servicio, consulte la referencia de la API de Service Definitions.
Para crear, obtener y eliminar definiciones para nuevos tipos de componentes como sistemas, Datastore y colas, consulte la referencia de la API de Software Catalog.
Para crear y actualizar reglas y resultados de los Scorecards de servicio, consulte la referencia de la API de Scorecards del Servicio.

Características clave

Nuevos elementos de la UI, como agrupaciones de servicios y campos para application, tier y lifecycle
Application y Teams pueden usarse como variables de agrupamiento en el Software Catalog
Lifecycle el campo indica la etapa de desarrollo para diferenciar entre production, experimental o deprecated servicios
Tier el campo indica la criticidad del servicio para priorizar durante la clasificación de incidentes

Estructura del esquema

El esquema completo está disponible en GitHub.

Ejemplo 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"

Documentación de referencia de la API

Para crear, obtener y eliminar definiciones de servicio, consulte la referencia de la API de Definiciones de Servicio.
Para crear, obtener y eliminar definiciones para nuevos tipos de componentes como sistemas, almacenes de datos y colas, consulte la referencia de la API del Software Catalog.
Para crear y actualizar reglas y resultados del Scorecard del servicio, consulte la referencia de la API de Service Scorecards.

Características clave

Metadatos básicos del servicio
Asociaciones de equipo
Información de contacto
Enlaces externos

Estructura del esquema

El esquema completo está disponible en GitHub.

Ejemplo 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

Documentación de referencia de la API

Para crear, obtener y eliminar definiciones de servicio, consulte la referencia de la API de Definiciones de Servicio.
Para crear, obtener y eliminar definiciones para nuevos tipos de componentes como sistemas, almacenes de datos y colas, consulte la referencia de la API del Software Catalog.
Para crear y actualizar reglas y resultados del Scorecard del servicio, consulte la referencia de la API de Service Scorecards.

Crear extensiones personalizadas

Las extensiones personalizadas están en disponibilidad limitada para todas las versiones del esquema.

Las extensiones personalizadas permiten adjuntar metadatos específicos de la organización a las entidades, habilitando el soporte para herramientas y flujos de trabajo personalizados. Por ejemplo, utiliza el extensions campo para incluir notas de lanzamiento, etiquetas de cumplimiento o modelos de propiedad en tus definiciones de entidad.

Datadog también admite claves de extensión específicas para ciertas características. Estas incluyen:

datadoghq.com/dora-metrics: Define patrones de ruta de código fuente para filtrar commits de Git al calcular métricas DORA.
datadoghq.com/cd-visibility: Controla qué commits se consideran parte de un despliegue en CD Visibility.

El siguiente ejemplo define una extensión personalizada utilizada para gestionar la programación de lanzamientos a través de entornos:

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"

Validación de esquema a través del complemento de IDE

Datadog proporciona un Esquema JSON para definiciones, de modo que cuando editas una definición en un IDE compatible, se ofrecen características como autocompletar y validación.