Añadir comandos personalizados a traces (trazas) de pipelines

Documentos > Continuous Integration Visibility > CI Pipeline Visibility en Datadog > Añadir comandos personalizados a traces (trazas) de pipelines

Los comandos personalizados proporcionan una forma de rastrear comandos individuales en tus pipelines de CI, lo que te permite medir el tiempo que tarda tu comando sin tener en cuenta las acciones de configuración o desmontaje que podría tener el job (generic) (por ejemplo, la descarga de imágenes de Docker o la espera de un nodo disponible en una infraestructura basada en Kubernetes). Estos spans (tramos) aparecen como parte de la trace (traza) del pipeline:

Detalles de un único pipeline con comandos personalizados

Compatibilidad

Los comandos personalizados funcionan con los siguientes proveedores de CI:

GitHub.com (SaaS) con datadog-ci CLI >= 2.40. Para enviar comandos personalizados en GitHub Actions, consulta Problema conocido con Github Actions.
GitLab (SaaS o autoalojado >= 14.1) con datadog-ci CLI >= 2.40.
Jenkins con el complemento de Datadog >= v3.2.0
CircleCI
Azure DevOps Pipelines con datadog-ci CLI >= 2.40.
AWS Codepipeline con datadog-ci CLI >= 2.40. Sigue Añadir comandos personalizados para configurar comandos personalizados en AWS Codepipeline.
Buildkite con datadog-ci CLI >= 2.40.

Instalar CI CLI de Datadog

Instala la datadog-ci (>=v0.17.0) CLI globalmente con npm:

npm install -g @datadog/datadog-ci

Consulta Más formas de instalar la CLI en el repositorio de datadog-ci para obtener otras opciones de instalación.

Rastrear una línea de comandos

Para rastrear una línea de comandos, ejecuta:

datadog-ci trace [--name <name>] -- <command>

Especifica una clave de API de Datadog válida en la variable de entorno DATADOG_API_KEY. Por ejemplo:


DATADOG_API_KEY=<key> DATADOG_SITE= datadog-ci trace \
--name "Greet" \
-- \
echo "Hello World"

Ajustes de configuración

Estas opciones están disponibles para el comando datadog-ci trace (traza):

--name: Muestra el nombre del comando personalizado.
Predeterminado: el mismo valor que <command>
Ejemplo: Wait for DB to be reachable
--tags: Pares clave-valor con el formato key:value que se adjuntarán al comando personalizado (el parámetro --tags puede especificarse varias veces). Al especificar tags (etiquetas) con DD_TAGS, sepáralas con comas (por ejemplo, team:backend,priority:high).
**Variable de entorno DD_TAGS
Predeterminada: (ninguna)
Ejemplo: team:backend
Nota: Las tags (etiquetas) especificadas con --tags y con la variable de entorno DD_TAGS se fusionan. Si la misma clave aparece en --tags y en DD_TAGS, el valor de la variable de entorno DD_TAGS tiene prioridad.
--measures: Pares clave-valor con el formato key:value que se adjuntarán al comando personalizado como valores numéricos (el parámetro --measures puede especificarse varias veces).
(Requiere datadog-ci >=v2.35.0)
Predeterminado: (ninguno)
Ejemplo: size:1024
--no-fail: Evita que datadog-ci falle incluso si se ejecuta en un proveedor CI no admitido. En este case (incidencia), el comando se ejecuta y no se informa de nada a Datadog.
Predeterminado: false
--dry-run: Evita que datadog-ci envíe el span (tramo) personalizado a Datadog. Se realizan todos los demás checks.
Predeterminado: false
Argumentos posicionales: El comando que se lanza y se rastrea.

Se admiten las siguientes variables de entorno:

DATADOG_API_KEY (Obligatorio): Clave de API de Datadog utilizada para autenticar las solicitudes.
Predeterminada: (ninguna)

Rastrear un bloque de comandos

Es posible rastrear varias líneas de comandos a la vez especificando manualmente las marcas de tiempo de inicio y fin (o la duración).

el span (tramo) de la trace (traza) de datadog-ci [--name <name>] [--start-time <timestamp-ms>] [--end-time <timestamp-ms>] # [--duration <duration-ms>] puede utilizarse en lugar de la hora de inicio/fin

Especifica una clave de API de Datadog válida en la variable de entorno DATADOG_API_KEY. Por ejemplo:


DATADOG_API_KEY=<key> DATADOG_SITE= datadog-ci trace span \
--name "Build Step" \
--duration 10000

Ajustes de configuración

Estas opciones están disponibles para el comando datadog-ci trace (traza) span (tramo):

--name: Muestra el nombre del span (tramo) personalizado.
Ejemplo: Build step (UI) / paso (generic)
--start-time: Marca de tiempo en milisegundos desde la época UNIX que representa la hora de inicio del span (tramo).
Nota: Hay dos formas de especificar la hora de inicio y fin, con --start-time y --end-time o con --duration.
--end-time: Marca de tiempo en milisegundos desde la época UNIX que representa la hora de finalización del span (tramo).
Nota: Hay dos formas de especificar la hora de inicio y fin, con --start-time y --end-time o con --duration.
--duration: Duración en milisegundos. Usando esto, la hora de finalización es la hora actual en que se ejecuta este comando.
Nota: Hay dos formas de especificar la hora de inicio y fin, con --start-time y --end-time o con --duration.
--tags: Pares clave-valor con el formato key:value que se adjuntarán al span (tramo) personalizado (el parámetro --tags puede especificarse varias veces). Al especificar tags (etiquetas) con DD_TAGS, sepáralas con comas (por ejemplo, team:backend,priority:high).
**Variable de entorno DD_TAGS
**Predeterminada (ninguna)
Ejemplo: team:backend
Nota: Las etiquetas especificadas con --tags y con la variable de entorno DD_TAGS se fusionan. Si la misma clave aparece en --tags y en DD_TAGS, el valor de la variable de entorno DD_TAGS tiene prioridad.
--measures: Pares clave-valor con el formato key:value que se adjuntarán al span (tramo) personalizado como valores numéricos (el parámetro --measures puede especificarse varias veces).
(Requiere datadog-ci >=v2.35.0)
Predeterminado: (ninguno)
Ejemplo: size:1024
--dry-run: Evita que datadog-ci envíe el span (tramo) personalizado a Datadog. Se realizan todos los demás checks.
Predeterminado: false

Se admiten las siguientes variables de entorno:

DATADOG_API_KEY (Obligatorio): clave de API de Datadog utilizada para autenticar las solicitudes.
Predeterminada: (ninguna)

Problema conocido con las GitHub Actions

A partir de la versión datadog-ci 4.1.1 , no se requiere acción adicional, incluso cuando se utilizan nombres personalizados o estrategias de matriz.

Para versiones de datadog-ci anteriores a la 4.1.1

Si estás utilizando datadog-ci versión 2.29.0 a 4.1.0 y el nombre de job (generic) no coincide con la entrada definida en el archivo de configuración de workflow (UI) / proceso (generic) (el ID de job (generic) de GitHub), es necesario exponer la variable de entorno DD_GITHUB_JOB_NAME, apuntando al nombre de job (generic). Por ejemplo:

Si se cambia el nombre de job (generic) con la propiedad de nombre:

jobs:
  build:
    name: My build job name
    env:
      DD_GITHUB_JOB_NAME: My build job name
    steps:
    - run: datadog-ci trace ...

Si se utiliza la estrategia de matriz, GitHub genera varios nombres de job (generic) añadiendo los valores de matriz al final del nombre de job (generic), entre paréntesis. La variable de entorno DD_GITHUB_JOB_NAME debe entonces condicionarse a los valores de la matriz:

jobs:
  build:
    strategy:
      matrix:
        version: [1, 2]
        os: [Linux, macos]
    env:
      DD_GITHUB_JOB_NAME: build (${{ matrix.version }}, ${{ matrix.os }})
    steps:
    - run: datadog-ci trace ...

Solucionar problemas

Carga útil demasiado grande

El límite de tamaño es aproximadamente 4MB. La causa más común de este error son las tags (etiquetas) demasiado grandes. Utiliza la opción --dry-run para ver el contenido del comando rastreado antes de enviarlo a Datadog.

Referencias adicionales

Más enlaces, artículos y documentación útiles:

Solucionar problemas de CI VisibilityDOCUMENTACIÓN