datadog-cli

Visión general de la skill datadog-cli

La skill datadog-cli ayuda a un agente a usar Datadog desde la línea de comandos para trabajo práctico de observabilidad: buscar logs, seguir trazas de solicitudes, consultar métricas, listar servicios y gestionar dashboards. Encaja especialmente bien para ingenieros, equipos de SRE y plataforma, y personas que responden a incidentes con ayuda de IA que ya tienen acceso a Datadog y quieren hacer triage más rápido sin depender de navegar manualmente por la UI.

Para qué sirve datadog-cli

Usa datadog-cli cuando el trabajo real no es “resumir Datadog”, sino “investigar un síntoma en producción con comandos repetibles”. La skill rinde mejor cuando necesitas:

• acotar un incidente por servicio, tipo de error o ventana temporal
• pasar de logs al contexto de una traza
• comprobar si un pico es nuevo o forma parte del comportamiento normal
• extraer métricas rápidamente para un servicio o entorno
• inspeccionar o actualizar dashboards con flujos guiados por CLI

Usuarios para los que mejor encaja

Esta datadog-cli skill encaja con usuarios que:

• ya usan Datadog para logs, métricas, trazas o dashboards
• quieren que un agente genere comandos correctos en vez de sugerencias vagas de búsqueda
• necesitan flujos de triage de incidentes, no consejos genéricos de observabilidad
• se sienten cómodos aportando nombres de servicio, rangos de tiempo, trace IDs o dashboard IDs

Si no tienes claves de Datadog o no conoces las convenciones de servicios y tags de tu entorno, la configuración y la calidad del prompt van a influir más que la skill en sí.

Por qué esta skill es más útil que un prompt genérico

Un prompt normal podría decir “mira los logs en Datadog”. Esta skill le da al agente una ruta a nivel de comando: logs search, logs tail, logs trace, logs context, logs patterns, logs compare, metrics query, errors, services y operaciones sobre dashboards. Además, remite a la documentación de referencia que realmente importa para ejecutar bien, sobre todo la sintaxis de consultas y las advertencias al actualizar dashboards.

Principales bloqueos de adopción que conviene conocer primero

Los principales bloqueos son operativos, no conceptuales:

• DD_API_KEY y DD_APP_KEY son obligatorios
• las cuentas de Datadog fuera de EE. UU. pueden necesitar --site, por ejemplo datadoghq.eu
• los resultados dependen mucho de usar correctamente la sintaxis de consultas de Datadog
• las actualizaciones de dashboards son destructivas si se omiten campos

Esas son las primeras comprobaciones que deberías hacer antes de juzgar la calidad de datadog-cli usage.

Cómo usar la skill datadog-cli

Instalación y contexto de ejecución de datadog-cli

La skill en sí vive en softaworks/agent-toolkit, pero el CLI real que enseña al agente a ejecutar es:

npx @leoflores/datadog-cli <command>

Configura primero las credenciales:

export DD_API_KEY="your-api-key"
export DD_APP_KEY="your-app-key"

Para sitios de Datadog fuera de EE. UU., pasa --site:

npx @leoflores/datadog-cli logs search --query "*" --site datadoghq.eu

Si estás valorando una datadog-cli install práctica, la dependencia que debes validar es el CLI externo junto con un acceso funcional a la API de Datadog.

Lee estos archivos antes del primer uso real

Esta skill depende de referencias más de lo habitual. Léelos en este orden:

1. SKILL.md
2. references/query-syntax.md
3. references/logs-commands.md
4. references/metrics.md
5. references/workflows.md
6. references/dashboards.md

Seguir este recorrido evita la mayoría de los errores del primer uso: filtros malos, ventanas temporales débiles y ediciones inseguras de dashboards.

Qué datos necesita la skill para funcionar bien

La datadog-cli skill funciona mejor cuando tu solicitud incluye al menos parte de esto:

• nombre del servicio, del equipo o del entorno
• ventana temporal como 15m, 1h o 24h
• tipo de síntoma: errores, latencia, solicitudes fallidas, regresión tras despliegue
• trace ID, request ID o timestamp si ya lo tienes
• si quieres logs, métricas, dashboards o un flujo de triage
• sitio de Datadog si no es el predeterminado de EE. UU.

Entrada débil: “Revisa Datadog.”
Entrada sólida: “Investiga los errores 5xx de payment-api en prod durante la última hora, compáralos con la hora anterior y luego saca cualquier traza relacionada y las métricas de CPU.”

Convierte un objetivo difuso en un prompt útil para datadog-cli

Un buen prompt de datadog-cli guide debería indicarle al agente tanto el objetivo como las dimensiones con las que acotar.

Prueba este patrón:

Use datadog-cli for Observability triage.
Goal: identify why checkout failures increased after the last deploy.
Scope: service:payment-api env:prod
Time: last 1h, compare with previous 1h
Need: error summary, common log patterns, likely trace IDs, and key metrics
Site: datadoghq.eu

Por qué funciona:

• le da al agente un flujo de trabajo, no un único comando
• incluye tags de consulta que el CLI realmente puede usar
• evita que el agente busque con un alcance demasiado amplio

Mejores primeros comandos para tareas habituales

Para triage de incidentes, empieza en amplio y luego ve cerrando el foco:

npx @leoflores/datadog-cli errors --from 1h --pretty
npx @leoflores/datadog-cli logs compare --query "status:error" --period 1h --pretty
npx @leoflores/datadog-cli logs patterns --query "status:error" --from 1h --pretty

Después, acótalo a un servicio:

npx @leoflores/datadog-cli logs search --query "service:payment-api status:error env:prod" --from 1h --pretty

Si ya tienes una traza:

npx @leoflores/datadog-cli logs trace --id "TRACE_ID" --from 24h --pretty

Para revisar la salud del servicio:

npx @leoflores/datadog-cli metrics query --query "avg:system.cpu.user{env:prod,service:payment-api}" --from 1h --pretty

La sintaxis de consulta importa más de lo que suele pensar quien usa datadog-cli

Muchos resultados flojos en datadog-cli usage en realidad son problemas de calidad de la consulta. La skill depende de la sintaxis de búsqueda de Datadog, por ejemplo:

• service:api status:error
• @http.status_code:>=500
• service:api OR service:payment
• @duration:[1000 TO 5000]
• -status:info

Si conoces tus campos, inclúyelos explícitamente. Si no, pídele al agente que empiece con consultas de descubrimiento más amplias y que luego las ajuste según los atributos devueltos.

Flujo práctico de datadog-cli para respuesta a incidentes

Un bucle sólido de investigación con datadog-cli es:

1. obtener una visión general de errores con errors
2. comparar el periodo actual con el anterior usando logs compare
3. agrupar fallos repetidos con logs patterns
4. acotar por servicio y entorno con logs search
5. inspeccionar la actividad alrededor con logs context
6. pasar al flujo distribuido con logs trace
7. confirmar señales de recursos o throughput con metrics query

Esto es mucho mejor que pedir una y otra vez “más logs”, porque cada comando responde a una pregunta diagnóstica distinta.

Los dashboards requieren una precaución extra

La nota de seguridad más importante de este repo es que dashboards update reemplaza el dashboard completo, no solo los campos modificados. Si se omiten campos como variables de plantilla, descripción o lista de notificaciones, pueden desaparecer.

Antes de cualquier actualización, el flujo seguro es:

1. exportar el dashboard a un archivo temporal con --output
2. conservar los campos existentes
3. actualizar usando la estructura completa retenida

Eso hace que la datadog-cli skill sea adecuada para trabajar con dashboards solo si mantienes una disciplina estricta de copias de respaldo y actualizaciones con el estado completo.

Consejos de calidad de salida que sí cambian el resultado

Para obtener mejores respuestas del agente:

• especifica si quieres descubrimiento, explicación o comandos exactos
• incluye juntos los tags de servicio y entorno siempre que puedas
• empieza con una ventana temporal acotada; amplíala solo si hace falta
• pide comparación con un periodo anterior cuando evalúes regresiones
• usa un trace ID o timestamp si ya lo tienes
• pide --pretty cuando importe la revisión humana

La mayor mejora de calidad suele venir de dar un objetivo de consulta preciso, no de pedir un análisis más largo.

Cuándo usar logs frente a métricas o dashboards

Usa logs cuando necesites eventos concretos, errores o detalles de solicitudes.
Usa métricas cuando necesites tendencias, uso de recursos o señales de tasa/latencia.
Usa dashboards cuando necesites contexto operativo ya existente o quieras empaquetar una vista para un equipo.

Si le pides al agente las tres cosas a la vez, indícale cuál es el objetivo de decisión: causa raíz, alcance del impacto, comprobación de regresión o creación de dashboard.

Preguntas frecuentes sobre la skill datadog-cli

¿datadog-cli es buena opción para principiantes?

Sí, si ya tienes acceso a Datadog y manejas conceptos básicos como servicios, tags y ventanas temporales. No, si todavía estás aprendiendo qué representan logs, trazas y métricas. La skill reduce la parte de adivinar comandos, pero no elimina la necesidad de conocer los nombres de tus entornos ni las convenciones de observabilidad de tu organización.

¿Qué la diferencia de usar directamente la UI de Datadog?

datadog-cli es mejor cuando quieres pasos de investigación repetibles, scriptables y generados por un agente. Es especialmente útil para triage rápido, depuración guiada por prompts y compartir comandos exactos. La UI sigue siendo mejor para exploración visual profunda y navegación ad hoc.

¿Cuándo no encaja bien datadog-cli?

No uses esta skill si:

• tu organización bloquea el uso de claves API de Datadog
• necesitas funciones exclusivas de la UI que no estén expuestas por el flujo del CLI
• buscas teoría general de observabilidad en lugar de ejecución específica en Datadog
• no puedes dar suficiente contexto para que el agente construya consultas válidas

¿Necesito instalar algo además de la skill?

Sí. La dependencia crítica en tiempo de ejecución es el Datadog CLI invocado así:

npx @leoflores/datadog-cli <command>

También necesitas DD_API_KEY y DD_APP_KEY. En algunas cuentas, además debes pasar --site.

¿datadog-cli es solo para Observability o también puede cambiar cosas?

Principalmente ayuda a inspeccionar e investigar, pero los comandos de dashboards pueden modificar estado. Ahí es donde más importa la cautela. Lee references/dashboards.md antes de permitir cualquier flujo de actualización.

¿Es mejor que pedirle a un agente “revisa los logs”?

Sí, porque la skill le da al agente familias de comandos concretas y documentación de referencia. Eso suele traducirse en un acotado más rápido, menos consultas mal formadas y flujos de incidentes más útiles que un prompting libre y genérico.

Cómo mejorar la skill datadog-cli

Empieza los prompts con restricciones operativas

La forma más rápida de mejorar la salida de datadog-cli es incluir las restricciones que el CLI realmente necesita:

• sitio de Datadog
• entorno
• nombres de servicio
• rango temporal
• identificadores como trace ID o dashboard ID
• si la tarea es solo de lectura o si puede modificar dashboards

Sin eso, el agente suele caer en comandos demasiado amplios y con poca señal.

Pide un flujo de trabajo, no solo un comando

Un fallo habitual es pedir una única consulta cuando el problema necesita una secuencia. Mejor prompt:

Use datadog-cli to triage a spike in 5xx responses for service:checkout in env:prod over the last hour.
First compare against the prior hour, then identify top error patterns, then pull relevant traces, then check CPU and memory metrics.

Esto produce mejores investigaciones porque encaja con las referencias de flujos del repo.

Aporta ingredientes de consulta más sólidos

Las buenas entradas incluyen campos reales de Datadog:

• service:payment-api
• env:prod
• @http.status_code:>=500
• @error.kind:TimeoutError
• @duration:>=1000

Si solo das lenguaje natural como “la API va lenta”, el agente tiene que adivinar nombres de campos y filtros. Las entradas a nivel de campo llevan a un mejor datadog-cli usage.

Gestiona las ediciones de dashboards con un prompt orientado a seguridad

Si tu tarea toca dashboards, exige explícitamente un flujo de backup primero:

Use datadog-cli to update dashboard abc-def-ghi, but first export the current dashboard to a temp file, preserve template variables and description, and show the exact safe update command.
Do not produce a partial update.

Esto reduce de forma notable el mayor riesgo destructivo de la skill.

Itera después de la primera salida en vez de ampliar a ciegas

Después del primer conjunto de comandos, mejora el resultado acotando:

• de todos los errores a un solo servicio
• de 24h a la ventana exacta del fallo
• de logs genéricos a agrupación por patrones
• del síntoma a evidencia a nivel de traza
• de logs a métricas de confirmación

Esto funciona mejor que pedirle al agente “más detalle”, que a menudo solo amplía el ruido.

Errores habituales que conviene evitar

Los problemas más frecuentes de adopción y calidad de salida son:

• falta de DD_API_KEY o DD_APP_KEY
• olvidar --site en Datadog fuera de EE. UU.
• usar una sintaxis de consulta débil o inválida
• buscar primero en un rango temporal demasiado amplio
• tratar la actualización de dashboards como si fuera un parche y no un reemplazo completo
• pedir ayuda de observabilidad sin nombrar el servicio o entorno afectado

Qué revisar en el repo cuando datadog-cli da resultados flojos

Si el agente suena genérico, vuelve a:

• references/query-syntax.md para ganar precisión en filtros
• references/logs-commands.md para elegir mejor el comando
• references/workflows.md para el orden de investigación
• references/dashboards.md para patrones seguros de modificación

Ese recorrido suele corregir prompts pobres más rápido que reescribir la solicitud completa desde cero.

La mejor forma de evaluar datadog-cli después de la instalación

Una prueba de aceptación práctica para datadog-cli install es:

1. ejecutar un logs search conocido
2. ejecutar un metrics query acotado
3. probar un comando de flujo como errors o logs patterns
4. confirmar el comportamiento de --site si estás fuera de EE. UU.
5. evitar escrituras en dashboards hasta verificar el flujo de backup

Si todo eso funciona, la datadog-cli skill probablemente ya esté lista para trabajo real de incidentes y observabilidad.