datadog-mcp 4.0.1 → 5.1.0

package/README.md

@@ -127,6 +127,7 @@ When running with `--transport=http`:
 | `monitors` | delete | Alerting | Delete a monitor | `monitors_write` |
 | `monitors` | mute | Alerting | Mute a monitor | `monitors_write` |
 | `monitors` | unmute | Alerting | Unmute a monitor | `monitors_write` |
+| `monitors` | top | Alerting | Top N monitors by alert frequency with real monitor names and context breakdown. Groups without context tags are included as "no_context" | `monitors_read` |
 | `dashboards` | list | Visualization | List all dashboards | `dashboards_read` |
 | `dashboards` | get | Visualization | Get dashboard by ID | `dashboards_read` |
 | `dashboards` | create | Visualization | Create a new dashboard | `dashboards_write` |
@@ -146,7 +147,7 @@ When running with `--transport=http`:
 | `events` | create | Events | Create an event | `events_read` |
 | `events` | search | Events | Search events with v2 API and cursor pagination | `events_read` |
 | `events` | aggregate | Events | Client-side aggregation by monitor_name, source, etc. | `events_read` |
-| `events` | top | Events | Top N noisiest monitors (convenience wrapper) | `events_read` |
+| `events` | top | Events | Top N event groups by count with generic groupBy support (deployments, configs, alerts, etc.). Groups without context tags are included as "no_context" | `events_read` |
 | `events` | timeseries | Events | Time-bucketed alert trends (hourly/daily counts) | `events_read` |
 | `events` | incidents | Events | Deduplicate alerts into incidents with Trigger/Recover pairing | `events_read` |
 | `incidents` | list | Incidents | List incidents | `incident_read` |
@@ -221,7 +222,26 @@ AI assistants have full control over query limits. The environment variables set
 | Metrics (timeseries) | 1000 | `pointLimit` | Data points per series (controls resolution) |
 | General tools | 50 | `limit` | Results to return |
 
-Defaults can be configured via `MCP_DEFAULT_*` environment variables.
+Defaults can be configured via `MCP_DEFAULT_*` environment variables:
+
+```json
+{
+  "mcpServers": {
+    "datadog": {
+      "command": "npx",
+      "args": ["-y", "datadog-mcp"],
+      "env": {
+        "DD_API_KEY": "your-api-key",
+        "DD_APP_KEY": "your-app-key",
+        "MCP_DEFAULT_LIMIT": "50",              // General fallback for most tools
+        "MCP_DEFAULT_LOG_LINES": "200",         // Logs search only
+        "MCP_DEFAULT_METRIC_POINTS": "1000",    // Metrics query timeseries only
+        "MCP_DEFAULT_TIME_RANGE": "24"          // Default time range in hours
+      }
+    }
+  }
+}
+```
 
 ### Compact Mode (Logs)
 
@@ -252,42 +272,74 @@ The `diverse` mode normalizes messages (strips UUIDs, timestamps, IPs, numbers)
 
 ## Events Aggregation
 
-### Top Monitors Report (Best for Weekly/Daily Meteo)
+### Top Monitors Report (Monitor-Specific)
 
-Get top alerting monitors with automatic context breakdown by queue, service, ingress, pod, etc:
+**Use `monitors` tool for monitor alerts with real monitor names:**
 
 ```
-events({ action: "top", from: "7d", limit: 10 })
+monitors({ action: "top", from: "7d", limit: 10 })
 ```
 
-Returns nested structure perfect for reports:
+Returns monitors with **real names** (including {{template.vars}}) from monitors API:
 ```json
 {
   "top": [
     {
       "rank": 1,
-      "name": "High number of ready messages",
       "monitor_id": 67860480,
+      "name": "High number of ready messages on {{queue.name}}",
+      "message": "Queue {{queue.name}} has {{value}} ready messages",
       "total_count": 50,
       "by_context": [
-        {"context": "queue:state-status_tasks", "count": 30},
-        {"context": "queue:updated_order_service", "count": 20}
+        {"context": "queue:email-notifications", "count": 30},
+        {"context": "queue:payment-processing", "count": 20}
       ]
     },
     {
       "rank": 2,
-      "name": "Nginx 5XX errors",
       "monitor_id": 134611486,
+      "name": "Nginx some requests on errors (HTTP 5XX) on {{ingress.name}}",
+      "message": "Nginx request on ingress {{ingress.name}} contains some errors (HTTP 5XX)",
       "total_count": 42,
       "by_context": [
-        {"context": "ingress:trusk-api", "count": 29},
-        {"context": "ingress:backoffice", "count": 13}
+        {"context": "ingress:api-gateway", "count": 29},
+        {"context": "ingress:admin-panel", "count": 13}
       ]
     }
   ]
 }
 ```
 
+### Top Events Report (Generic)
+
+**Use `events` tool for any event type** (deployments, configs, custom events):
+
+```
+events({ action: "top", from: "7d", limit: 10, groupBy: ["service"] })
+```
+
+Returns event groups by custom fields:
+```json
+{
+  "top": [
+    {
+      "rank": 1,
+      "service": "api-server",
+      "message": "Deployment completed",
+      "total_count": 30,
+      "by_context": [
+        {"context": "env:prod", "count": 20},
+        {"context": "env:staging", "count": 10}
+      ]
+    }
+  ]
+}
+```
+
+**Key Differences:**
+- `monitors top`: Fetches real monitor names from monitors API (slower, monitor-specific)
+- `events top`: Fast generic grouping, returns event message text (any event type)
+
 Context tags are auto-extracted: `queue:`, `service:`, `ingress:`, `pod_name:`, `kube_namespace:`, `kube_container_name:`
 
 ### Tag Discovery