datadog-mcp 3.0.0 → 4.0.1

package/README.md

@@ -252,23 +252,57 @@ The `diverse` mode normalizes messages (strips UUIDs, timestamps, IPs, numbers)
 
 ## Events Aggregation
 
-Find the noisiest monitors with a single query:
+### Top Monitors Report (Best for Weekly/Daily Meteo)
+
+Get top alerting monitors with automatic context breakdown by queue, service, ingress, pod, etc:
 
 ```
 events({ action: "top", from: "7d", limit: 10 })
 ```
 
-Returns:
+Returns nested structure perfect for reports:
 ```json
 {
   "top": [
-    { "rank": 1, "name": "Error budget (SLI)", "alertCount": 44, "lastAlert": "..." },
-    { "rank": 2, "name": "High number of ready messages", "alertCount": 38, "lastAlert": "..." }
+    {
+      "rank": 1,
+      "name": "High number of ready messages",
+      "monitor_id": 67860480,
+      "total_count": 50,
+      "by_context": [
+        {"context": "queue:state-status_tasks", "count": 30},
+        {"context": "queue:updated_order_service", "count": 20}
+      ]
+    },
+    {
+      "rank": 2,
+      "name": "Nginx 5XX errors",
+      "monitor_id": 134611486,
+      "total_count": 42,
+      "by_context": [
+        {"context": "ingress:trusk-api", "count": 29},
+        {"context": "ingress:backoffice", "count": 13}
+      ]
+    }
   ]
 }
 ```
 
-For more control, use `aggregate` with custom groupBy:
+Context tags are auto-extracted: `queue:`, `service:`, `ingress:`, `pod_name:`, `kube_namespace:`, `kube_container_name:`
+
+### Tag Discovery
+
+Discover available tag prefixes in your alert data:
+
+```
+events({ action: "discover", from: "7d", tags: ["source:alert"] })
+```
+
+Returns: `{tagPrefixes: ["queue", "service", "ingress", "pod_name", "monitor", "priority"], sampleSize: 150}`
+
+### Custom Aggregation
+
+For custom grouping patterns, use `aggregate`:
 
 ```
 events({
@@ -279,7 +313,7 @@ events({
 })
 ```
 
-Supported groupBy fields: `monitor_name`, `priority`, `alert_type`, `source`, `status`, `host`
+Supported groupBy fields: `monitor_name`, `priority`, `alert_type`, `source`, `status`, `host`, or any tag prefix
 
 The aggregation uses v2 API with cursor pagination to stream through events efficiently (up to 10k events).
 

package/dist/index.js

@@ -1761,7 +1761,8 @@ var ActionSchema6 = z7.enum([
   "aggregate",
   "top",
   "timeseries",
-  "incidents"
+  "incidents",
+  "discover"
 ]);
 var InputSchema6 = {
   action: ActionSchema6.describe("Action to perform"),
@@ -1783,7 +1784,14 @@ var InputSchema6 = {
   // Phase 2: Incidents deduplication
   dedupeWindow: z7.string().optional().describe("Deduplication window for incidents: 5m, 15m, 1h (default: 5m)"),
   // Phase 3: Monitor enrichment
-  enrich: z7.boolean().optional().describe("Enrich events with monitor metadata (slower, adds monitor details)")
+  enrich: z7.boolean().optional().describe("Enrich events with monitor metadata (slower, adds monitor details)"),
+  // Context tag extraction for top action
+  contextTags: z7.array(z7.string()).optional().describe(
+    "Tag prefixes for context breakdown in top action (default: queue, service, ingress, pod_name, kube_namespace, kube_container_name)"
+  ),
+  maxEvents: z7.number().min(1).max(5e3).optional().describe(
+    "Maximum events to fetch for grouping in top action (default: 5000, max: 5000). Higher = more accurate but slower"
+  )
 };
 function extractMonitorInfo(title) {
   const priorityMatch = title.match(/^\[P(\d+)\]\s*/);
@@ -1906,6 +1914,48 @@ function formatEventV2(e) {
     } : void 0
   };
 }
+function findFirstContextTag(tags, prefixes) {
+  for (const tag of tags) {
+    const colonIndex = tag.indexOf(":");
+    if (colonIndex > 0) {
+      const prefix = tag.substring(0, colonIndex);
+      if (prefixes.has(prefix)) {
+        return tag;
+      }
+    }
+  }
+  return null;
+}
+async function discoverTagsV2(api, params, limits, site) {
+  const result = await searchEventsV2(
+    api,
+    {
+      ...params,
+      limit: 200
+    },
+    limits,
+    site
+  );
+  const prefixSet = /* @__PURE__ */ new Set();
+  for (const event of result.events) {
+    for (const tag of event.tags) {
+      if (tag.includes(":")) {
+        const prefix = tag.split(":")[0];
+        if (prefix) {
+          prefixSet.add(prefix);
+        }
+      }
+    }
+  }
+  return {
+    tagPrefixes: Array.from(prefixSet).sort((a, b) => a.localeCompare(b)),
+    sampleSize: result.events.length,
+    meta: {
+      from: result.meta.from,
+      to: result.meta.to
+    }
+  };
+}
 async function listEventsV1(api, params, limits) {
   const effectiveLimit = params.limit ?? limits.defaultLimit;
   const defaultFrom = hoursAgo(limits.defaultTimeRangeHours);
@@ -2095,34 +2145,79 @@ async function aggregateEventsV2(api, params, limits, site) {
   };
 }
 async function topEventsV2(api, params, limits, site) {
+  if (params.contextTags !== void 0) {
+    if (!Array.isArray(params.contextTags)) {
+      throw new Error("contextTags must be an array");
+    }
+    if (params.contextTags.some((tag) => typeof tag !== "string" || tag.trim() === "")) {
+      throw new Error("contextTags must be an array of non-empty strings");
+    }
+  }
   const effectiveQuery = params.query ?? "source:alert";
   const effectiveTags = params.tags ?? ["source:alert"];
-  const result = await aggregateEventsV2(
+  const result = await searchEventsV2(
     api,
     {
-      ...params,
       query: effectiveQuery,
+      from: params.from,
+      to: params.to,
+      sources: params.sources,
       tags: effectiveTags,
-      groupBy: params.groupBy ?? ["monitor_name"],
-      limit: params.limit ?? 10
+      limit: params.maxEvents ?? 5e3
     },
     limits,
     site
   );
-  return {
-    top: result.buckets.map((bucket, index) => ({
-      rank: index + 1,
-      name: bucket.key,
-      monitorId: bucket.sample.monitorId,
-      alertCount: bucket.count,
-      lastAlert: bucket.sample.timestamp,
-      sample: {
-        title: bucket.sample.title,
-        source: bucket.sample.source,
-        alertType: bucket.sample.alertType
+  const monitorGroups = /* @__PURE__ */ new Map();
+  for (const event of result.events) {
+    const monitorName = event.monitorInfo?.name ?? event.title;
+    const monitorId = event.monitorId ?? 0;
+    const key = `${monitorId}|${monitorName}`;
+    let monitorGroup = monitorGroups.get(key);
+    if (!monitorGroup) {
+      monitorGroup = { name: monitorName, monitorId, events: [] };
+      monitorGroups.set(key, monitorGroup);
+    }
+    monitorGroup.events.push(event);
+  }
+  const contextPrefixes = new Set(
+    params.contextTags ?? [
+      "queue",
+      "service",
+      "ingress",
+      "pod_name",
+      "kube_namespace",
+      "kube_container_name"
+    ]
+  );
+  const monitors = Array.from(monitorGroups.values()).map((monitor) => {
+    const contextGroups = /* @__PURE__ */ new Map();
+    for (const event of monitor.events) {
+      const contextTag = findFirstContextTag(event.tags, contextPrefixes);
+      if (contextTag) {
+        contextGroups.set(contextTag, (contextGroups.get(contextTag) || 0) + 1);
       }
-    })),
-    meta: result.meta
+    }
+    return {
+      name: monitor.name,
+      monitor_id: monitor.monitorId,
+      total_count: monitor.events.length,
+      by_context: Array.from(contextGroups.entries()).map(([context, count]) => ({ context, count })).sort((a, b) => b.count - a.count)
+      // Sort by count desc
+    };
+  }).filter((monitor) => monitor.by_context.length > 0);
+  const topMonitors = monitors.sort((a, b) => b.total_count - a.total_count).slice(0, params.limit ?? 10).map((m, i) => ({ rank: i + 1, ...m }));
+  return {
+    top: topMonitors,
+    meta: {
+      query: effectiveQuery,
+      from: result.meta.from,
+      to: result.meta.to,
+      totalMonitors: monitorGroups.size,
+      totalEvents: result.events.length,
+      contextPrefixes,
+      datadog_url: result.meta.datadog_url
+    }
   };
 }
 function parseIntervalToMs(interval) {
@@ -2411,16 +2506,15 @@ async function enrichWithMonitorMetadata(events, monitorsApi) {
 function registerEventsTool(server, apiV1, apiV2, monitorsApi, limits, readOnly = false, site = "datadoghq.com") {
   server.tool(
     "events",
-    `Track Datadog events. Actions: list, get, create, search, aggregate, top, timeseries, incidents.
-IMPORTANT: For monitor alert history, use tags: ["source:alert"] to find all triggered monitors.
-Filters: query (text search), sources, tags, priority, time range.
-Use for: monitor alerts, deployments, incidents, change tracking.
+    `Track Datadog events. Actions: list, get, create, search, aggregate, top, timeseries, incidents, discover.
+For monitor alerts, use tags: ["source:alert"].
 
-Use action:"top" with from:"7d" to find the noisiest monitors.
-Use action:"aggregate" with groupBy:["monitor_name"] for alert counts per monitor.
-Use action:"timeseries" with interval:"1h" to see alert trends over time.
-Use action:"incidents" with dedupeWindow:"5m" to deduplicate alerts into incidents.
-Use enrich:true with search to get monitor metadata (slower).`,
+top: Returns monitors with context breakdown. Example: {name, monitor_id, total_count, by_context: [{context: "queue:X", count: 30}]}
+discover: Returns available tag prefixes from events.
+aggregate: Custom groupBy, returns pipe-delimited keys.
+search: Full event details.
+timeseries: Time-bucketed trends with interval.
+incidents: Deduplicate alerts with dedupeWindow.`,
     InputSchema6,
     async ({
       action,
@@ -2439,7 +2533,8 @@ Use enrich:true with search to get monitor metadata (slower).`,
       cursor,
       interval,
       dedupeWindow,
-      enrich
+      enrich,
+      contextTags
     }) => {
       try {
         checkReadOnly(action, readOnly);
@@ -2526,8 +2621,23 @@ Use enrich:true with search to get monitor metadata (slower).`,
                   to,
                   sources,
                   tags,
-                  groupBy,
-                  limit
+                  limit,
+                  contextTags
+                },
+                limits,
+                site
+              )
+            );
+          case "discover":
+            return toolResult(
+              await discoverTagsV2(
+                apiV2,
+                {
+                  query,
+                  from,
+                  to,
+                  sources,
+                  tags
                 },
                 limits,
                 site