datadog-cli

Tổng quan về skill datadog-cli

Skill datadog-cli giúp agent sử dụng Datadog từ dòng lệnh cho các tác vụ observability thực tế: tìm kiếm log, lần theo request trace, truy vấn metric, liệt kê service và quản lý dashboard. Đây là lựa chọn phù hợp nhất cho kỹ sư, SRE, platform team và người xử lý incident có hỗ trợ AI, những người đã có quyền truy cập Datadog và muốn triage nhanh hơn thay vì phải bấm thủ công qua UI.

datadog-cli dùng để làm gì

Hãy dùng datadog-cli khi công việc thực sự không phải là “tóm tắt Datadog”, mà là “điều tra một triệu chứng production bằng các câu lệnh có thể lặp lại.” Skill này mạnh nhất khi bạn cần:

• thu hẹp incident theo service, loại lỗi hoặc khoảng thời gian
• chuyển từ log sang ngữ cảnh trace
• kiểm tra xem một spike là mới xuất hiện hay vốn đã bình thường
• lấy metric nhanh cho một service hoặc environment
• kiểm tra hoặc cập nhật dashboard theo workflow điều khiển bằng CLI

Người dùng phù hợp nhất

datadog-cli skill này phù hợp với những người dùng:

• đã dùng Datadog cho logs, metrics, traces hoặc dashboards
• muốn agent tạo ra câu lệnh đúng thay vì gợi ý tìm kiếm mơ hồ
• cần workflow triage incident, không phải lời khuyên observability chung chung
• sẵn sàng cung cấp tên service, khoảng thời gian, trace ID hoặc dashboard ID

Nếu bạn chưa có Datadog keys hoặc chưa nắm rõ quy ước service/tag của mình, thì phần setup và chất lượng prompt sẽ ảnh hưởng nhiều hơn chính skill này.

Vì sao skill này hữu ích hơn một prompt chung chung

Một prompt thông thường có thể chỉ nói “xem log trên Datadog.” Skill này đưa cho agent một lộ trình ở cấp câu lệnh: logs search, logs tail, logs trace, logs context, logs patterns, logs compare, metrics query, errors, services và các thao tác với dashboard. Nó cũng chỉ ra các tài liệu tham chiếu quan trọng để chạy đúng, đặc biệt là cú pháp truy vấn và các cảnh báo khi cập nhật dashboard.

Những rào cản triển khai chính cần biết trước

Các rào cản chính nằm ở vận hành, không phải ở khái niệm:

• bắt buộc có DD_API_KEY và DD_APP_KEY
• tài khoản Datadog ngoài US có thể cần --site, ví dụ datadoghq.eu
• kết quả phụ thuộc rất nhiều vào cú pháp truy vấn Datadog chính xác
• cập nhật dashboard có tính phá hủy nếu bỏ sót trường

Đó là những điểm đầu tiên cần xác minh trước khi bạn đánh giá chất lượng datadog-cli usage.

Cách dùng skill datadog-cli

Cài đặt và bối cảnh runtime

Bản thân skill nằm trong softaworks/agent-toolkit, nhưng CLI thực tế mà nó hướng dẫn agent chạy là:

npx @leoflores/datadog-cli <command>

Trước tiên hãy thiết lập credential:

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

Với các Datadog site ngoài US, thêm --site:

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

Nếu bạn đang cân nhắc việc datadog-cli install, dependency quan trọng cần xác thực là CLI bên ngoài này cùng với quyền truy cập Datadog API đang hoạt động.

Hãy đọc các file này trước lần dùng thật đầu tiên

Skill này phụ thuộc vào tài liệu tham chiếu nhiều hơn bình thường. Hãy đọc theo thứ tự:

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

Lộ trình này giúp giảm phần lớn lỗi khi chạy lần đầu: filter sai, chọn time window yếu và chỉnh sửa dashboard không an toàn.

Những đầu vào skill cần để hoạt động tốt

datadog-cli skill cho kết quả tốt nhất khi yêu cầu của bạn có ít nhất một số thông tin sau:

• tên service, tên team hoặc environment
• khoảng thời gian như 15m, 1h hoặc 24h
• loại triệu chứng: errors, latency, failed requests, deployment regression
• trace ID, request ID hoặc timestamp nếu có
• bạn muốn logs, metrics, dashboards hay một workflow triage
• Datadog site nếu không phải US mặc định

Đầu vào yếu: “Check Datadog.”
Đầu vào mạnh: “Investigate payment-api 5xx errors in prod for the last hour, compare against the previous hour, then pull any related traces and CPU metrics.”

Biến một mục tiêu thô thành prompt dùng được

Một prompt datadog-cli guide tốt nên cho agent biết cả mục tiêu lẫn các chiều thu hẹp phạm vi.

Hãy thử mẫu này:

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

Vì sao mẫu này hiệu quả:

• nó cho agent một workflow, không phải chỉ một câu lệnh đơn lẻ
• nó bao gồm các query tag mà CLI thực sự dùng được
• nó ngăn agent tìm kiếm quá rộng

Những lệnh nên chạy đầu tiên cho các tác vụ phổ biến

Với triage incident, hãy bắt đầu rộng rồi mới thu hẹp:

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

Sau đó giới hạn theo service:

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

Nếu bạn đã có trace:

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

Để kiểm tra tình trạng service:

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

Với datadog-cli, cú pháp truy vấn quan trọng hơn đa số người dùng nghĩ

Nhiều kết quả datadog-cli usage kém thực ra là do chất lượng truy vấn. Skill này dựa vào cú pháp tìm kiếm của Datadog như:

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

Nếu bạn biết các field của mình, hãy đưa chúng vào rõ ràng. Nếu chưa biết, hãy yêu cầu agent bắt đầu bằng các truy vấn khám phá rộng hơn, rồi siết chặt dần dựa trên các thuộc tính trả về.

Workflow thực tế cho incident response

Một vòng điều tra hiệu quả với datadog-cli là:

1. lấy tổng quan lỗi bằng errors
2. so sánh khoảng thời gian hiện tại với giai đoạn trước bằng logs compare
3. gom cụm lỗi lặp lại bằng logs patterns
4. thu hẹp theo service/env bằng logs search
5. kiểm tra hoạt động xung quanh bằng logs context
6. chuyển sang luồng phân tán bằng logs trace
7. xác nhận tín hiệu tài nguyên hoặc throughput bằng metrics query

Cách này tốt hơn nhiều so với việc liên tục yêu cầu “thêm log,” vì mỗi câu lệnh trả lời một câu hỏi chẩn đoán khác nhau.

Dashboard cần được xử lý cẩn trọng hơn

Lưu ý an toàn quan trọng nhất trong repo này là dashboards update sẽ thay thế toàn bộ dashboard, chứ không chỉ các trường đã đổi. Nếu bỏ sót các trường như template variables, description hoặc notify list, chúng có thể bị xóa.

Trước mọi lần cập nhật, workflow an toàn là:

1. lấy dashboard ra file tạm bằng --output
2. giữ nguyên các trường hiện có
3. cập nhật bằng toàn bộ cấu trúc đã được giữ lại

Điều này có nghĩa datadog-cli skill chỉ thực sự phù hợp cho công việc liên quan dashboard nếu bạn làm việc kỷ luật với backup và cập nhật full-state.

Mẹo cải thiện chất lượng đầu ra có tác động rõ rệt

Để agent trả lời tốt hơn:

• nêu rõ bạn muốn khám phá, giải thích hay câu lệnh chính xác
• nếu có thể, hãy cung cấp cả tag service và env cùng lúc
• chọn time window có giới hạn trước; chỉ mở rộng khi cần
• khi đánh giá regression, hãy yêu cầu so sánh với giai đoạn trước
• nếu đã có trace ID hoặc timestamp, hãy ưu tiên đưa vào
• yêu cầu --pretty khi cần con người đọc kết quả

Thông thường, cải thiện lớn nhất đến từ việc đưa ra mục tiêu truy vấn chính xác, không phải từ việc yêu cầu phân tích dài hơn.

Khi nào nên dùng logs, metrics hay dashboards

Dùng logs khi bạn cần event cụ thể, lỗi hoặc chi tiết request.
Dùng metrics khi bạn cần xu hướng, mức sử dụng tài nguyên hoặc tín hiệu rate/latency.
Dùng dashboards khi bạn cần ngữ cảnh vận hành sẵn có hoặc muốn đóng gói một góc nhìn cho cả team.

Nếu bạn yêu cầu agent xử lý cả ba cùng lúc, hãy nói rõ mục tiêu ra quyết định là gì: root cause, blast radius, regression check hay tạo dashboard.

Câu hỏi thường gặp về skill datadog-cli

datadog-cli có phù hợp cho người mới bắt đầu không?

Có, nếu bạn đã có quyền truy cập Datadog và hiểu các khái niệm cơ bản như services, tags và time windows. Không, nếu bạn vẫn đang học logs, traces và metrics thực sự đại diện cho điều gì. Skill này giúp giảm việc đoán mò câu lệnh, nhưng không thay thế nhu cầu phải hiểu tên environment và quy ước observability trong hệ thống của bạn.

Điểm khác biệt so với dùng trực tiếp Datadog UI là gì?

datadog-cli tốt hơn khi bạn muốn các bước điều tra có thể lặp lại, dễ script hóa và do agent tạo ra. Nó đặc biệt hữu ích cho triage nhanh, debug theo prompt và chia sẻ câu lệnh chính xác. UI vẫn phù hợp hơn cho việc khám phá trực quan chuyên sâu và duyệt ad hoc.

Khi nào datadog-cli không phải lựa chọn phù hợp?

Đừng dùng skill này nếu:

• tổ chức của bạn chặn việc dùng Datadog API key
• bạn cần các tính năng chỉ có trên UI mà workflow CLI không hỗ trợ
• bạn muốn kiến thức observability tổng quát thay vì cách thực thi cụ thể trong Datadog
• bạn không thể cung cấp đủ ngữ cảnh để agent tạo truy vấn hợp lệ

Tôi có cần cài thêm gì ngoài skill không?

Có. Dependency runtime quan trọng là Datadog CLI được gọi như sau:

npx @leoflores/datadog-cli <command>

Bạn cũng cần DD_API_KEY và DD_APP_KEY. Với một số tài khoản, bạn phải truyền thêm --site.

datadog-cli chỉ dành cho Observability hay còn có thể thay đổi hệ thống?

Phần lớn nó phục vụ việc kiểm tra và điều tra, nhưng các lệnh dashboard có thể thay đổi trạng thái. Đây là chỗ cần cẩn trọng nhất. Hãy đọc references/dashboards.md trước khi cho phép bất kỳ workflow cập nhật nào.

Nó có tốt hơn việc chỉ bảo agent “check logs” không?

Có, vì skill này cung cấp cho agent các nhóm lệnh cụ thể và tài liệu tham chiếu đi kèm. Điều đó thường giúp thu hẹp nhanh hơn, giảm truy vấn lỗi cú pháp và tạo ra workflow incident hữu ích hơn so với prompt tự do thông thường.

Cách cải thiện skill datadog-cli

Bắt đầu prompt bằng các ràng buộc vận hành

Cách nhanh nhất để cải thiện đầu ra của datadog-cli là đưa vào các ràng buộc mà CLI thực sự cần:

• Datadog site
• environment
• tên service
• khoảng thời gian
• định danh như trace ID hoặc dashboard ID
• tác vụ là chỉ đọc hay được phép sửa dashboard

Nếu thiếu các thông tin này, agent thường mặc định dùng các câu lệnh quá rộng và ít tín hiệu.

Hãy yêu cầu một workflow, đừng chỉ hỏi một lệnh

Một kiểu thất bại phổ biến là prompt chỉ xin một lần tra cứu, trong khi vấn đề thực tế cần cả một chuỗi bước. Prompt tốt hơn:

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.

Cách này tạo ra quá trình điều tra tốt hơn vì nó bám sát các tài liệu workflow trong repo.

Cung cấp thành phần truy vấn mạnh hơn

Đầu vào tốt nên bao gồm các field Datadog thật:

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

Nếu bạn chỉ mô tả bằng ngôn ngữ tự nhiên như “the API is slow,” agent sẽ phải đoán tên field và filter. Đầu vào ở mức field cụ thể sẽ cho datadog-cli usage tốt hơn.

Xử lý chỉnh sửa dashboard bằng prompt ưu tiên an toàn

Nếu tác vụ có đụng tới dashboard, hãy nói rõ yêu cầu workflow backup trước:

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.

Cách này giảm mạnh rủi ro phá hủy lớn nhất của skill.

Lặp lại sau đầu ra đầu tiên thay vì mở rộng mù quáng

Sau bộ lệnh đầu tiên, hãy cải thiện kết quả bằng cách thu hẹp:

• từ mọi lỗi xuống một service cụ thể
• từ 24h xuống đúng khung thời gian xảy ra lỗi
• từ log chung chung sang nhóm mẫu lỗi
• từ triệu chứng sang bằng chứng ở mức trace
• từ logs sang metrics để xác nhận

Cách này tốt hơn việc yêu cầu agent “chi tiết hơn,” vì kiểu yêu cầu đó thường chỉ làm tăng nhiễu.

Những lỗi phổ biến cần tránh

Các vấn đề phổ biến nhất khi triển khai và khi nhận đầu ra là:

• thiếu DD_API_KEY hoặc DD_APP_KEY
• quên --site với Datadog ngoài US
• dùng cú pháp truy vấn yếu hoặc không hợp lệ
• ngay từ đầu đã tìm trên time range quá rộng
• xem dashboard update như patch thay vì thay thế toàn phần
• yêu cầu hỗ trợ observability nhưng không nêu service hoặc env bị ảnh hưởng

Nên kiểm tra gì trong repo khi kết quả còn yếu

Nếu agent có vẻ quá chung chung, hãy quay lại:

• references/query-syntax.md để tăng độ chính xác của filter
• references/logs-commands.md để chọn đúng lệnh
• references/workflows.md để đi đúng thứ tự điều tra
• references/dashboards.md để theo mẫu chỉnh sửa an toàn

Lộ trình đọc này thường giúp sửa prompt kém nhanh hơn so với việc viết lại toàn bộ yêu cầu từ đầu.

Cách tốt nhất để đánh giá datadog-cli sau khi cài đặt

Một bài acceptance test thực tế cho datadog-cli install là:

1. chạy một logs search đã biết trước
2. chạy một metrics query có phạm vi rõ ràng
3. thử một lệnh workflow như errors hoặc logs patterns
4. xác nhận hành vi --site nếu bạn ở ngoài US
5. tránh ghi vào dashboard cho đến khi workflow backup được xác minh

Nếu các bước này đều thành công, datadog-cli skill nhiều khả năng đã sẵn sàng cho công việc incident và observability thực tế.