datadog-cli

Visão geral da skill datadog-cli

A skill datadog-cli ajuda um agente a usar o Datadog pela linha de comando em tarefas práticas de observabilidade: pesquisar logs, rastrear requisições, consultar métricas, listar serviços e gerenciar dashboards. Ela é mais indicada para engenheiros, SREs, times de plataforma e responders de incidentes com apoio de IA que já têm acesso ao Datadog e querem fazer a triagem mais rápido, sem precisar clicar manualmente pela interface.

Para que serve o datadog-cli

Use datadog-cli quando o trabalho real não for “resumir o Datadog”, e sim “investigar um sintoma em produção com comandos reproduzíveis”. A skill é mais forte quando você precisa:

• restringir um incidente por serviço, tipo de erro ou janela de tempo
• sair de logs para contexto de trace
• verificar se um pico é novo ou já era normal
• puxar métricas rapidamente de um serviço ou ambiente
• inspecionar ou atualizar dashboards com workflows guiados por CLI

Perfil de usuário ideal

Esta datadog-cli skill combina melhor com quem:

• já usa Datadog para logs, métricas, traces ou dashboards
• quer que um agente gere comandos corretos em vez de sugestões vagas de busca
• precisa de workflows de triagem de incidentes, não de conselhos genéricos sobre observabilidade
• consegue informar nomes de serviços, intervalos de tempo, trace IDs ou dashboard IDs

Se você não tem as chaves do Datadog ou não conhece as convenções de serviço/tag do seu ambiente, a configuração e a qualidade do prompt vão pesar mais do que a skill em si.

Por que esta skill é mais útil do que um prompt genérico

Um prompt comum pode dizer “olhe os logs no Datadog”. Esta skill dá ao agente um caminho em nível de comando: logs search, logs tail, logs trace, logs context, logs patterns, logs compare, metrics query, errors, services e operações de dashboard. Ela também aponta para a documentação de referência que realmente importa para executar corretamente, especialmente a sintaxe de consulta e os avisos sobre atualização de dashboards.

Principais bloqueios de adoção que você deve saber antes

Os principais bloqueios são operacionais, não conceituais:

• DD_API_KEY e DD_APP_KEY são obrigatórios
• contas do Datadog fora dos EUA podem exigir --site, como datadoghq.eu
• os resultados dependem fortemente da sintaxe correta de consulta do Datadog
• atualizações de dashboard são destrutivas se campos forem omitidos

Esses são os primeiros pontos que você deve validar antes de julgar a qualidade de uso do datadog-cli.

Como usar a skill datadog-cli

Instalação e contexto de execução

A skill em si fica em softaworks/agent-toolkit, mas a CLI real que ela ensina o agente a executar é:

npx @leoflores/datadog-cli <command>

Defina as credenciais primeiro:

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

Para sites do Datadog fora dos EUA, passe --site:

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

Para uma decisão prática de datadog-cli install, a dependência que você precisa validar é a CLI externa junto com um acesso funcional à API do Datadog.

Leia estes arquivos antes do primeiro uso real

Esta skill é incomumente guiada por material de referência. Leia nesta ordem:

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

Esse caminho reduz a maior parte dos erros da primeira execução: filtros ruins, janelas de tempo fracas e edições inseguras de dashboard.

Quais entradas a skill precisa para funcionar bem

A datadog-cli skill funciona melhor quando o seu pedido inclui pelo menos parte destes itens:

• nome do serviço, nome do time ou ambiente
• janela de tempo como 15m, 1h ou 24h
• tipo de sintoma: erros, latência, requisições com falha, regressão após deploy
• trace ID, request ID ou timestamp, se você tiver
• se você quer logs, métricas, dashboards ou um workflow de triagem
• site do Datadog, se não for o padrão dos EUA

Entrada fraca: “Verifica o Datadog.”
Entrada forte: “Investigue erros 5xx no payment-api em prod na última hora, compare com a hora anterior e depois puxe traces relacionados e métricas de CPU.”

Transforme um objetivo vago em um prompt utilizável

Um bom prompt de datadog-cli guide deve informar ao agente tanto o objetivo quanto os eixos de recorte.

Experimente este padrão:

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 que isso funciona:

• dá ao agente um workflow, não apenas um comando
• inclui tags de consulta que a CLI realmente consegue usar
• evita que o agente pesquise amplo demais

Melhores primeiros comandos do datadog-cli para tarefas comuns

Para triagem de incidente, comece amplo e depois vá restringindo:

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

Depois, delimite por serviço:

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

Se você já tiver um trace:

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

Para saúde do serviço:

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

A sintaxe de consulta importa mais do que a maioria imagina

Muitos resultados fracos de uso do datadog-cli são, na verdade, problemas de qualidade de consulta. A skill depende da sintaxe de busca do Datadog, como:

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

Se você conhece os campos do seu ambiente, inclua-os explicitamente. Se não conhece, peça ao agente para começar com consultas mais amplas de descoberta e depois apertar o filtro com base nos atributos retornados.

Workflow prático de resposta a incidentes

Um loop forte de investigação com datadog-cli é:

1. obter uma visão geral dos erros com errors
2. comparar o período atual com o anterior usando logs compare
3. agrupar falhas repetidas com logs patterns
4. restringir por serviço/ambiente com logs search
5. inspecionar a atividade ao redor com logs context
6. navegar para o fluxo distribuído com logs trace
7. confirmar sinais de recurso ou throughput com metrics query

Isso é muito melhor do que continuar pedindo “mais logs”, porque cada comando responde a uma pergunta diagnóstica diferente.

Dashboards exigem cuidado extra

A observação de segurança mais importante deste repositório é que dashboards update substitui o dashboard inteiro, não apenas os campos alterados. Se campos como variáveis de template, descrição ou lista de notificações forem omitidos, eles podem ser removidos.

Antes de qualquer atualização, o workflow seguro é:

1. buscar o dashboard para um arquivo temporário com --output
2. preservar os campos existentes
3. atualizar usando a estrutura completa mantida

Isso faz com que a datadog-cli skill seja adequada para trabalho com dashboards apenas se você tiver disciplina com backups e atualizações de estado completo.

Dicas de qualidade de saída que realmente mudam o resultado

Para obter respostas melhores do agente:

• especifique se você quer descoberta, explicação ou comandos exatos
• inclua tags de serviço e ambiente juntas sempre que possível
• escolha primeiro uma janela de tempo limitada; só amplie se necessário
• peça comparação com um período anterior ao avaliar regressões
• prefira informar um trace ID ou timestamp se já tiver isso
• peça --pretty quando a revisão humana importar

O maior ganho de qualidade normalmente vem de dar um alvo de consulta preciso, não de pedir uma análise mais verbosa.

Quando usar logs, métricas ou dashboards

Use logs quando você precisa de eventos concretos, erros ou detalhes de requisição.
Use métricas quando precisa de tendências, uso de recursos ou sinais de taxa/latência.
Use dashboards quando precisa de contexto operacional já existente ou quer empacotar uma visão para um time.

Se você pedir os três de uma vez ao agente, diga qual é o objetivo da decisão: causa raiz, raio de impacto, checagem de regressão ou criação de dashboard.

FAQ da skill datadog-cli

O datadog-cli é bom para iniciantes?

Sim, se você já tem acesso ao Datadog e entende conceitos básicos como serviços, tags e janelas de tempo. Não, se você ainda está aprendendo o que logs, traces e métricas representam. A skill reduz a adivinhação de comandos, mas não elimina a necessidade de conhecer os nomes de ambiente e as convenções de observabilidade da sua operação.

O que diferencia isso de usar a interface do Datadog diretamente?

datadog-cli é melhor quando você quer etapas de investigação reproduzíveis, automatizáveis e geradas por agente. Ele é especialmente útil para triagem rápida, debugging guiado por prompt e compartilhamento de comandos exatos. A UI continua sendo melhor para exploração visual profunda e navegação ad hoc.

Quando o datadog-cli não é uma boa escolha?

Não use esta skill se:

• sua organização bloqueia o uso de chaves de API do Datadog
• você precisa de recursos exclusivos da UI que não estão expostos no workflow da CLI
• você quer teoria ampla de observabilidade em vez de execução específica no Datadog
• você não consegue fornecer contexto suficiente para o agente montar consultas válidas

Preciso instalar algo além da skill?

Sim. A dependência crítica em tempo de execução é a Datadog CLI invocada assim:

npx @leoflores/datadog-cli <command>

Você também precisa de DD_API_KEY e DD_APP_KEY. Em algumas contas, é necessário passar --site.

O datadog-cli serve só para observabilidade ou também pode alterar coisas?

Na maior parte do tempo ele ajuda a inspecionar e investigar, mas os comandos de dashboard podem modificar estado. É aí que o cuidado mais importa. Leia references/dashboards.md antes de permitir qualquer fluxo de atualização.

É melhor do que pedir para um agente “checar os logs”?

Sim, porque a skill dá ao agente famílias de comandos concretas e documentação de referência. Isso geralmente significa recorte mais rápido, menos consultas malformadas e workflows de incidente mais úteis do que um prompting livre e genérico.

Como melhorar a skill datadog-cli

Comece os prompts com restrições operacionais

A forma mais rápida de melhorar a saída do datadog-cli é incluir as restrições de que a CLI realmente precisa:

• site do Datadog
• ambiente
• nomes de serviço
• intervalo de tempo
• identificadores como trace ID ou dashboard ID
• se a tarefa é somente leitura ou se pode modificar dashboards

Sem isso, o agente costuma cair em comandos amplos demais e com pouco sinal.

Peça um workflow, não só um comando

Um modo comum de falha é pedir uma única consulta quando o problema exige uma sequência. Melhor 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.

Isso produz investigações melhores porque se encaixa nos workflows de referência do repositório.

Forneça ingredientes de consulta mais fortes

Boas entradas incluem campos reais do Datadog:

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

Se você fornecer apenas linguagem natural, como “a API está lenta”, o agente terá de adivinhar nomes de campos e filtros. Entradas em nível de campo geram um uso de datadog-cli melhor.

Trate edições de dashboard com um prompt orientado à segurança

Se sua tarefa mexe em dashboards, exija explicitamente um workflow com backup antes:

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.

Isso reduz bastante o maior risco destrutivo da skill.

Itere depois da primeira saída em vez de ampliar às cegas

Depois do primeiro conjunto de comandos, melhore os resultados restringindo:

• de todos os erros para um serviço
• de 24h para a janela exata da falha
• de logs genéricos para agrupamento por padrão
• do sintoma para evidência em nível de trace
• de logs para métricas de confirmação

Isso é melhor do que pedir ao agente “mais detalhes”, o que muitas vezes só amplia o ruído.

Erros comuns que você deve evitar

Os problemas mais comuns de adoção e de saída são:

• falta de DD_API_KEY ou DD_APP_KEY
• esquecer --site para Datadog fora dos EUA
• usar sintaxe de consulta fraca ou inválida
• começar pesquisando uma janela de tempo ampla demais
• tratar atualização de dashboard como se fosse patch, e não substituição completa
• pedir ajuda de observabilidade sem nomear o serviço ou ambiente afetado

O que inspecionar no repositório quando os resultados parecem fracos

Se o agente estiver genérico demais, volte para:

• references/query-syntax.md para precisão de filtros
• references/logs-commands.md para escolha de comandos
• references/workflows.md para ordem de investigação
• references/dashboards.md para padrões seguros de modificação

Esse caminho de leitura normalmente corrige prompts ruins mais rápido do que reescrever a solicitação inteira do zero.

Melhor forma de avaliar o datadog-cli após a instalação

Um teste de aceitação prático para datadog-cli install é:

1. executar um logs search conhecido
2. executar um metrics query com escopo definido
3. testar um comando de workflow como errors ou logs patterns
4. confirmar o comportamento de --site se estiver fora dos EUA
5. evitar gravações em dashboards até validar o workflow de backup

Se tudo isso funcionar, a datadog-cli skill provavelmente está pronta para trabalho real de incidentes e observabilidade.