Este producto no es compatible con el
sitio Datadog seleccionado. (
).
Descripción general
DORA Metrics rastrea y mide el rendimiento de la entrega de software utilizando eventos de implementación. Estos eventos impulsan las cuatro métricas clave de DORA Metrics: frecuencia de implementación, tiempo de entrega de cambios, tasa de fallas en cambios y tiempo para restaurar.
Para comenzar a usar DORA Metrics, sigue estos pasos:
Configura una fuente de datos de implementación: Elige cómo deseas enviar eventos de implementación a Datadog: a través de APM Deployment Tracking o la API/CLI de DORA Metrics.
Enriquece las implementaciones con información de commits: Agrega metadatos de Git (URL del repositorio y SHA del commit) a tus eventos de implementación y sincroniza tu repositorio con Datadog para habilitar los cálculos del tiempo de entrega de cambios.
Personaliza la detección de fallas en cambios: DORA Metrics detecta automáticamente implementaciones fallidas a través de retrocesos (volver a implementar una versión anterior) e incluye reglas predeterminadas para patrones comunes de avance como PRs de reversión y etiquetas de corrección rápida. Puedes personalizar estas reglas para que coincidan con los flujos de trabajo específicos de tu equipo y los patrones de remediación.
(Opcional) Configura el seguimiento de incidentes: Integra datos de incidentes para correlacionar fallas de cambios detectadas con incidentes en producción, proporcionando una vista completa de cómo tus implementaciones afectan la salud del servicio.
Cuando se configura, los eventos de implementación llenan automáticamente tu tablero de DORA Metrics con datos de rendimiento filtrados por equipo, servicio, entorno y etiquetas personalizadas.
Limitaciones
- Cuando seleccionas por primera vez una opción de fuente de datos (como APM Deployment Tracking), DORA Metrics comienza a poblar datos desde ese momento en adelante. Si cambias de la fuente A a la fuente B, y luego regresas a la fuente A, los datos históricos de la fuente A solo están disponibles desde el momento en que fue seleccionada por primera vez.
- Las implementaciones del mismo servicio no pueden ocurrir en el mismo segundo.
DORA Metrics admite las siguientes fuentes de datos para eventos de implementación:
Para enviar tus propios eventos de implementación, utiliza 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 DORA settings.
- Los siguientes atributos son requeridos:
started_at: El momento en que comenzó el despliegue.finished_at: El momento en que finalizó el despliegue.service: El servicio que fue desplegado. Si el servicio proporcionado está registrado en Software Catalog con los metadatos configurados (ver Adding Metadata), el team del servicio se recupera automáticamente y se asocia con todas las métricas.
Opcionalmente, puedes agregar los siguientes atributos a los eventos de despliegue:
repository_url: El repositorio de código fuente del servicio. Requerido para calcular el tiempo de entrega de cambios.commit_sha: El SHA del commit HEAD asociado con el despliegue. Requerido para calcular el tiempo de entrega de cambios.team: Asociar un despliegue con un team diferente al que se encontró automáticamente para el servicio.env: Filtra tus métricas de DORA Metrics por entorno en la página de DORA Metrics.id: Identificar un despliegue. Este atributo es generado por el usuario; cuando no se proporciona, el endpoint devuelve un UUID generado por Datadog.version: La versión del despliegue.custom_tags: Etiquetas en la forma key:value que pueden ser utilizadas para filtrar eventos en la página de DORA Metrics.
Ejemplo de API (cURL)
Consulte la DORA Metrics API reference documentation para la especificación completa y ejemplos de código adicionales.
Para el siguiente ejemplo, reemplace <DD_SITE> en la URL con ${DD_API_KEY} con tu Datadog API Key:
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 CLI datadog-ci proporciona un acceso directo para enviar eventos de despliegue dentro de tu entorno de Continuous Integration.
Para el siguiente ejemplo, establece la variable de entorno DD_SITE en DD_API_KEY en tu Datadog API Key:
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
El tiempo de finalización del despliegue se establece automáticamente al momento actual si no se proporciona --finished-at.
Si el trabajo de CI de despliegue se está ejecutando en la misma revisión de Git que se está desplegando, git-repository-url y git-commit-sha se pueden omitir y se infieren automáticamente del contexto de CI.
La opción --skip-git se puede proporcionar para deshabilitar el envío de la URL del repositorio y el SHA del commit. Cuando se agrega esta opción, la métrica de Lead Time de cambio no estará disponible.
Si el servicio asociado con el despliegue está registrado en el Software Catalog con metadatos configurados (ver Adding Metadata), el languages del servicio y cualquier tags se recuperan automáticamente y se asocian con el evento.
Para habilitar el cálculo del Lead Time de cambio, configura la información de Git para tus implementaciones y sincroniza los metadatos de tu repositorio con Datadog. Esto permite que DORA Metrics rastree cuánto tiempo tardan los commits desde su creación hasta el despliegue.
Datadog necesita acceso a la información de Git (URL del repositorio y SHA del commit) del SHA del commit principal de tu despliegue. Los requisitos difieren según la fuente de datos de tu despliegue:
Para las implementaciones identificadas a través de APM Deployment Tracking, asegúrate de que la telemetría de tu aplicación esté etiquetada con información de Git:
Nota: Para las implementaciones rastreadas por APM, el Lead Time de cambio se calcula desde la creación del commit hasta que el commit se observa por primera vez en una nueva versión. La métrica Deploy Time no está disponible.
Para las implementaciones rastreadas por la DORA Metrics API o el comando datadog-ci dora deployment, asegúrate de lo siguiente:
- Los atributos
repository_url y commit_sha se incluyen en la carga útil de eventos de implementación
Datadog necesita acceso a los metadatos de tu repositorio (commits, rutas de archivos) para recuperar todos los commits desplegados entre un despliegue y el anterior. Elige el método de sincronización según tu proveedor de Git:
Los flujos de trabajo de GitHub que se ejecutan en
pull_request el desencadenador no es compatible actualmente con la integración de GitHub.
Si está utilizando el
pull_request desencadenador, utilice el método alternativo.
Si la integración de GitHub no está instalada, instálela en el GitHub integration tile.
Al configurar la aplicación de GitHub:
- Seleccione al menos Read permisos de repositorio para Contents y Pull Requests.
- Suscríbete al menos a Push, PullRequest y PullRequestReview eventos.
Para confirmar que la configuración es válida, selecciona tu aplicación de GitHub en el GitHub integration tile y verifica 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 no está instalada, instálela en el panel 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),
la detección automática de la ruta del servicio puede no resolverse correctamente debido a la estructura de grupos anidados de GitLab.
Para asegurar que las métricas de DORA manejen correctamente las rutas del código fuente de su servicio,
puede usar 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/**
Si la integración se instaló antes del 10 de marzo de 2026, ejecuta el
script de instalación del webhook nuevamente para ayudar a asegurar que todas las métricas de DORA se calculen correctamente. Si encuentras errores, vuelve a ejecutar el script antes de contactar al soporte.
Si la integración de código fuente de Azure DevOps no está instalada, instálela en el Azure DevOps Source Code integration tile.
Para configurar la integración:
Abra el Azure DevOps Source Code integration tile en Datadog.
Seleccione la pestaña Configuration y haga clic en Connect Microsoft Entra App.
Siga las instrucciones de configuración.
Haga clic en Add Organizations.
Siga los pasos de instalación del repositorio y ejecute el script de configuración. Si no se ejecuta el script, los commits realizados antes de que se cree una solicitud de extracción no estarán asociados con esa solicitud.
Después de que el script se complete, verifique el estado de integración en el panel. Los repositorios y proyectos conectados aparecen en la lista.
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 del commit de la rama actual y una lista de rutas de archivos rastreados.
Ejecute este comando en CI para cada nuevo commit. Si se ejecuta un despliegue para un SHA de commit específico, asegúrese de que se ejecute el comando datadog-ci git-metadata upload para ese commit antes de que se envíe el evento de despliegue.
No proporcione el --no-gitsync opción al datadog-ci git-metadata upload comando.
Cuando se incluye esa opción, la información del commit 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 los commits que afectan al servicio específico que se está desplegando.
Para filtrar los commits medidos solo a aquellos que afectan al servicio, especifica las rutas de los patrones de archivos glob del código fuente en la definición del 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 ya sea ‘Source’ o el nombre del servicio (shopist en los ejemplos a continuación).
Ejemplo (versión del 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 métricas DORA para el shopist servicio solo consideran los commits 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 del esquema v2.2):
extensions:
datadoghq.com/dora-metrics:
source_patterns:
- src/apps/shopist/**
- src/libs/utils/**
Las métricas DORA para el servicio shopist solo consideran los commits de Git que incluyen cambios dentro de src/apps/shopist/** o src/libs/utils/**.
Si se definen dos entradas de metadatos para un servicio, solo se considera extensions[datadoghq.com/dora-metrics] para filtrar los commits.
Personalizar la detección de fallos en cambios
Las métricas DORA identifican automáticamente los despliegues fallidos para calcular la tasa de fallos en cambios y el tiempo de recuperación de despliegues fallidos.
Cómo funciona
La detección de fallos en cambios opera de manera inmediata al identificar los despliegues de remediación y enlazarlos de nuevo al despliegue específico que están remediando.
Detección automática (sin necesidad de configuración):
- Reversiones: Detectadas automáticamente cuando se vuelve a desplegar una versión previamente desplegada.
Reglas personalizadas (personalizables):
- Rollforwards: Detectados a través de reglas predeterminadas que coinciden con patrones comunes como revert PRs y etiquetas de hotfix. Puedes personalizar estas reglas en la configuración de DORA para que coincidan con los flujos de trabajo y patrones de remediación específicos de tu equipo.
Para obtener información detallada sobre cómo funciona la detección y cómo personalizar reglas, consulta la documentación de detección de fallos en cambios.
(Opcional) Configurar el seguimiento de incidentes
Integrar los datos de incidentes proporciona una visión integral de cómo la actividad de despliegue impacta la salud del servicio. Al rastrear incidentes junto con fallas de cambio detectadas automáticamente, se puede correlacionar el rendimiento de entrega con el impacto operativo en el mundo real y entender la historia completa del efecto de la entrega de software en la confiabilidad del servicio.
DORA Metrics admite las siguientes opciones para rastrear incidentes:
DORA Metrics puede identificar y rastrear automáticamente fallas a través de Incidentes de Datadog. Después de que se declaran los incidentes, DORA los utiliza para medir la tasa de fallas de cambio y el tiempo de restauración.
Nota: El tiempo de restauración se mide como la duración total que un incidente pasa en el estado active. Para casos como active → stable → active → stable, incluye todos los períodos active. El tiempo de restauración se muestra solo cuando un incidente está en un estado stable o resolved. Si un incidente resolved se reactiva, la métrica se oculta hasta que esté resolved nuevamente.
Requisitos
- Incidents está habilitado como una fuente de datos de eventos Failures en DORA settings.
Para evitar tener fallas sin etiquetar, Datadog recomienda encarecidamente agregar los siguientes atributos a los incidentes:
Si se proporciona con incidentes, se agrega la etiqueta Severity a los eventos de falla.
Recomendado: En la Configuración de Incidentes, establezca el campo de atributos Prompted en At Resolution para asegurarse de que nunca olvide agregar estos atributos a sus incidentes.
Incluir incidentes históricos
Puede incluir retroactivamente incidentes de los últimos dos años seleccionando Backfill Data en DORA settings, lo que crea fallas a partir de esos incidentes. El llenado de datos puede tardar hasta una hora en completarse.
PagerDuty es una plataforma de gestión de incidentes que proporciona a los equipos de TI visibilidad inmediata de los incidentes, permitiendo respuestas proactivas y efectivas para mantener la estabilidad y resiliencia operativa.
Para integrar tu cuenta de PagerDuty con DORA Metrics:
Habilita PagerDuty como una Failures fuente de datos de eventos en DORA settings.
Navega a Integrations > Developer Tools en PagerDuty y haz clic en Generic Webhooks (v3).
Haz clic en + New Webhook e ingresa los siguientes detalles:
| Variable | Descripción |
|---|
| URL del Webhook | Agregar https://webhook-intake./api/v2/webhook/. |
| Tipo de Contexto | Selecciona el contexto de los incidentes que deseas enviar. Puedes enviar incidentes para un Service específico o Team, o todos los servicios de PagerDuty en tu Account. Dependiendo de tu entorno y nivel de acceso, algunos tipos de contexto pueden no estar disponibles. |
| Descripción | Una descripción ayuda a distinguir el webhook. Agrega algo como Datadog DORA Metrics integration. |
| Suscripción de Eventos | Selecciona los siguientes eventos:
-incident.acknowledged
-incident.annotated
-incident.custom_field_values.updated
-incident.delegated
-incident.escalated
-incident.priority_updated
-incident.reassigned
-incident.reopened
-incident.resolved
-incident.triggered
-incident.unacknowledged |
| Encabezados Personalizados | Haz clic en Add custom header, ingresa DD-API-KEY como el nombre, e ingresa tu clave de API de Datadog como el valor.
Opcionalmente, puedes agregar un entorno a todos los incidentes de PagerDuty enviados desde el webhook creando un encabezado personalizado adicional con el nombre dd_env y el entorno deseado como el valor. |
Para guardar el webhook, haz clic en Add Webhook.
La severidad de la falla en el producto DORA Metrics se basa en la prioridad del incidente en PagerDuty.
Nota: Al crear el webhook, se crea un nuevo secreto que se utiliza para firmar todos los payloads del webhook. Ese secreto no es necesario para que la integración funcione, ya que la autenticación se realiza utilizando la clave de API en su lugar.
Cuando se recibe un evento de incidente para un servicio de PagerDuty específico, Datadog intenta recuperar el servicio y el equipo de Datadog relacionados de cualquier monitor de Datadog que lo haya activado y del Software Catalog.
El algoritmo de coincidencia funciona en los siguientes pasos:
Si el evento de incidente de PagerDuty fue activado desde un monitor de Datadog:
- Si el monitor está en modo de Alerta Múltiple, las métricas y eventos del incidente se emiten con el
env, service y team del grupo alertado. - Si el monitor tiene etiquetas para
env, service o team:env: Si el monitor tiene una sola etiqueta env, las métricas y eventos del incidente se emiten con el entorno.service: Si el monitor tiene una o más etiquetas service, las métricas y eventos del incidente se emiten con los servicios proporcionados.team: Si el monitor tiene una sola etiqueta team, las métricas y eventos del incidente se emiten con el equipo.
Si la URL del servicio del incidente coincide con la URL del servicio de PagerDuty para cualquiera de los servicios en el Software Catalog:
- Si un solo servicio de Datadog coincide, las métricas y eventos del incidente se emiten con el servicio y el equipo.
- Si múltiples servicios de Datadog coinciden, las métricas y eventos del incidente se emiten con el equipo.
Para más información sobre cómo establecer la URL del servicio de PagerDuty para un servicio de Datadog, consulte Use Integrations with Software Catalog.
Si el nombre del servicio de PagerDuty del incidente coincide con un nombre de servicio en el Software Catalog, las métricas y eventos del incidente se emiten con el servicio y el equipo.
Si el nombre del equipo de PagerDuty del incidente coincide con un nombre de equipo en el Software Catalog, las métricas y eventos del incidente se emiten con el equipo.
Si el nombre del servicio de PagerDuty del incidente coincide con un nombre de equipo en el Software Catalog, las métricas y eventos del incidente se emiten con el equipo.
Si no ha habido coincidencias hasta este punto, las métricas y eventos del incidente se emiten con el servicio de PagerDuty y el equipo de PagerDuty proporcionados en el incidente.
Si un incidente se resuelve manualmente en PagerDuty en lugar de a partir de una notificación del monitor, el evento de resolución del incidente no contiene información del monitor y se omite el primer paso del algoritmo de coincidencia.
Para enviar sus propios eventos de falla, use la API de Métricas DORA. Los eventos de falla se utilizan para calcular la tasa de fallas en cambios y el tiempo para restaurar.
Incluya el atributo finished_at en un evento de falla para marcar que la falla está resuelta. Puede enviar eventos al inicio de la falla y después de que se haya resuelto. Los eventos de falla se emparejan por los atributos env, service y started_at.
Requisitos
- datadog-ci CLI / API está habilitado como una fuente de datos de eventos Failures en DORA settings.
- Los siguientes atributos son requeridos:
services o team (al menos uno debe estar presente)started_at
Puede agregar opcionalmente los siguientes atributos a los eventos de falla:
finished_at para * fallas resueltas*. *** Requerido para calcular el tiempo de restauración***id para identificar fallas. Este atributo es generado por el usuario; cuando no se proporciona, el endpoint devuelve un UUID generado por Datadog.name para describir la falla.severityenv para filtrar sus DORA Metrics por entorno en la página DORA Metrics.repository_urlcommit_shaversioncustom_tags: Etiquetas en la forma key:value que se pueden usar para filtrar eventos en la página DORA Metrics.
Consulte la DORA Metrics API reference documentation para la especificación completa y ejemplos de código adicionales.
Ejemplo de API (cURL)
Para la siguiente configuración, reemplace <DD_SITE> con :
curl -X POST "https://api.<DD_SITE>/api/v2/dora/failure" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-d @- << EOF
{
"data": {
"attributes": {
"services": ["shopist"],
"team": "shopist-devs",
"started_at": 1693491974000000000,
"finished_at": 1693491984000000000,
"git": {
"commit_sha": "66adc9350f2cc9b250b69abddab733dd55e1a588",
"repository_url": "https://github.com/organization/example-repository"
},
"env": "prod",
"name": "Web server is down failing all requests",
"severity": "High",
"version": "v1.12.07",
"custom_tags": ["department:engineering", "app_type:backend"]
}
}
}
EOF
Lectura adicional
Más enlaces, artículos y documentación útiles:
