datadog-cli

datadog-cli skill 개요

datadog-cli skill은 Datadog를 커맨드라인에서 활용해 실무형 Observability 작업을 빠르게 처리하도록 돕습니다. 로그 검색, 요청 추적, 메트릭 조회, 서비스 목록 확인, 대시보드 관리까지 CLI 중심으로 수행할 수 있어, UI를 일일이 클릭하지 않고도 더 빠르게 트리아지하려는 엔지니어, SRE, 플랫폼 팀, AI 보조 인시던트 대응자에게 특히 잘 맞습니다. 전제는 이미 Datadog 접근 권한이 있어야 한다는 점입니다.

datadog-cli가 필요한 상황

datadog-cli는 “Datadog를 요약해줘” 같은 막연한 요청보다, “재현 가능한 명령으로 운영 증상을 조사해줘”가 실제 목표일 때 가장 빛납니다. 특히 다음과 같은 상황에서 강합니다.

• 서비스, 에러 유형, 시간 범위로 인시던트를 좁혀갈 때
• 로그에서 trace 컨텍스트로 이어서 추적해야 할 때
• 급증 현상이 새 이슈인지 평소 패턴인지 확인할 때
• 특정 서비스나 환경의 메트릭을 빠르게 뽑아야 할 때
• CLI 기반 워크플로우로 대시보드를 점검하거나 수정할 때

잘 맞는 사용자

이 datadog-cli skill은 다음 사용자에게 적합합니다.

• 이미 Datadog로 로그, 메트릭, 트레이스, 대시보드를 운영 중인 사용자
• 막연한 검색 제안이 아니라, 에이전트가 정확한 명령을 만들어주길 원하는 사용자
• 일반적인 Observability 설명이 아니라 인시던트 트리아지 워크플로우가 필요한 사용자
• 서비스명, 시간 범위, trace ID, dashboard ID 같은 정보를 제공하는 데 익숙한 사용자

반대로 Datadog 키가 없거나 서비스/태그 규칙을 잘 모른다면, skill 자체보다도 초기 설정과 프롬프트 품질이 결과를 더 크게 좌우합니다.

일반 프롬프트보다 이 skill이 더 유용한 이유

보통의 프롬프트는 “Datadog 로그 좀 봐줘” 수준에서 그치기 쉽습니다. 반면 이 skill은 에이전트에게 logs search, logs tail, logs trace, logs context, logs patterns, logs compare, metrics query, errors, services, 그리고 대시보드 작업까지 이어지는 명령 단위 경로를 제공합니다. 또한 정확한 실행에 필요한 참조 문서도 함께 짚어주는데, 특히 쿼리 문법과 대시보드 업데이트 시 주의사항이 중요합니다.

먼저 알아야 할 주요 도입 장애물

핵심 장애물은 개념보다 운영 측면에 있습니다.

• DD_API_KEY와 DD_APP_KEY가 반드시 필요합니다
• 미국 이외 Datadog 계정은 datadoghq.eu 같은 --site 지정이 필요할 수 있습니다
• 결과 품질은 Datadog 쿼리 문법 정확도에 크게 좌우됩니다
• 대시보드 업데이트는 일부 필드를 빼먹으면 파괴적으로 동작할 수 있습니다

따라서 datadog-cli usage 품질을 평가하기 전에, 먼저 이 조건들이 충족되는지 확인하는 것이 우선입니다.

datadog-cli skill 사용 방법

설치와 실행 환경

이 skill 자체는 softaworks/agent-toolkit에 들어 있지만, 에이전트가 실제로 실행하는 CLI는 다음입니다.

npx @leoflores/datadog-cli <command>

먼저 인증 정보를 설정하세요.

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

미국 이외 Datadog 사이트를 사용하는 경우에는 --site를 함께 넘겨야 합니다.

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

실제 datadog-cli install 판단에서는 skill 자체보다, 이 외부 CLI가 정상 동작하는지와 Datadog API 접근이 제대로 열려 있는지를 먼저 검증해야 합니다.

처음 실사용 전에 읽어야 할 파일

이 skill은 유난히 레퍼런스 의존도가 높습니다. 아래 순서대로 읽는 것이 좋습니다.

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

이 순서를 따르면 첫 사용에서 자주 생기는 실수, 예를 들어 잘못된 필터, 부정확한 시간 범위, 위험한 대시보드 수정 같은 문제를 크게 줄일 수 있습니다.

skill이 잘 동작하려면 필요한 입력

datadog-cli skill은 요청에 다음 정보가 일부라도 포함될 때 가장 잘 작동합니다.

• 서비스명, 팀명, 또는 환경
• 15m, 1h, 24h 같은 시간 범위
• 증상 유형: 에러, 지연 시간, 실패 요청, 배포 후 회귀
• 가능하다면 trace ID, request ID, 또는 타임스탬프
• 로그를 볼지, 메트릭을 볼지, 대시보드를 볼지, 혹은 트리아지 워크플로우가 필요한지
• 기본값인 미국 사이트가 아니라면 Datadog site 정보

약한 입력: “Datadog 확인해줘.”
강한 입력: “지난 1시간 동안 prod의 payment-api 5xx 에러를 조사하고, 이전 1시간과 비교한 뒤, 관련 trace와 CPU 메트릭까지 확인해줘.”

거친 목표를 실전용 프롬프트로 바꾸기

좋은 datadog-cli guide 프롬프트는 목표만 말하는 것이 아니라, 어떤 축으로 범위를 좁혀야 하는지까지 알려줘야 합니다.

다음 패턴을 써보세요.

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

이 방식이 잘 먹히는 이유는 다음과 같습니다.

• 단일 명령이 아니라 워크플로우를 에이전트에 제공합니다
• CLI가 실제로 사용할 수 있는 쿼리 태그가 포함됩니다
• 검색 범위를 불필요하게 넓히는 일을 막아줍니다

자주 하는 작업에 적합한 첫 명령

인시던트 트리아지에서는 처음엔 넓게 보고, 그다음 좁혀가는 접근이 좋습니다.

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

그다음 서비스 단위로 범위를 줄입니다.

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

이미 trace가 있다면:

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

서비스 상태를 볼 때는:

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

대부분이 생각하는 것보다 쿼리 문법이 더 중요함

부실한 datadog-cli usage 결과는 실제로는 skill 문제가 아니라 쿼리 품질 문제인 경우가 많습니다. 이 skill은 Datadog 검색 문법에 크게 의존합니다. 예를 들면:

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

필드명을 알고 있다면 명시적으로 넣는 편이 훨씬 좋습니다. 반대로 필드 구조를 잘 모른다면, 처음에는 더 넓은 탐색용 쿼리로 시작한 뒤 반환된 속성을 보고 점차 조여가라고 에이전트에 지시하세요.

datadog-cli 기반 인시던트 대응 실전 워크플로우

datadog-cli로 강한 조사 루프를 만들려면 보통 다음 순서가 좋습니다.

1. errors로 에러 개요를 확인한다
2. logs compare로 현재 구간과 이전 구간을 비교한다
3. logs patterns로 반복되는 실패 패턴을 묶어본다
4. logs search로 서비스/환경 기준으로 범위를 좁힌다
5. logs context로 주변 활동을 함께 본다
6. logs trace로 분산 흐름을 추적한다
7. metrics query로 리소스나 처리량 신호를 교차 확인한다

이 방식은 “로그 좀 더 보여줘”를 반복하는 것보다 훨씬 낫습니다. 각 명령이 서로 다른 진단 질문에 답하기 때문입니다.

대시보드는 특히 더 조심해야 함

이 저장소에서 가장 중요한 안전 경고는 dashboards update가 변경된 필드만 덮어쓰는 방식이 아니라, 대시보드 전체를 교체한다는 점입니다. 따라서 template variables, description, notify list 같은 필드를 빼먹으면 실제로 삭제될 수 있습니다.

업데이트 전 안전한 절차는 다음과 같습니다.

1. --output으로 현재 대시보드를 임시 파일에 저장한다
2. 기존 필드를 그대로 보존한다
3. 보존된 전체 구조를 유지한 채 업데이트한다

즉, 이 datadog-cli skill은 백업과 전체 상태 기반 업데이트를 엄격히 지킬 수 있을 때만 대시보드 작업에 적합합니다.

결과 품질을 실제로 바꾸는 팁

에이전트 답변 품질을 높이려면:

• 탐색이 필요한지, 설명이 필요한지, 정확한 명령이 필요한지 먼저 지정하세요
• 가능하면 service 태그와 env 태그를 함께 주세요
• 처음에는 좁은 시간 범위를 잡고, 필요할 때만 넓히세요
• 회귀 여부를 볼 때는 이전 구간과 비교하도록 요청하세요
• 이미 trace ID나 타임스탬프가 있으면 적극적으로 포함하세요
• 사람이 결과를 검토해야 한다면 --pretty를 요청하세요

대개 가장 큰 품질 향상은 “더 길고 자세한 분석”을 요구할 때가 아니라, 쿼리 대상을 더 정확히 줄 때 나옵니다.

언제 logs를 쓰고, metrics를 쓰고, dashboards를 써야 하나

구체적인 이벤트, 에러, 요청 상세를 봐야 한다면 logs를 쓰세요.
추세, 리소스 사용량, rate/latency 신호를 봐야 한다면 metrics가 맞습니다.
기존 운영 맥락을 확인하거나 팀과 공유할 뷰를 구성해야 한다면 dashboards가 적합합니다.

세 가지를 한 번에 요청할 수도 있지만, 그 경우에는 루트 원인 파악인지, 영향 범위 확인인지, 회귀 점검인지, 대시보드 생성인지처럼 의사결정 목표를 분명히 알려줘야 합니다.

datadog-cli skill FAQ

datadog-cli는 초보자에게도 괜찮은가요?

그렇기도 하고 아니기도 합니다. Datadog 접근 권한이 있고, 서비스·태그·시간 범위 같은 기본 개념을 이미 이해하고 있다면 충분히 유용합니다. 반대로 logs, traces, metrics가 각각 무엇을 의미하는지 아직 익히는 단계라면 적합도가 떨어집니다. 이 skill은 명령 추측 비용을 줄여주지만, 환경 이름이나 Observability 규칙 자체를 대신 알아주지는 않습니다.

Datadog UI를 직접 쓰는 것과 뭐가 다른가요?

datadog-cli는 반복 가능하고 스크립트화 가능한 조사 단계를 에이전트가 생성해준다는 점에서 강점이 있습니다. 특히 빠른 트리아지, 프롬프트 기반 디버깅, 정확한 명령 공유에 유리합니다. 다만 깊이 있는 시각 탐색이나 즉석 탐색은 여전히 UI가 더 나은 경우가 많습니다.

언제 datadog-cli가 적합하지 않나요?

다음 상황이라면 이 skill 사용을 권하지 않습니다.

• 조직 정책상 Datadog API key 사용이 막혀 있는 경우
• CLI 워크플로우로 노출되지 않은 UI 전용 기능이 필요한 경우
• Datadog 실행법보다 넓은 Observability 이론이 필요한 경우
• 유효한 쿼리를 만들 만큼의 컨텍스트를 에이전트에 줄 수 없는 경우

skill 외에 따로 설치해야 하는 것이 있나요?

있습니다. 핵심 런타임 의존성은 아래처럼 호출하는 Datadog CLI입니다.

npx @leoflores/datadog-cli <command>

그리고 DD_API_KEY, DD_APP_KEY도 필요합니다. 계정에 따라 --site 지정이 필수일 수 있습니다.

datadog-cli는 Observability 조회만 하나요, 아니면 변경도 가능한가요?

대부분은 조회와 조사에 초점이 맞춰져 있지만, 대시보드 관련 명령은 상태를 변경할 수 있습니다. 가장 주의가 필요한 지점이 바로 여기입니다. 업데이트 흐름을 허용하기 전에 반드시 references/dashboards.md를 읽어두는 것이 좋습니다.

에이전트에게 그냥 “로그 좀 봐줘”라고 하는 것보다 낫나요?

네. 이 skill은 에이전트에게 구체적인 명령군과 참고 문서를 함께 제공합니다. 그 결과, 일반적인 자유형 프롬프트보다 범위 축소가 더 빠르고, 잘못된 쿼리가 줄며, 인시던트 대응 워크플로우도 더 실용적으로 나오는 경우가 많습니다.

datadog-cli skill 개선 방법

프롬프트 시작부터 운영 제약을 넣기

datadog-cli 출력 품질을 가장 빠르게 끌어올리는 방법은, CLI가 실제로 필요로 하는 제약 조건을 처음부터 넣는 것입니다.

• Datadog site
• environment
• 서비스 이름
• 시간 범위
• trace ID나 dashboard ID 같은 식별자
• 읽기 전용 작업인지, 대시보드 변경까지 허용되는지

이 정보가 없으면 에이전트는 신호가 약한 넓은 명령으로 흘러가기 쉽습니다.

명령 하나가 아니라 워크플로우를 요청하기

문제가 실제로는 여러 단계 조사인데도 단일 조회만 요청하는 것이 흔한 실패 패턴입니다. 더 나은 프롬프트 예시는 다음과 같습니다.

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.

이런 방식이 더 나은 이유는, 저장소에 있는 워크플로우 레퍼런스 구조와 바로 맞물리기 때문입니다.

더 강한 쿼리 재료를 제공하기

좋은 입력에는 실제 Datadog 필드가 들어갑니다.

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

“API가 느려요”처럼 자연어만 주면, 에이전트는 필드명과 필터를 추정해야 합니다. 필드 수준 입력이 강할수록 datadog-cli usage 품질도 더 좋아집니다.

대시보드 수정은 안전 우선 프롬프트로 다루기

작업이 대시보드를 건드린다면, 백업 우선 절차를 프롬프트에 명시하세요.

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.

이 한 줄 차이로, 이 skill에서 가장 파괴적인 리스크를 크게 줄일 수 있습니다.

첫 결과 후에는 무작정 넓히지 말고 더 좁히기

첫 번째 명령 세트를 받은 뒤에는 다음 식으로 좁혀가며 품질을 높이세요.

• 전체 에러에서 특정 서비스 하나로
• 24시간 범위에서 실제 장애 시간대로
• 일반 로그에서 패턴 그룹화로
• 증상 수준에서 trace 수준 증거로
• 로그에서 확인용 메트릭으로

이 접근은 “더 자세히”라고만 요청하는 것보다 훨씬 낫습니다. 그런 요청은 대개 노이즈만 늘리기 쉽습니다.

피해야 할 흔한 실수

도입과 출력 품질에서 가장 흔한 문제는 다음과 같습니다.

• DD_API_KEY 또는 DD_APP_KEY 누락
• 미국 이외 Datadog인데 --site를 빠뜨림
• 약하거나 잘못된 쿼리 문법 사용
• 처음부터 너무 넓은 시간 범위를 검색함
• dashboard update를 patch처럼 오해하고 전체 교체라는 점을 놓침
• 영향을 받은 서비스나 env를 말하지 않은 채 Observability 도움만 요청함

결과가 약하게 느껴질 때 저장소에서 다시 볼 곳

에이전트가 너무 일반론적으로 보인다면, 다음 파일로 돌아가세요.

• 필터 정밀도는 references/query-syntax.md
• 어떤 명령을 써야 하는지는 references/logs-commands.md
• 조사 순서는 references/workflows.md
• 안전한 수정 패턴은 references/dashboards.md

대개는 요청 전체를 처음부터 다시 쓰는 것보다, 이 순서로 다시 읽는 편이 프롬프트 개선에 더 빠르게 효과가 납니다.

설치 후 datadog-cli를 평가하는 가장 좋은 방법

실용적인 datadog-cli install 수용 테스트는 다음과 같습니다.

1. 이미 예상 결과를 아는 logs search를 실행한다
2. 범위를 좁힌 metrics query를 실행한다
3. errors나 logs patterns 같은 워크플로우 명령 하나를 테스트한다
4. 미국 외 지역이라면 --site 동작을 확인한다
5. 백업 절차가 검증되기 전에는 대시보드 쓰기 작업을 피한다

이 테스트들이 통과한다면, datadog-cli skill은 실제 인시던트 대응과 Observability 작업에 투입할 준비가 된 가능성이 높습니다.