diff --git a/datadog/mcp.json b/datadog/mcp.json index aca9b4fa..666fd987 100644 --- a/datadog/mcp.json +++ b/datadog/mcp.json @@ -1,7 +1,8 @@ { + "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json", "mcpServers": { "datadog": { - "type": "http", + "type": "streamable-http", "url": "https://mcp.datadoghq.com/v1/mcp" } } diff --git a/datadog/plugin.json b/datadog/plugin.json new file mode 100644 index 00000000..4e2212d6 --- /dev/null +++ b/datadog/plugin.json @@ -0,0 +1,20 @@ +{ + "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", + "name": "datadog", + "version": "1.0.0", + "description": "Datadog Observability: query logs, metrics, traces, RUM events, incidents, and monitors from Datadog for production debugging and performance analysis.", + "author": { + "name": "Datadog" + }, + "homepage": "https://docs.datadoghq.com/bits_ai/mcp_server/", + "repository": "https://github.com/kirodotdev/powers", + "keywords": [ + "datadog", + "observability", + "logs", + "metrics", + "apm", + "rum", + "incidents" + ] +} diff --git a/datadog/steering/steering.md b/datadog/skills/datadog-query-syntax/SKILL.md similarity index 73% rename from datadog/steering/steering.md rename to datadog/skills/datadog-query-syntax/SKILL.md index a3231574..b0b7df08 100644 --- a/datadog/steering/steering.md +++ b/datadog/skills/datadog-query-syntax/SKILL.md @@ -1,6 +1,14 @@ -# Datadog MCP Server Steering Guide +--- +name: "datadog-query-syntax" +description: "Apply Datadog query syntax and best practices for logs, metrics, APM spans, RUM events, incidents and monitors when calling the Datadog MCP tools. Use when composing or debugging a Datadog search query, choosing time ranges, applying unified service tags, or avoiding common query mistakes." +metadata: + author: "Datadog" + version: "1.0.0" +--- + +# Datadog MCP Server Query Guide -This steering file provides comprehensive guidance for using the Datadog MCP (Model Context Protocol) server to query observability data including logs, metrics, traces, RUM events, incidents, and more. +This skill provides comprehensive guidance for using the Datadog MCP (Model Context Protocol) server to query observability data including logs, metrics, traces, RUM events, incidents, and more. ## When to Use the Datadog MCP Server @@ -554,227 +562,14 @@ Start narrow and expand based on findings: --- -## Common Use Cases - -### 1. Investigating Production Errors -``` -# Step 1: Search logs for errors in last hour -Tool: search_datadog_logs -Query: service:api env:prod status:error -Time: from="now-1h", to="now" - -# Step 2: If errors found, get error details -Enable: extra_fields=["*"] # Get all attributes -Check: Error messages, stack traces, affected users - -# Step 3: Find related traces -Tool: search_datadog_spans -Query: service:api status:error -Time: Same as log time range - -# Step 4: Get full trace for detailed analysis -Tool: get_datadog_trace -trace_id: -``` - -### 2. Performance Degradation Analysis -``` -# Step 1: Check for slow requests -Tool: search_datadog_spans -Query: service:api @duration:>100000000 # >100ms -Time: from="now-1h", to="now" - -# Step 2: Examine metrics for patterns -Tool: get_datadog_metric -Query: avg:trace.servlet.request.duration{service:api} by {resource_name} -Time: from="now-4h", to="now" - -# Step 3: Check for infrastructure issues -Tool: get_datadog_metric -Query: avg:system.cpu.user{service:api} by {host} -Time: Same range - -# Step 4: Review related monitors -Tool: search_datadog_monitors -Query: tag:"service:api" status:alert -``` - -### 3. User Experience Issues (RUM) -``` -# Step 1: Find slow page loads -Tool: search_datadog_rum_events -Query: @type:view @view.loading_time:>3000 -detailed_output: true -Time: from="now-1h", to="now" - -# Step 2: Check for frontend errors -Tool: search_datadog_rum_events -Query: @type:error @application.name:"My App" -Time: Same range - -# Step 3: Analyze by device/browser -Query: @type:view @view.loading_time:>3000 -Group findings by @device.type and @browser.name -``` - -### 4. Incident Investigation -``` -# Step 1: Find active incidents -Tool: search_datadog_incidents -Query: state:(active OR stable) - -# Step 2: Get incident details -Tool: get_datadog_incident -incident_id: - -# Step 3: Check related metrics/logs -Use incident time range to query logs and metrics -Filter by affected services/hosts from incident -``` - -### 5. Service Dependency Analysis -``` -# Step 1: List all services -Tool: search_datadog_services -detailed_output: true - -# Step 2: Find traces spanning multiple services -Tool: search_datadog_spans -Query: service:frontend -Check spans for downstream service calls - -# Step 3: Analyze service-to-service latency -Tool: get_datadog_metric -Query: avg:trace.servlet.request.duration{env:prod} by {service} -``` - ---- - -## Anti-Patterns and Common Mistakes - -### ❌ DON'T: Use Very Long Time Ranges Without Reason -``` -# Slow and often not helpful -from: "now-30d" -``` -**Instead**: Start with `now-1h` or `now-24h`, expand if needed. - -### ❌ DON'T: Forget @ Prefix for Span/Log Attributes -``` -# Wrong -http.status_code:500 - -# Correct -@http.status_code:500 -``` - -### ❌ DON'T: Use @ Prefix for Reserved Trace Attributes -``` -# Wrong -@service:api - -# Correct -service:api -``` - -### ❌ DON'T: Forget Duration is in Nanoseconds -``` -# Wrong (this is 5 nanoseconds!) -@duration:>5 - -# Correct (5 milliseconds) -@duration:>5000000 -``` - -### ❌ DON'T: Use Wildcards Inside Quotes -``` -# Wrong (wildcard becomes literal) -@url:"*/api/*" - -# Correct -@url:*/api/* -``` - -### ❌ DON'T: Separate Multi-Value OR Queries -``` -# Wrong for incidents -severity:SEV-1 OR severity:SEV-2 - -# Correct -severity:(SEV-1 OR SEV-2) -``` - -### ❌ DON'T: Use Excessive Free-Text Searches -``` -# Slow and imprecise -"timeout error in production" - -# Better - use structured tags -service:api env:prod @error.message:*timeout* -``` - -### ❌ DON'T: Ignore Unified Service Tagging -``` -# Missing critical context -status:error - -# Much better -service:api env:prod version:v1.2.3 status:error -``` - -### ❌ DON'T: Skip Escaping Special Characters -``` -# Wrong (colon breaks parsing) -@url:https://example.com - -# Correct -@url:https\:\/\/example.com -``` - ---- - -## Performance Tips +## Common Use Cases, Anti-Patterns and Performance Tips -### 1. Query Optimization -- **Filter first**: Use `service`, `env` before complex conditions -- **Use facets**: Ensure frequently queried attributes are facets -- **Limit wildcards**: Avoid leading wildcards when possible -- **Use tag searches**: More efficient than free-text - -### 2. Result Size Management -- **max_tokens**: Adjust based on needs (5000 for overview, 50000 for details) -- **head_limit**: Limit result count for faster responses -- **group_by_message**: For logs, group similar messages to reduce output -- **Binned metrics**: Use binned data for trends instead of raw - -### 3. Time Range Strategy -``` -# Good progression -1. now-15m → Quick check for recent issues -2. now-1h → Standard investigation window -3. now-24h → Broader pattern analysis -4. now-7d → Historical trends only when needed -``` - -### 4. Parallel Investigations -When investigating incidents, query multiple sources in parallel: -- Logs for error messages -- Spans for trace analysis -- Metrics for resource utilization -- Monitors for alert status +Step-by-step investigation examples (production errors, performance degradation, user experience, incidents, service dependencies), common mistakes to avoid, and query/result-size performance tips are in [references/use-cases-and-pitfalls.md](references/use-cases-and-pitfalls.md). --- ## Additional Resources -### Documentation Tool -Use `search_datadog_docs` to look up information about instrumentation, setup, and platform functionality: -- **Service instrumentation**: How to add APM tracing, log collection, or RUM to your applications -- **Integration setup**: How to configure cloud providers, databases, or third-party services -- **Platform features**: How to use monitors, dashboards, SLOs, synthetic tests, etc. -- **Configuration options**: How to use APIs, agent settings, tagging strategies -- **Best practices**: Recommended approaches for monitoring and observability - ### Dashboard Analysis Use `search_datadog_dashboards` to: - Find existing dashboards by name or tags @@ -797,4 +592,4 @@ Before making Datadog queries, ensure you: - ✅ Set appropriate max_tokens for expected result size - ✅ Use structured tag queries instead of free-text when possible -This steering file represents the essential knowledge for effectively querying Datadog observability data through the MCP server. Follow these patterns for accurate, performant, and actionable results. \ No newline at end of file +This skill represents the essential knowledge for effectively querying Datadog observability data through the MCP server. Follow these patterns for accurate, performant, and actionable results. \ No newline at end of file diff --git a/datadog/skills/datadog-query-syntax/references/use-cases-and-pitfalls.md b/datadog/skills/datadog-query-syntax/references/use-cases-and-pitfalls.md new file mode 100644 index 00000000..f1d7ac93 --- /dev/null +++ b/datadog/skills/datadog-query-syntax/references/use-cases-and-pitfalls.md @@ -0,0 +1,212 @@ +# Datadog Query Use Cases, Anti-Patterns and Performance Tips + +Companion reference for the [datadog-query-syntax](../SKILL.md) skill. + +## Common Use Cases + +### 1. Investigating Production Errors +``` +# Step 1: Search logs for errors in last hour +Tool: search_datadog_logs +Query: service:api env:prod status:error +Time: from="now-1h", to="now" + +# Step 2: If errors found, get error details +Enable: extra_fields=["*"] # Get all attributes +Check: Error messages, stack traces, affected users + +# Step 3: Find related traces +Tool: search_datadog_spans +Query: service:api status:error +Time: Same as log time range + +# Step 4: Get full trace for detailed analysis +Tool: get_datadog_trace +trace_id: +``` + +### 2. Performance Degradation Analysis +``` +# Step 1: Check for slow requests +Tool: search_datadog_spans +Query: service:api @duration:>100000000 # >100ms +Time: from="now-1h", to="now" + +# Step 2: Examine metrics for patterns +Tool: get_datadog_metric +Query: avg:trace.servlet.request.duration{service:api} by {resource_name} +Time: from="now-4h", to="now" + +# Step 3: Check for infrastructure issues +Tool: get_datadog_metric +Query: avg:system.cpu.user{service:api} by {host} +Time: Same range + +# Step 4: Review related monitors +Tool: search_datadog_monitors +Query: tag:"service:api" status:alert +``` + +### 3. User Experience Issues (RUM) +``` +# Step 1: Find slow page loads +Tool: search_datadog_rum_events +Query: @type:view @view.loading_time:>3000 +detailed_output: true +Time: from="now-1h", to="now" + +# Step 2: Check for frontend errors +Tool: search_datadog_rum_events +Query: @type:error @application.name:"My App" +Time: Same range + +# Step 3: Analyze by device/browser +Query: @type:view @view.loading_time:>3000 +Group findings by @device.type and @browser.name +``` + +### 4. Incident Investigation +``` +# Step 1: Find active incidents +Tool: search_datadog_incidents +Query: state:(active OR stable) + +# Step 2: Get incident details +Tool: get_datadog_incident +incident_id: + +# Step 3: Check related metrics/logs +Use incident time range to query logs and metrics +Filter by affected services/hosts from incident +``` + +### 5. Service Dependency Analysis +``` +# Step 1: List all services +Tool: search_datadog_services +detailed_output: true + +# Step 2: Find traces spanning multiple services +Tool: search_datadog_spans +Query: service:frontend +Check spans for downstream service calls + +# Step 3: Analyze service-to-service latency +Tool: get_datadog_metric +Query: avg:trace.servlet.request.duration{env:prod} by {service} +``` + +--- + +## Anti-Patterns and Common Mistakes + +### ❌ DON'T: Use Very Long Time Ranges Without Reason +``` +# Slow and often not helpful +from: "now-30d" +``` +**Instead**: Start with `now-1h` or `now-24h`, expand if needed. + +### ❌ DON'T: Forget @ Prefix for Span/Log Attributes +``` +# Wrong +http.status_code:500 + +# Correct +@http.status_code:500 +``` + +### ❌ DON'T: Use @ Prefix for Reserved Trace Attributes +``` +# Wrong +@service:api + +# Correct +service:api +``` + +### ❌ DON'T: Forget Duration is in Nanoseconds +``` +# Wrong (this is 5 nanoseconds!) +@duration:>5 + +# Correct (5 milliseconds) +@duration:>5000000 +``` + +### ❌ DON'T: Use Wildcards Inside Quotes +``` +# Wrong (wildcard becomes literal) +@url:"*/api/*" + +# Correct +@url:*/api/* +``` + +### ❌ DON'T: Separate Multi-Value OR Queries +``` +# Wrong for incidents +severity:SEV-1 OR severity:SEV-2 + +# Correct +severity:(SEV-1 OR SEV-2) +``` + +### ❌ DON'T: Use Excessive Free-Text Searches +``` +# Slow and imprecise +"timeout error in production" + +# Better - use structured tags +service:api env:prod @error.message:*timeout* +``` + +### ❌ DON'T: Ignore Unified Service Tagging +``` +# Missing critical context +status:error + +# Much better +service:api env:prod version:v1.2.3 status:error +``` + +### ❌ DON'T: Skip Escaping Special Characters +``` +# Wrong (colon breaks parsing) +@url:https://example.com + +# Correct +@url:https\:\/\/example.com +``` + +--- + +## Performance Tips + +### 1. Query Optimization +- **Filter first**: Use `service`, `env` before complex conditions +- **Use facets**: Ensure frequently queried attributes are facets +- **Limit wildcards**: Avoid leading wildcards when possible +- **Use tag searches**: More efficient than free-text + +### 2. Result Size Management +- **max_tokens**: Adjust based on needs (5000 for overview, 50000 for details) +- **head_limit**: Limit result count for faster responses +- **group_by_message**: For logs, group similar messages to reduce output +- **Binned metrics**: Use binned data for trends instead of raw + +### 3. Time Range Strategy +``` +# Good progression +1. now-15m → Quick check for recent issues +2. now-1h → Standard investigation window +3. now-24h → Broader pattern analysis +4. now-7d → Historical trends only when needed +``` + +### 4. Parallel Investigations +When investigating incidents, query multiple sources in parallel: +- Logs for error messages +- Spans for trace analysis +- Metrics for resource utilization +- Monitors for alert status diff --git a/datadog/POWER.md b/datadog/skills/datadog/SKILL.md similarity index 73% rename from datadog/POWER.md rename to datadog/skills/datadog/SKILL.md index 7de7464e..d0fbd373 100644 --- a/datadog/POWER.md +++ b/datadog/skills/datadog/SKILL.md @@ -1,19 +1,23 @@ --- name: "datadog" -displayName: "Datadog Observability" -description: "Query logs, metrics, traces, RUM events, incidents, and monitors from Datadog for production debugging and performance analysis" -keywords: ["datadog", "observability", "monitoring", "logs", "metrics", "apm", "traces", "rum", "incidents"] -author: "Datadog" +description: "Query Datadog logs, metrics, APM traces, RUM events, incidents, monitors, services and dashboards through the Datadog MCP server for production debugging and performance analysis. Use when investigating production issues, analyzing performance or user experience, or checking incidents and monitors." +metadata: + author: "Datadog" + version: "1.0.0" --- # Onboarding -Before proceeding, let the user know that the MCP server is currently in preview and they may need to request access by visiting https://docs.datadoghq.com/bits_ai/mcp_server/ +The Datadog MCP server is generally available. Before proceeding, let the user know what it needs: +- An organization admin must allow MCP access in Organization Settings. +- The user's Datadog role needs MCP Server permissions (the Standard Role has them by default; custom roles need `mcp_read` and/or `mcp_write`). +- Datadog government sites (`app.ddog-gov.com`, `us2.ddog-gov.com`) are not supported. +Setup details: https://docs.datadoghq.com/bits_ai/mcp_server/setup # Overview -The Datadog Observability Power provides comprehensive access to your Datadog monitoring data across logs, metrics, APM traces, Real User Monitoring (RUM), incidents, and monitors. Query and analyze production systems for debugging, performance optimization, and incident response. +The Datadog Observability plugin provides comprehensive access to your Datadog monitoring data across logs, metrics, APM traces, Real User Monitoring (RUM), incidents, and monitors. Query and analyze production systems for debugging, performance optimization, and incident response. **Key capabilities:** - **Log Search**: Query application and infrastructure logs with powerful filtering @@ -22,20 +26,19 @@ The Datadog Observability Power provides comprehensive access to your Datadog mo - **RUM**: Analyze user experience, page performance, and frontend errors - **Incidents**: Track and manage production incidents - **Monitors**: Search alerting rules and monitor status -- **Documentation**: Look up Datadog setup, instrumentation, and best practices -**Authentication**: Requires Datadog API key and application key. +**Authentication**: OAuth 2.0 (recommended; your MCP client completes the login flow). A Datadog Personal or Service Access Token, or a Datadog API key and application key, can be used instead when OAuth is not possible. See [Configuration](#configuration). -## Available Steering Files +## Related Skills -This power has the following steering files: -- **steering** - Comprehensive query syntax guide with examples, workflows, and troubleshooting +This plugin has the following related skill: +- **[datadog-query-syntax](../datadog-query-syntax/SKILL.md)** - Comprehensive query syntax guide with examples, workflows, and troubleshooting ## Available MCP Servers ### datadog -**Package:** `mcp-remote` + `https://mcp.datadoghq.com/api/unstable/mcp-server/mcp` -**Connection:** Remote MCP server via npx +**Connection:** Remote MCP server over streamable HTTP +**Endpoint:** `https://mcp.datadoghq.com/v1/mcp` (US1), configured in this plugin's `mcp.json`. No npx or `mcp-remote` is needed. **Tools:** @@ -102,17 +105,15 @@ This power has the following steering files: - Optional: `max_queries_per_dashboard` (number) - Extract widget queries - Returns: Dashboards with metadata and widget queries -11. **search_datadog_docs** - Search Datadog documentation - - Required: `query` (string) - Documentation search query - - Returns: Relevant documentation pages and guides - ## Tool Usage Examples +In the examples below, `tool_name({...})` means: call that MCP tool with the given arguments. + ### Searching Logs **Find error logs:** ```javascript -usePower("datadog", "datadog", "search_datadog_logs", { +search_datadog_logs({ "query": "service:api env:prod status:error", "from": "now-1h", "to": "now" @@ -122,7 +123,7 @@ usePower("datadog", "datadog", "search_datadog_logs", { **Search with custom attributes:** ```javascript -usePower("datadog", "datadog", "search_datadog_logs", { +search_datadog_logs({ "query": "service:checkout @http.status_code:[400 TO 599]", "from": "now-1h", "to": "now", @@ -135,7 +136,7 @@ usePower("datadog", "datadog", "search_datadog_logs", { **Service response time:** ```javascript -usePower("datadog", "datadog", "get_datadog_metric", { +get_datadog_metric({ "query": "avg:trace.servlet.request.duration{service:api,env:prod} by {resource_name}", "from": "now-4h", "to": "now" @@ -145,7 +146,7 @@ usePower("datadog", "datadog", "get_datadog_metric", { **CPU usage by host:** ```javascript -usePower("datadog", "datadog", "get_datadog_metric", { +get_datadog_metric({ "query": "avg:system.cpu.user{env:prod} by {host}", "from": "now-1h", "to": "now" @@ -155,7 +156,7 @@ usePower("datadog", "datadog", "get_datadog_metric", { **Cloud costs:** ```javascript -usePower("datadog", "datadog", "get_datadog_metric", { +get_datadog_metric({ "query": "sum:all.cost{*} by {providername}.rollup(sum, daily)", "from": "now-30d", "to": "now", @@ -168,7 +169,7 @@ usePower("datadog", "datadog", "get_datadog_metric", { **Find slow requests:** ```javascript -usePower("datadog", "datadog", "search_datadog_spans", { +search_datadog_spans({ "query": "service:api @duration:>100000000", // >100ms in nanoseconds "from": "now-1h", "to": "now" @@ -178,7 +179,7 @@ usePower("datadog", "datadog", "search_datadog_spans", { **Get full trace details:** ```javascript -usePower("datadog", "datadog", "get_datadog_trace", { +get_datadog_trace({ "trace_id": "7d5d747be160e280504c099d984bcfe0" }) // Returns: Complete trace with all spans and timing @@ -188,7 +189,7 @@ usePower("datadog", "datadog", "get_datadog_trace", { **Find slow page loads:** ```javascript -usePower("datadog", "datadog", "search_datadog_rum_events", { +search_datadog_rum_events({ "query": "@type:view @view.loading_time:>3000", "from": "now-1h", "to": "now", @@ -199,7 +200,7 @@ usePower("datadog", "datadog", "search_datadog_rum_events", { **Frontend errors:** ```javascript -usePower("datadog", "datadog", "search_datadog_rum_events", { +search_datadog_rum_events({ "query": "@type:error @application.name:\"My App\" @device.type:mobile", "from": "now-1h", "to": "now" @@ -211,7 +212,7 @@ usePower("datadog", "datadog", "search_datadog_rum_events", { **List active incidents:** ```javascript -usePower("datadog", "datadog", "search_datadog_incidents", { +search_datadog_incidents({ "query": "state:(active OR stable)" }) // Returns: Current incidents being worked on @@ -219,7 +220,7 @@ usePower("datadog", "datadog", "search_datadog_incidents", { **Get incident details:** ```javascript -usePower("datadog", "datadog", "get_datadog_incident", { +get_datadog_incident({ "incident_id": "12345" }) // Returns: Full incident timeline and updates @@ -229,7 +230,7 @@ usePower("datadog", "datadog", "get_datadog_incident", { **Find alerting monitors:** ```javascript -usePower("datadog", "datadog", "search_datadog_monitors", { +search_datadog_monitors({ "query": "status:alert muted:false env:prod" }) // Returns: Active unmuted alerts in production @@ -241,7 +242,7 @@ usePower("datadog", "datadog", "search_datadog_monitors", { ```javascript // Step 1: Find recent errors in logs -const errorLogs = usePower("datadog", "datadog", "search_datadog_logs", { +const errorLogs = search_datadog_logs({ "query": "service:checkout env:prod status:error", "from": "now-1h", "to": "now", @@ -249,24 +250,24 @@ const errorLogs = usePower("datadog", "datadog", "search_datadog_logs", { }) // Step 2: Find related error traces -const errorSpans = usePower("datadog", "datadog", "search_datadog_spans", { +const errorSpans = search_datadog_spans({ "query": "service:checkout status:error", "from": "now-1h", "to": "now" }) // Step 3: Get full trace for first error -const fullTrace = usePower("datadog", "datadog", "get_datadog_trace", { +const fullTrace = get_datadog_trace({ "trace_id": errorSpans[0].trace_id }) // Step 4: Check if there's an active incident -const incidents = usePower("datadog", "datadog", "search_datadog_incidents", { +const incidents = search_datadog_incidents({ "query": "state:active" }) // Step 5: Check related monitors -const monitors = usePower("datadog", "datadog", "search_datadog_monitors", { +const monitors = search_datadog_monitors({ "query": "tag:\"service:checkout\" status:alert" }) ``` @@ -275,35 +276,35 @@ const monitors = usePower("datadog", "datadog", "search_datadog_monitors", { ```javascript // Step 1: Identify slow requests -const slowSpans = usePower("datadog", "datadog", "search_datadog_spans", { +const slowSpans = search_datadog_spans({ "query": "service:api @duration:>100000000", // >100ms "from": "now-1h", "to": "now" }) // Step 2: Check response time metrics -const latencyMetrics = usePower("datadog", "datadog", "get_datadog_metric", { +const latencyMetrics = get_datadog_metric({ "query": "avg:trace.servlet.request.duration{service:api} by {resource_name}", "from": "now-4h", "to": "now" }) // Step 3: Check infrastructure metrics -const cpuMetrics = usePower("datadog", "datadog", "get_datadog_metric", { +const cpuMetrics = get_datadog_metric({ "query": "avg:system.cpu.user{service:api} by {host}", "from": "now-4h", "to": "now" }) // Step 4: Check for deployment correlation -const deploymentLogs = usePower("datadog", "datadog", "search_datadog_logs", { +const deploymentLogs = search_datadog_logs({ "query": "service:api @deployment.version:*", "from": "now-4h", "to": "now" }) // Step 5: Get full trace of slowest request -const slowestTrace = usePower("datadog", "datadog", "get_datadog_trace", { +const slowestTrace = get_datadog_trace({ "trace_id": slowSpans[0].trace_id }) ``` @@ -312,7 +313,7 @@ const slowestTrace = usePower("datadog", "datadog", "get_datadog_trace", { ```javascript // Step 1: Find slow page loads -const slowPages = usePower("datadog", "datadog", "search_datadog_rum_events", { +const slowPages = search_datadog_rum_events({ "query": "@type:view @view.loading_time:>3000", "from": "now-1h", "to": "now", @@ -320,21 +321,21 @@ const slowPages = usePower("datadog", "datadog", "search_datadog_rum_events", { }) // Step 2: Check for frontend errors -const frontendErrors = usePower("datadog", "datadog", "search_datadog_rum_events", { +const frontendErrors = search_datadog_rum_events({ "query": "@type:error", "from": "now-1h", "to": "now" }) // Step 3: Check backend API performance -const apiLatency = usePower("datadog", "datadog", "get_datadog_metric", { +const apiLatency = get_datadog_metric({ "query": "avg:trace.servlet.request.duration{service:api,env:prod}", "from": "now-1h", "to": "now" }) // Step 4: Check resource loading issues -const resourceErrors = usePower("datadog", "datadog", "search_datadog_rum_events", { +const resourceErrors = search_datadog_rum_events({ "query": "@type:resource @resource.status_code:[400 TO 599]", "from": "now-1h", "to": "now" @@ -345,24 +346,24 @@ const resourceErrors = usePower("datadog", "datadog", "search_datadog_rum_events ```javascript // Step 1: List all services -const services = usePower("datadog", "datadog", "search_datadog_services", { +const services = search_datadog_services({ "detailed_output": true }) // Step 2: Find traces for a service -const serviceSpans = usePower("datadog", "datadog", "search_datadog_spans", { +const serviceSpans = search_datadog_spans({ "query": "service:frontend", "from": "now-1h", "to": "now" }) // Step 3: Get full trace to see downstream calls -const dependencyTrace = usePower("datadog", "datadog", "get_datadog_trace", { +const dependencyTrace = get_datadog_trace({ "trace_id": serviceSpans[0].trace_id }) // Step 4: Check latency between services -const serviceLatency = usePower("datadog", "datadog", "get_datadog_metric", { +const serviceLatency = get_datadog_metric({ "query": "avg:trace.servlet.request.duration{env:prod} by {service}", "from": "now-4h", "to": "now" @@ -513,7 +514,6 @@ tag:"service:api" status:alert - **Group similar logs** with `group_by_message: true` - **Set appropriate max_tokens** (5000 for overview, 50000 for details) - **Use extra_fields/custom_attributes** for custom data -- **Leverage documentation search** for setup and instrumentation questions - **Check incidents first** when investigating issues ### ❌ Don't: @@ -563,60 +563,41 @@ tag:"service:api" status:alert ## Configuration -**Authentication Required**: Datadog API key and application key - -**Setup Steps:** - -1. **Get Datadog Credentials:** - - Log in to Datadog - - Navigate to Organization Settings → API Keys - - Create or copy API key - - Navigate to Organization Settings → Application Keys - - Create or copy application key - -2. **Configure in mcp.json:** - ```json - { - "mcpServers": { - "datadog": { - "command": "npx", - "args": [ - "mcp-remote", - "https://mcp.datadoghq.com/api/unstable/mcp-server/mcp" - ], - "env": { - "DD_API_KEY": "your-api-key-here", - "DD_APP_KEY": "your-app-key-here", - "DD_SITE": "datadoghq.com" - } - } - } - } - ``` - -3. **Set DD_SITE** based on your region: - - US1: `datadoghq.com` (default) - - US3: `us3.datadoghq.com` - - US5: `us5.datadoghq.com` - - EU: `datadoghq.eu` - - AP1: `ap1.datadoghq.com` +This plugin's `mcp.json` connects to the Datadog remote MCP server (streamable HTTP) at `https://mcp.datadoghq.com/v1/mcp`, the US1 endpoint. Nothing needs to be installed locally. + +**Authentication:** + +1. **OAuth 2.0 (recommended):** Your MCP client starts the login flow when the server connects. Complete the OAuth login flow when prompted. You don't manage long-lived credentials. +2. **Personal or Service Access Token:** When OAuth is not possible, for example on a server or in CI, pass the token as a bearer token in the `Authorization` header. No API key is required. +3. **API key and application key:** Alternatively, provide a Datadog API key and application key as the `DD_API_KEY` and `DD_APPLICATION_KEY` HTTP headers. Use a scoped key pair from a service account that has only the required permissions. + +Don't commit tokens or keys to a shared `mcp.json`. + +**Other Datadog sites:** The bundled endpoint is for US1. On another site, point the server at that site's endpoint: +- US3: `https://mcp.us3.datadoghq.com/v1/mcp` +- US5: `https://mcp.us5.datadoghq.com/v1/mcp` +- EU: `https://mcp.datadoghq.eu/v1/mcp` +- AP1: `https://mcp.ap1.datadoghq.com/v1/mcp` +- AP2: `https://mcp.ap2.datadoghq.com/v1/mcp` +- UK1: `https://mcp.uk1.datadoghq.com/v1/mcp` + +The US1-FED and US2-FED sites are not supported. For client-specific setup, toolsets and other options, see [Set Up the Datadog MCP Server](https://docs.datadoghq.com/bits_ai/mcp_server/setup/). ## Tips 1. **Start narrow** - Use 15m-1h time ranges, expand if needed -2. **Use steering file** - Comprehensive syntax guide with examples +2. **Use the [datadog-query-syntax](../datadog-query-syntax/SKILL.md) skill** - Comprehensive syntax guide with examples 3. **Check incidents first** - Active incidents often point to root cause 4. **Leverage unified tags** - Always use service, env, version together -5. **Search docs** - Use `search_datadog_docs` for setup questions -6. **Group logs** - Use `group_by_message` to reduce duplicate entries -7. **Get full traces** - Use trace_id from spans to get complete picture -8. **Monitor your monitors** - Check alert status during investigations -9. **Analyze dependencies** - Use full traces to understand service relationships -10. **Remember units** - Nanoseconds for spans, milliseconds for logs/RUM +5. **Group logs** - Use `group_by_message` to reduce duplicate entries +6. **Get full traces** - Use trace_id from spans to get complete picture +7. **Monitor your monitors** - Check alert status during investigations +8. **Analyze dependencies** - Use full traces to understand service relationships +9. **Remember units** - Nanoseconds for spans, milliseconds for logs/RUM --- -**Package:** `mcp-remote` + Datadog MCP Server +**Server:** Datadog remote MCP server (streamable HTTP) **Source:** Official Datadog **License:** Apache 2.0 -**Connection:** Remote MCP server with API/App key authentication +**Connection:** Remote MCP server with OAuth 2.0 authentication (or access token / API and application keys)