datadog-cli

datadog-cli skill 概覽

datadog-cli skill 讓代理可以直接透過命令列使用 Datadog，處理實際的可觀測性工作：搜尋 logs、追查 requests、查詢 metrics、列出 services，以及管理 dashboards。它特別適合已經有 Datadog 權限、想在不手動點 UI 的情況下加快分流與排查速度的工程師、SRE、平台團隊，以及由 AI 協助的事件應變人員。

datadog-cli 的用途是什麼

當你的真正目標不是「摘要 Datadog 裡有什麼」，而是「用可重複執行的指令調查正式環境症狀」時，就適合用 datadog-cli。這個 skill 最擅長的情境包括：

• 依 service、錯誤類型或時間區間逐步縮小 incident 範圍
• 從 logs 轉進 trace 脈絡
• 判斷某個尖峰是新異常還是平常就有的波動
• 快速拉出某個 service 或 environment 的 metrics
• 用 CLI 驅動流程檢查或更新 dashboards

最適合的使用者

這個 datadog-cli skill 特別適合以下使用者：

• 已經用 Datadog 管理 logs、metrics、traces 或 dashboards
• 希望代理直接產生正確指令，而不是只給模糊搜尋建議
• 需要 incident triage 流程，而不是泛泛而談的 observability 建議
• 願意提供 service 名稱、時間範圍、trace ID 或 dashboard ID

如果你還沒有 Datadog keys，或還不清楚自己環境裡的 service/tag 命名慣例，那麼 setup 與 prompt 品質對結果的影響，會比 skill 本身更大。

為什麼這個 skill 比一般 prompt 更有用

一般 prompt 可能只會說「去看一下 Datadog logs」。這個 skill 則直接提供代理可執行的命令層級路徑：logs search、logs tail、logs trace、logs context、logs patterns、logs compare、metrics query、errors、services，以及 dashboard 相關操作。它也會指向真正影響正確執行的參考文件，尤其是 query syntax 與 dashboard 更新風險的說明。

先知道的 datadog-cli 導入阻礙

主要阻礙多半不是概念理解，而是操作層面：

• 必須提供 DD_API_KEY 和 DD_APP_KEY
• 非美國區 Datadog 帳號可能需要加上 --site，例如 datadoghq.eu
• 查詢結果高度依賴正確的 Datadog query syntax
• dashboard 更新具有破壞性，省略欄位可能導致資料被覆蓋或移除

在評估 datadog-cli usage 品質之前，這幾點應該先確認清楚。

如何使用 datadog-cli skill

datadog-cli 的安裝與執行環境

這個 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，請加上 --site：

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

如果你是在評估是否要實際採用 datadog-cli install，真正要先驗證的依賴其實是外部 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

照這個順序看，通常能避開大多數第一次使用會遇到的錯誤：像是 filter 寫錯、時間範圍抓太弱，或 dashboard 編輯方式不安全。

datadog-cli skill 要吃到哪些輸入才會表現好

當你的需求至少包含下列其中幾項時，datadog-cli skill 會明顯表現更好：

• service 名稱、team 名稱或 environment
• 像 15m、1h、24h 這類時間區間
• 症狀類型：errors、latency、failed requests、deployment regression
• trace ID、request ID，或明確 timestamp（如果你手上有）
• 你要的是 logs、metrics、dashboards，還是完整 triage workflow
• 若非預設美國區，請提供 Datadog site

弱輸入範例：「Check Datadog。」
強輸入範例：「Investigate payment-api 5xx errors in prod for the last hour, compare against the previous hour, then pull any related traces and CPU metrics.」

把模糊目標改寫成可用的 datadog-cli prompt

好的 datadog-cli guide prompt，應該同時告訴代理「目標」與「縮小範圍的維度」。

可以用這種格式：

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

這樣寫之所以有效，是因為：

• 它給的是一個 workflow，不是一條孤立指令
• 它包含 CLI 真正可用的 query tags
• 它能避免代理把搜尋範圍拉得太廣

datadog-cli 常見工作最值得先跑的指令

做 incident triage 時，建議先廣後窄：

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

接著再縮到特定 service：

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

如果要看 service 健康狀況：

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

datadog-cli 的 query syntax 比多數人想像得更重要

很多看起來效果不佳的 datadog-cli usage，其實問題不在工具本身，而是 query 品質太弱。這個 skill 依賴 Datadog 的搜尋語法，例如：

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

如果你知道自己要查的欄位，請直接明講。若你還不知道，就讓代理先用範圍較大的 discovery queries 探索，再根據回傳屬性逐步收斂。

datadog-cli 的實務 incident response 工作流

使用 datadog-cli 時，一個夠強的調查迴圈通常是：

1. 用 errors 先看整體錯誤概況
2. 用 logs compare 對比目前時段與前一時段
3. 用 logs patterns 把重複失敗型態分群
4. 用 logs search 依 service/env 繼續縮小範圍
5. 用 logs context 看前後相關活動
6. 用 logs trace 轉進分散式流程脈絡
7. 用 metrics query 確認資源或吞吐量訊號

這比反覆要求「再多給我一些 logs」有效得多，因為每一條命令都在回答不同的診斷問題。

使用 datadog-cli 處理 dashboards 要更謹慎

這個 repo 裡最重要的安全提醒是：dashboards update 會覆蓋整個 dashboard，不是只修改變更的欄位。如果像 template variables、description 或 notify list 這些欄位沒有帶上，可能會直接被移除。

在任何更新之前，安全流程應該是：

1. 先用 --output 把 dashboard 匯出到暫存檔
2. 保留既有欄位
3. 用完整保留的結構進行更新

因此，只有在你能嚴格遵守備份與完整狀態更新流程時，這個 datadog-cli skill 才適合拿來做 dashboard 相關工作。

會直接影響 datadog-cli 輸出品質的實用技巧

如果你想讓代理給出更好的答案：

• 先說清楚你要 discovery、explanation，還是 exact commands
• 盡量同時提供 service 與 env tags
• 一開始先用有界的時間範圍；真的需要再往外擴
• 在判斷 regression 時，要求和前一個時段比較
• 如果你已經有 trace ID 或 timestamp，優先提供
• 需要人工檢視時，記得要求 --pretty

通常最大的品質提升，來自於你給了明確的 query 目標，而不是要求更冗長的分析。

datadog-cli 中何時該用 logs、metrics 或 dashboards

當你需要具體事件、錯誤內容或 request 細節時，用 logs。
當你需要趨勢、資源使用狀況，或 rate/latency 訊號時，用 metrics。
當你需要既有營運視角，或想整理一個可供團隊共用的檢視時，用 dashboards。

如果你一次要代理同時處理三者，請把決策目標一起講清楚：是要找 root cause、估 blast radius、檢查 regression，還是建立 dashboard。

datadog-cli skill 常見問題

datadog-cli 適合新手嗎？

適合，但前提是你已經有 Datadog 存取權限，並理解 services、tags、time windows 這些基本概念。若你還在學 logs、traces、metrics 各自代表什麼，那就不太適合。這個 skill 能減少你猜指令的成本，但不會取代你對環境名稱與 observability 慣例的理解。

這和直接用 Datadog UI 有什麼不同？

當你想要可重複、可腳本化、由代理產生的調查步驟時，datadog-cli 會更有優勢。它特別適合快速 triage、以 prompt 驅動的除錯，以及分享可直接執行的精確命令。不過，如果你要做深入的視覺化探索或臨時瀏覽，UI 仍然更好用。

什麼情況下 datadog-cli 不適合？

以下情況不建議使用這個 skill：

• 你的組織禁止使用 Datadog API keys
• 你需要的是 CLI workflow 沒有暴露出的 UI 專屬功能
• 你想要的是廣義 observability 理論，而不是 Datadog 專用執行方式
• 你無法提供足夠上下文讓代理形成有效 query

除了 skill 之外，還需要安裝其他東西嗎？

需要。關鍵的執行期依賴是這個 Datadog CLI：

npx @leoflores/datadog-cli <command>

你還需要 DD_API_KEY 與 DD_APP_KEY。某些帳號另外必須加上 --site。

datadog-cli 只適合 Observability，還是也能修改內容？

大多數情況下它是用來檢視與調查，但 dashboard 相關指令確實可能改動狀態。這也是最需要提高警覺的地方。在允許任何 update flow 之前，務必先看 references/dashboards.md。

它比直接叫代理「去看 logs」更好嗎？

是的，因為這個 skill 會把具體的命令家族與參考文件一起交給代理。這通常代表更快的範圍收斂、更少格式錯誤的 query，以及比一般自由輸入 prompt 更有用的 incident workflow。

如何改善 datadog-cli skill 的使用效果

一開始就在 prompt 裡帶入操作限制

想提升 datadog-cli 輸出品質，最快的方法就是直接提供 CLI 真正需要的限制條件：

• Datadog site
• environment
• service names
• time range
• trace ID 或 dashboard ID 這類 identifiers
• 這次任務是 read-only，還是允許修改 dashboards

少了這些資訊，代理通常就會退回到範圍很廣、訊號很弱的指令。

不要只問一條指令，改成要求完整 workflow

常見失敗模式是只要求一次查詢，但實際問題需要一串步驟。比較好的 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.

這樣會產生更好的調查流程，因為它直接對應 repo 裡的 workflow references。

提供更強的 query 素材

好的輸入應該包含實際 Datadog 欄位：

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

如果你只給自然語言，例如「API 很慢」，代理就得自己猜欄位名稱與 filter。能提供欄位級輸入時，通常就會得到更好的 datadog-cli usage。

datadog-cli 編輯 dashboard 時，請用安全優先的 prompt

如果你的工作會碰到 dashboards，請明確要求先備份再修改：

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 最具破壞性的風險。

第一輪輸出後要收斂，不要盲目放大範圍

拿到第一組指令後，改善結果的方式通常是往下收斂：

• 從全部 errors 收到單一 service
• 從 24h 縮到真正的故障時段
• 從 generic logs 改查 pattern grouping
• 從 symptom 轉向 trace-level evidence
• 從 logs 轉去驗證 metrics

這比單純要求代理「再多給一點細節」更有效，因為後者通常只會把雜訊一起放大。

datadog-cli 常見錯誤要避免

最常見的導入與輸出問題包括：

• 缺少 DD_API_KEY 或 DD_APP_KEY
• 非美國區 Datadog 忘記加 --site
• query syntax 太弱或寫錯
• 一開始就搜尋太大的時間範圍
• 把 dashboard update 當成 patch，以為只會局部修改，實際上卻是完整覆蓋
• 要求 observability 協助時，卻沒有指出受影響的 service 或 env

當 datadog-cli 結果偏弱時，應該回 repo 看哪些地方

如果代理的表現顯得太泛，建議回頭看：

• references/query-syntax.md，確認 filter 精準度
• references/logs-commands.md，確認命令選擇是否正確
• references/workflows.md，確認調查順序
• references/dashboards.md，確認安全修改模式

通常照這條路徑補讀，比從頭重寫整個需求更快改善 prompt 品質。

安裝後評估 datadog-cli 的最佳方式

要做實際可用的 datadog-cli install 驗收，可以用這組測試：

1. 跑一次已知可命中的 logs search
2. 跑一次有範圍限制的 metrics query
3. 測一個 workflow 類指令，例如 errors 或 logs patterns
4. 如果不是美國區，確認 --site 行為正確
5. 在備份流程驗證完成前，先不要做 dashboard 寫入

如果以上都能順利完成，這個 datadog-cli skill 通常就已經可以投入真實 incident 與 observability 工作。