Definition Schema v3.0

Información general

Schema v3.0 introduce varias funciones nuevas y mejoras para ofrecer más flexibilidad y definiciones detalladas.

Características principales

Modelo de datos ampliado: la versión 3.0 admite varios tipos de entidades. Puedes organizar tus sistemas utilizando varios componentes, como sistemas servicios, colas y almacenes de datos.
Multipropietario: puedes asignar múltiples propietarios a cualquier objeto definido a través del esquema v3.0 para especificar múltiples puntos de contacto.
Asignación de relaciones mejorada: con los datos de APM y USM, puedes detectar automáticamente las dependencias entre los componentes. v3.0 admite la declaración manual para aumentar la topología del sistema detectada automáticamente y garantizar una visión completa de cómo interactúan los componentes dentro de tus sistemas.
Herencia de los metadatos del sistema: los componentes de un sistema heredan automáticamente los metadatos del sistema. Ya no es necesario declarar uno a uno los metadatos de todos los componentes relacionados, como en las versiones 2.1 y 2.2.
Localización de código precisa: añade la asignación de tu localización de código para tu servicio. La sección codeLocations en v3.0 especifica las localizaciones del código con el repositorio que contiene el código y sus paths asociadas. El atributo paths es una lista de globs que debe coincidir con las rutas en el repositorio.
Entidades personalizadas: define los tipos de entidad personalizados que no sean Servicio, Sistema, Almacén de datos, Colas y API. Limita las scorecards y acciones a tipos de entidad específicos.
(En vista previa) Integraciones: integra con herramientas de terceros para obtener dinámicamente información relacionada con tus componentes (por ejemplo, solicitudes pull de GitHub, incidentes de PagerDuty y pipelines de GitLab). Informa y escribe reglas de scorecard contra cualquier fuente de terceros.
Agrupar por producto o dominio: organiza los componentes por producto, permitiendo múltiples capas de agrupación jerárquica.

Elige la Vista previa para obtener la última versión de Software Catalog.

Metadata Schema v3.0

Entity Definition Schema es una estructura que contiene información básica sobre una entidad. Consulta el esquema completo en GitHub.

En la versión 3.0, el campo aplicación se ha sustituido por sistema en la documentación para ajustarse a la terminología actualizada del esquema público.

Ejemplo de YAML para `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

Ejemplo de YAML para `kind:custom.library`

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

Especificar componentes comunes que forman parte de varios sistemas

Si un único componente forma parte de varios sistemas, debes especificar dicho componente en el YAML de cada sistema. Por ejemplo, si el almacén de datos orders-postgres es un componente tanto de una flota postgres como de una aplicación web, especifica dos YAML:

Para la flota 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 aparte 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 explícita e implícita de metadatos

Herencia explícita

entity.datadog.yaml

inheritFrom:<entity_kind>:<name>

El campo inheritFrom indica al pipeline de ingesta que hereda los metadatos de los metadatos de la entidad a la que hace referencia <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 en 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.

Endpoints de la API v3.0

Para ver los endpoints de la API v3.0, consulta la última documentación de la API.

Esquema general

Puedes consultar las definiciones completas del esquema en Github. He aquí un resumen de la estructura del esquema:

api_version es la versión del esquema: 2.0, 2.1, 3.0
kind es nuevo y define el tipo de componente: servicio, cola, almacén de datos, sistema o API
metadata incluye el nombre, la descripción, la propiedad, los enlaces (documentación, runbooks, repositorios, contactos, dashboards), y etiquetas
spec incluye el nivel, el ciclo de vida, el lenguaje, el tipo y las relaciones con otros componentes
integrations incluye conexiones con PagerDuty y OpsGenie
Datadog incluye formas de filtrar y enlazar con otros datos de Datadog, como localizaciones de código, pipelines, logs y eventos

Migración a la versión 3.0

v3.0 admite los mismos métodos de creación de metadatos que las versiones anteriores, incluidos Github, API, Terraform, Backstage, ServiceNow y la interfaz de usuario. Sin embargo, hay nuevos endpoints de API y un nuevo módulo de Terraform para v3.0.

Puedes consultar las definiciones completas del esquema en Github. V3.0 contiene los siguientes cambios con respecto a v2.2:

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

Páginas de sistema y API en el Software Catalog

La definición de entidades de kind:system y kind:api crea agrupaciones jerárquicas de entidades que incluyen servicios, colas, almacenes de datos y endpoints. Para definir componentes dentro de un sistema o API, puedes especificar valores para la clave components en el campo spec de la definición v3 de la entidad.

Ejemplo de YAML para kind:system:

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

El sistema definido por el usuario anterior aparece en el Software Catalog como se muestra a continuación. Esta página contiene los datos de relación de los componentes entre el sistema y las dependencias ascendentes y descendentes, así como scorecards, logs y eventos agregados a todos los componentes del sistema.

Página del sistema para el sistema de Recomendación de productos en Software Catalog

Ejemplo de YAML para kind:api:

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

La API definida por el usuario aparece en el Software Catalog como se muestra a continuación. Esta página contiene datos de relación de cómo interactúa la API con las dependencias, los componentes de la API, una vista previa de OpenAPI, y logs y eventos agregados a través de todos los endpoints.