Descripción general
DORA Metrics rastrea y mide el rendimiento de su entrega de software utilizando eventos de despliegue. Estos eventos impulsan las cuatro métricas clave de DORA Metrics: frecuencia de despliegue, tiempo de entrega de cambios, tasa de fallos en cambios y tiempo de restauración.
Para comenzar a usar DORA Metrics, siga estos pasos:
Configure una fuente de datos de despliegue: Elija cómo desea enviar los eventos de despliegue a Datadog: a través de APM Deployment Tracking o la API/CLI de DORA Metrics.
Enriquezca los despliegues con información de confirmación: Agregue metadatos de Git (URL del repositorio y SHA de confirmación) a sus eventos de despliegue y sincronice su repositorio con Datadog para habilitar los cálculos del tiempo de entrega de cambios.
Personalice la Detección de Fallos en Cambios: DORA Metrics detecta automáticamente los despliegues fallidos mediante reversiones (desplegar una versión anterior) e incluye reglas predeterminadas para patrones comunes de avance como revertir PRs y etiquetas de hotfix. Puede personalizar estas reglas para que coincidan con los flujos de trabajo y patrones de remediación específicos de su equipo.
Una vez configurados, los eventos de despliegue completan automáticamente su panel de DORA Metrics con datos de rendimiento filtrados por equipo, servicio, entorno y etiquetas personalizadas.
Limitaciones
- Cuando seleccione por primera vez una opción de fuente de datos (como APM Deployment Tracking), DORA Metrics comienza a completar los datos a partir de ese momento. Si cambia de la fuente A a la fuente B, y luego vuelve a la fuente A, los datos históricos de la fuente A solo estarán disponibles desde el momento en que se seleccionó por primera vez.
- Los despliegues del mismo servicio no pueden ocurrir en el mismo segundo.
DORA Metrics admite las siguientes fuentes de datos para eventos de despliegue:
Para enviar sus propios eventos de despliegue, utilice la DORA Metrics API o el comando datadog-ci dora deployment.
Requisitos
- datadog-ci CLI / API está habilitado como una fuente de datos de eventos Deployments en configuración de DORA.
- Los siguientes atributos son obligatorios:
started_at: La hora en que comenzó el despliegue.finished_at: La hora en que finalizó el despliegue.service: El servicio que se desplegó. Si el servicio proporcionado está registrado en el Catálogo con metadatos configurados (consulte Agregar metadatos), el team del servicio se recupera automáticamente y se asocia con todas las métricas.
Opcionalmente, puede agregar los siguientes atributos a los eventos de despliegue:
repository_url: El repositorio de código fuente del servicio. Obligatorio para calcular el tiempo de entrega de cambios.commit_sha: El SHA del confirmación HEAD asociado con el despliegue. Obligatorio para calcular el tiempo de entrega de cambios.team: Asocie un despliegue con un team diferente al que se encontró automáticamente para el servicio.env: Filtre sus DORA metrics por entorno en la página de DORA Metrics.id: Identifique un despliegue. Este atributo es generado por el usuario; cuando no se proporciona, el punto de conexión devuelve un UUID generado por Datadog.version: La versión del despliegue.custom_tags: Etiquetas en el formato key:value que se pueden usar para filtrar eventos en la página de DORA Metrics.
Ejemplo de API (cURL)
Consulte la documentación de referencia de la DORA Metrics API para obtener la especificación completa y ejemplos de código adicionales.
Para el siguiente ejemplo, reemplace <DD_SITE> en la URL con y ${DD_API_KEY} con su clave de Datadog API:
curl -X POST "https://api.<DD_SITE>/api/v2/dora/deployment" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-d @- << EOF
{
"data": {
"attributes": {
"service": "shopist",
"started_at": 1693491974000000000,
"finished_at": 1693491984000000000,
"git": {
"commit_sha": "66adc9350f2cc9b250b69abddab733dd55e1a588",
"repository_url": "https://github.com/organization/example-repository"
},
"env": "prod",
"team": "backend",
"version": "v1.12.07",
"custom_tags": ["department:engineering", "app_type:backend"]
}
}
}
EOF
Ejemplo de CLI
La herramienta de CLI datadog-ci proporciona un acceso directo para enviar eventos de despliegue dentro de su entorno de Continuous Integration.
Para el siguiente ejemplo, establezca la variable de entorno DD_SITE en y establezca la variable de entorno DD_API_KEY en su clave de Datadog API:
export DD_SITE="<DD_SITE>"
export DD_API_KEY="<DD_API_KEY>"
export deploy_start=`date +%s`
./your-deploy-script.sh
datadog-ci dora deployment --service shopist --env prod \
--started-at $deploy_start --finished-at `date +%s` \
--version v1.12.07 --custom-tags department:engineering \
--custom-tags app_type:backend \
--git-repository-url "https://github.com/organization/example-repository" \
--git-commit-sha 66adc9350f2cc9b250b69abddab733dd55e1a588
La hora de finalización del despliegue se establece automáticamente en ahora si no se proporciona --finished-at.
Si el trabajo de CI del despliegue se está ejecutando en la misma revisión de Git que se está desplegando, git-repository-url y git-commit-sha pueden omitirse y se infieren automáticamente del contexto de CI.
La opción --skip-git puede proporcionarse para deshabilitar el envío de la URL del repositorio y el SHA de la confirmación. Cuando se agrega esta opción, la métrica de tiempo de entrega de cambios no estará disponible.
Si el servicio asociado con el despliegue está registrado en el Catálogo con metadatos configurados (consulte Agregar metadatos), el languages del servicio y cualquier tags se recuperan automáticamente y se asocian con el evento.
Para habilitar el cálculo del tiempo de entrega de cambios, configure la información de Git para sus despliegues y sincronice los metadatos de su repositorio con Datadog. Esto permite que DORA Metrics realice un seguimiento de cuánto tiempo tardan las confirmaciones desde su creación hasta su despliegue.
Datadog necesita acceso a la información de Git (URL del repositorio y SHA de confirmación) de confirmación HEAD asociado con su despliegue. Los requisitos difieren según su fuente de datos de despliegue:
Para los despliegues identificados a través de APM Deployment Tracking, asegúrese de que la telemetría de su aplicación, en forma de trazas, esté etiquetada con información de Git:
Nota: Para los despliegues rastreados por APM, el tiempo de entrega de cambios se calcula desde la creación de la confirmación hasta que la confirmación se observa por primera vez en una nueva versión. La métrica Deploy Time no está disponible.
Para los despliegues rastreados por la DORA Metrics API o el comando datadog-ci dora deployment, asegúrese de que:
- Los atributos
repository_url y commit_sha se incluyan en la carga útil de los eventos de despliegue
Datadog necesita acceso a los metadatos de su repositorio (confirmaciones, rutas de archivo) para recuperar todas las confirmaciones desplegadas entre un despliegue y el anterior. Elija el método de sincronización según su proveedor de Git:
Flujos de trabajo de GitHub que se ejecutan en
pull_request el activador no es compatible actualmente con la integración de GitHub.
Si está utilizando el
pull_request activador, utilice el método alternativo.
Si la integración de GitHub aún no está instalada, instálelo en el mosaico de integración de GitHub.
Al configurar la aplicación de GitHub:
- Seleccione al menos Read permisos de repositorio para Contents y Pull Requests.
- Suscríbase al menos a los eventos Push, PullRequest y PullRequestReview.
Para confirmar que la configuración es válida, seleccione su aplicación de GitHub en el mosaico de integración de GitHub y verifique que la tabla Datadog Features muestre que Pull Request Information cumple con todos los requisitos.
Si la integración de código fuente de GitLab aún no está instalada, instálela en el mosaico de integración de código fuente de GitLab.
Nota: El contexto del token de acceso personal de la cuenta de servicio debe ser al menos read_api.
Manejo de grupos y subgrupos de GitLab
Si sus repositorios están organizados bajo grupos o subgrupos de GitLab (por ejemplo,
https://gitlab.com/my-org/group(/subgroup)/repo),
es posible que la detección automática de la ruta del servicio no se resuelva correctamente debido a la estructura de grupos anidados de GitLab.
Para asegurarse de que las métricas DORA manejen correctamente las rutas del código fuente de su servicio,
puede utilizar la siguiente configuración en la definición de su servicio:
extensions:
datadoghq.com/dora-metrics:
source_patterns:
# All paths relative to the repository URL provided with the deployment
- **
# or specific paths related to this service (for monorepos)
- src/apps/shopist/**
- src/libs/utils/**
Puede cargar los metadatos de su repositorio de Git con el comando datadog-ci git-metadata upload.
Cuando se ejecuta este comando, Datadog recibe la URL del repositorio, el SHA de confirmación de la rama actual y una lista de rutas de archivos rastreados.
Ejecute este comando en CI para cada nueva confirmación. Si se ejecuta una implementación para un SHA de confirmación específico, asegúrese de que el comando datadog-ci git-metadata upload se ejecute para esa confirmación antes de que se envíe el evento de implementación.
No proporcione la --no-gitsync opción a la datadog-ci git-metadata upload comando.
Cuando se incluye esa opción, la información de confirmación no se envía a Datadog y la métrica de tiempo de entrega de cambios no se calcula.
Puede validar la configuración correcta del comando verificando la salida del comando. Un ejemplo de una salida correcta es:
Reporting commit 007f7f466e035b052415134600ea899693e7bb34 from repository git@github.com:organization/example-repository.git.
180 tracked file paths will be reported.
✅ Handled in 0.077 seconds.
Manejo de múltiples servicios en el mismo repositorio
Si el código fuente de múltiples servicios está presente en el mismo repositorio, se necesitan acciones adicionales para garantizar que el tiempo de entrega de cambios se calcule teniendo en cuenta solo las confirmaciones que afectan al servicio específico que se está implementando.
Para filtrar las confirmaciones medidas solo a aquellas que afectan al servicio, especifique los patrones de ruta de archivo glob del código fuente en la definición de servicio.
Si la definición del servicio contiene una URL completa de GitHub o GitLab a la carpeta de la aplicación, se utiliza automáticamente un único patrón de ruta. El tipo de enlace debe ser repo y el nombre del enlace debe ser “Source” o el nombre del servicio (shopist en los ejemplos a continuación).
Ejemplo (versión de esquema v2.2):
links:
- name: shopist
type: repo
provider: github
url: https://github.com/organization/example-repository/tree/main/src/apps/shopist
links:
- name: shopist
type: repo
provider: gitlab
url: https://gitlab.com/organization/example-repository/-/tree/main/src/apps/shopist?ref_type=heads
links:
- name: shopist
type: repo
provider: azure
url: https://dev.azure.com/organization/project/_git/example-repository?path=/src/apps/shopist
Las DORA Metrics para el servicio shopist solo consideran las confirmaciones de Git que incluyen cambios dentro de src/apps/shopist/**. Puede configurar un control más granular del filtrado con extensions[datadoghq.com/dora-metrics].Ejemplo (versión de esquema v2.2):
extensions:
datadoghq.com/dora-metrics:
source_patterns:
- src/apps/shopist/**
- src/libs/utils/**
Las DORA Metrics para el servicio shopist solo consideran las confirmaciones de Git que incluyen cambios dentro de src/apps/shopist/** o src/libs/utils/**.
Si las dos entradas de metadatos están definidas para un servicio, solo se considera extensions[datadoghq.com/dora-metrics] para filtrar las confirmaciones.
Personalizar la Detección de fallos en cambios
Las DORA Metrics identifican automáticamente las implementaciones fallidas para calcular la tasa de fallos en cambios y el tiempo de recuperación de implementaciones fallidas.
Cómo funciona
Change Failure Detection funciona de forma inmediata al identificar las implementaciones de corrección y vincularlas con la implementación específica que están corrigiendo.
Detección automática (no se necesita configuración):
- Rollbacks: Se detectan automáticamente cuando se vuelve a implementar una versión previamente desplegada.
Reglas personalizadas (personalizables):
- Rollforwards: Se detectan mediante reglas predeterminadas que coinciden con patrones comunes como revert PRs y etiquetas de hotfix. Puede personalizar estas reglas en la DORA settings para que coincidan con los flujos de trabajo y los patrones de corrección específicos de su equipo.
Para obtener información detallada sobre cómo funciona la detección y cómo personalizar las reglas, consulte la Change Failure Detection documentation.
Lecturas adicionales
Documentación, enlaces y artículos útiles adicionales: