datadog-mcp 5.5.0 → 5.6.0

package/README.md

@@ -127,7 +127,8 @@ 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` |
+| `monitors` | top | Alerting | Top N monitors by alert frequency with real monitor names and context breakdown. **WARNING:** `total_count` includes renotifies/re-evaluations (Datadog emits a renotify event every `renotify_interval` minutes while Alert). For real fires use `action=history`. | `monitors_read` |
+| `monitors` | history | Alerting | Count and list real state transitions for one monitor over a time window. Filters by `transitionType` (default `["alert","alert recovery"]` — fires+recoveries, excludes renotifies) and optional `group`. Returns `{transitions: [...], count, meta}` where `count` is the number of real transitions (e.g. for one always-Alert burn-rate monitor over 7d: 98 raw events vs **38 real transitions**). | `monitors_read`, `events_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` |
@@ -154,7 +155,7 @@ When running with `--transport=http`:
 | `events` | list | Events | List events | `events_read` |
 | `events` | get | Events | Get event by ID | `events_read` |
 | `events` | create | Events | Create an event | `events_read` |
-| `events` | search | Events | Search events with v2 API and cursor pagination | `events_read` |
+| `events` | search | Events | Search events with v2 API and cursor pagination. Optional `transitionType` filter (e.g. `["alert","alert recovery"]`) restricts to monitor state-transition events — without it, `source:alert` includes renotifies. For monitor-specific fires use `monitors action=history`. | `events_read` |
 | `events` | aggregate | Events | Client-side aggregation by monitor_name, source, etc. | `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` |

package/dist/index.js

@@ -302945,6 +302945,20 @@ var InputSchema = {
   ),
   maxEvents: external_exports.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"
+  ),
+  // Monitor transition filter (additive — see requirement 5.2 / monitors action=history)
+  transitionType: external_exports.array(
+    external_exports.enum([
+      "alert",
+      "alert recovery",
+      "warning",
+      "warning recovery",
+      "no data",
+      "no data recovery",
+      "renotify"
+    ])
+  ).optional().describe(
+    'Filter events by monitor state transition type. When set, restricts results to events with @monitor.transition.transition_type matching any value. Use ["alert","alert recovery"] to count real fires/recoveries and skip renotifies. Empty array is treated as undefined (no filter). For a fires-only count by monitor ID, prefer monitors action=history.'
   )
 };
 function extractMonitorInfo(title) {
@@ -303172,6 +303186,9 @@ async function createEventV1(api, params) {
     }
   };
 }
+function quoteIfNeeded(value) {
+  return /^[A-Za-z0-9_.-]+$/.test(value) ? value : `"${value}"`;
+}
 function buildEventQuery(params) {
   const parts = [];
   if (params.query) {
@@ -303189,6 +303206,10 @@ function buildEventQuery(params) {
   if (params.priority) {
     parts.push(`priority:${params.priority}`);
   }
+  if (params.transitionType && params.transitionType.length > 0) {
+    const inner = params.transitionType.map(quoteIfNeeded).join(" OR ");
+    parts.push(`@monitor.transition.transition_type:(${inner})`);
+  }
   return parts.length > 0 ? parts.join(" ") : "*";
 }
 async function searchEventsV2(api, params, limits, site) {
@@ -303204,7 +303225,8 @@ async function searchEventsV2(api, params, limits, site) {
     query: params.query,
     sources: params.sources,
     tags: params.tags,
-    priority: params.priority
+    priority: params.priority,
+    transitionType: params.transitionType
   });
   const effectiveLimit = params.limit ?? limits.defaultLimit;
   const body = {
@@ -303247,7 +303269,8 @@ async function aggregateEventsV2(api, params, limits, site) {
   const fullQuery = buildEventQuery({
     query: params.query,
     sources: params.sources,
-    tags: params.tags
+    tags: params.tags,
+    transitionType: params.transitionType
   });
   const groupByFields = params.groupBy ?? ["monitor_name"];
   const maxEventsToAggregate = 1e4;
@@ -303329,7 +303352,8 @@ async function topEventsV2(api, params, limits, site) {
       to: params.to,
       sources: params.sources,
       tags: effectiveTags,
-      limit: params.maxEvents ?? 5e3
+      limit: params.maxEvents ?? 5e3,
+      transitionType: params.transitionType
     },
     limits,
     site
@@ -303418,7 +303442,8 @@ async function timeseriesEventsV2(api, params, limits, site) {
   const fullQuery = buildEventQuery({
     query: params.query ?? "source:alert",
     sources: params.sources,
-    tags: params.tags
+    tags: params.tags,
+    transitionType: params.transitionType
   });
   const intervalMs = parseIntervalToMs(params.interval);
   const groupByFields = params.groupBy ?? ["monitor_name"];
@@ -303503,7 +303528,8 @@ async function incidentsEventsV2(api, params, limits, site) {
   const fullQuery = buildEventQuery({
     query: params.query ?? "source:alert",
     sources: params.sources,
-    tags: params.tags
+    tags: params.tags,
+    transitionType: params.transitionType
   });
   const dedupeWindowNs = parseDurationToNs(params.dedupeWindow ?? "5m");
   const dedupeWindowMs = dedupeWindowNs ? Math.floor(dedupeWindowNs / 1e6) : 3e5;
@@ -303691,10 +303717,17 @@ function registerEventsTool(server, apiV1, apiV2, monitorsApi, limits, readOnly
     `Track Datadog events. Actions: list, get, create, search, aggregate, top, timeseries, incidents, discover.
 For monitor alerts, use tags: ["source:alert"].
 
+IMPORTANT \u2014 re-evaluation vs transition:
+  - source:alert events INCLUDE renotifies and re-evaluations (every Datadog re-evaluation of an alerting monitor emits an event). A "how many times did monitor X fire" question answered with source:alert alone over-counts.
+  - To restrict to real state transitions, pass transitionType (e.g. ["alert","alert recovery"]). This appends @monitor.transition.transition_type:(...) to the query and matches the design's live investigation.
+  - For a fires-only numeric count rooted in a single monitor ID, prefer the higher-level primitive monitors action=history \u2014 it returns {transitions, count, meta} with the same filter applied for you.
+
+transitionType: Optional array of monitor transition types (alert, alert recovery, warning, warning recovery, no data, no data recovery, renotify). Empty array is treated as undefined.
 top: Generic event grouping by any fields (groupBy parameter). Returns groups ranked by count with optional context breakdown.
   - Example: {groupBy: ["service"], message: "...", service: "api", total_count: 50, by_context: [{context: "queue:X", count: 30}]}
   - Use for deployments, configs, custom events, or monitor alerts
   - Returns "message" field (event title), NOT monitor name (use monitors tool for real names)
+  - total_count includes renotifies when source:alert is used without transitionType \u2014 see monitors action=history for fires-only counts
 discover: Returns available tag prefixes from events.
 aggregate: Custom groupBy, returns pipe-delimited keys.
 search: Full event details.
@@ -303720,7 +303753,8 @@ incidents: Deduplicate alerts with dedupeWindow.`,
       dedupeWindow,
       enrich,
       contextTags,
-      maxEvents
+      maxEvents,
+      transitionType
     }) => {
       try {
         checkReadOnly(action, readOnly);
@@ -303769,7 +303803,8 @@ incidents: Deduplicate alerts with dedupeWindow.`,
                 tags,
                 priority,
                 limit,
-                cursor
+                cursor,
+                transitionType
               },
               limits,
               site
@@ -303791,7 +303826,8 @@ incidents: Deduplicate alerts with dedupeWindow.`,
                   sources,
                   tags,
                   groupBy,
-                  limit
+                  limit,
+                  transitionType
                 },
                 limits,
                 site
@@ -303810,7 +303846,8 @@ incidents: Deduplicate alerts with dedupeWindow.`,
                   limit,
                   groupBy,
                   contextTags,
-                  maxEvents
+                  maxEvents,
+                  transitionType
                 },
                 limits,
                 site
@@ -303843,7 +303880,8 @@ incidents: Deduplicate alerts with dedupeWindow.`,
                   tags,
                   groupBy,
                   interval,
-                  limit
+                  limit,
+                  transitionType
                 },
                 limits,
                 site
@@ -303860,7 +303898,8 @@ incidents: Deduplicate alerts with dedupeWindow.`,
                   sources,
                   tags,
                   dedupeWindow,
-                  limit
+                  limit,
+                  transitionType
                 },
                 limits,
                 site
@@ -303886,7 +303925,8 @@ var ActionSchema2 = external_exports.enum([
   "delete",
   "mute",
   "unmute",
-  "top"
+  "top",
+  "history"
 ]);
 var InputSchema2 = {
   action: ActionSchema2.describe("Action to perform"),
@@ -303907,7 +303947,24 @@ var InputSchema2 = {
   contextTags: external_exports.array(external_exports.string()).optional().describe(
     "Tag prefixes for context breakdown in top action (default: queue, service, ingress, pod_name, kube_namespace, kube_container_name)"
   ),
-  maxEvents: external_exports.number().min(1).max(5e3).optional().describe("Maximum events to fetch for top action (default: 5000, max: 5000)")
+  maxEvents: external_exports.number().min(1).max(5e3).optional().describe("Maximum events to fetch for top action (default: 5000, max: 5000)"),
+  // History action parameters
+  transitionType: external_exports.array(
+    external_exports.enum([
+      "alert",
+      "alert recovery",
+      "warning",
+      "warning recovery",
+      "no data",
+      "no data recovery",
+      "renotify"
+    ])
+  ).optional().describe(
+    'For history action: filter by monitor state transition types. Default: ["alert","alert recovery"] (real fires + recoveries, excludes renotifies). Pass ["alert"] for fires only, or include "renotify" for full chronological audit.'
+  ),
+  group: external_exports.string().optional().describe(
+    'For history action: filter transitions to a specific multi-alert monitor group (e.g., "pod_name:foo,kube_namespace:bar"). Optional; omit for all groups.'
+  )
 };
 var MonitorThresholdsSchema = external_exports.object({
   critical: external_exports.number().optional(),
@@ -304032,6 +304089,153 @@ function formatMonitorDetail(m, site = "datadoghq.com") {
   }
   return detail;
 }
+var DEFAULT_HISTORY_TRANSITION_TYPES = [
+  "alert",
+  "alert recovery"
+];
+function quoteIfNeeded2(value) {
+  return /^[A-Za-z0-9_.-]+$/.test(value) ? value : `"${value}"`;
+}
+function buildMonitorHistoryQuery(params) {
+  const parts = ["source:alert", `@monitor.id:${params.monitorId}`];
+  const transitionTypes = params.transitionType && params.transitionType.length > 0 ? params.transitionType : void 0;
+  if (transitionTypes) {
+    const inner = transitionTypes.map(quoteIfNeeded2).join(" OR ");
+    parts.push(`@monitor.transition.transition_type:(${inner})`);
+  }
+  if (params.group && params.group.length > 0) {
+    const escaped = params.group.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+    parts.push(`@monitor.groups:"${escaped}"`);
+  }
+  return parts.join(" ");
+}
+function isMonitorState(value) {
+  return value === "Alert" || value === "Warn" || value === "OK" || value === "No Data";
+}
+function isTransitionType(value) {
+  return value === "alert" || value === "alert recovery" || value === "warning" || value === "warning recovery" || value === "no data" || value === "no data recovery" || value === "renotify";
+}
+function extractTimestamp(outer, inner) {
+  const outerTs = outer.timestamp;
+  if (outerTs instanceof Date) {
+    return outerTs.toISOString();
+  }
+  if (typeof outerTs === "string" && outerTs.length > 0) {
+    const d = new Date(outerTs);
+    if (!Number.isNaN(d.getTime())) return d.toISOString();
+  }
+  const innerTs = inner.timestamp;
+  if (typeof innerTs === "number" && Number.isFinite(innerTs)) {
+    return new Date(innerTs).toISOString();
+  }
+  if (typeof innerTs === "string" && innerTs.length > 0) {
+    const parsed = Number.parseInt(innerTs, 10);
+    if (!Number.isNaN(parsed)) {
+      return new Date(parsed).toISOString();
+    }
+  }
+  return "";
+}
+function formatMonitorTransition(event) {
+  const outer = event.attributes ?? {};
+  const inner = outer.attributes ?? {};
+  const monitor = inner.monitor;
+  if (!monitor) {
+    return null;
+  }
+  const transition = monitor.transition ?? monitor.additionalProperties?.transition;
+  if (!transition) {
+    return null;
+  }
+  const fromState = isMonitorState(transition.source_state) ? transition.source_state : null;
+  const toState = isMonitorState(transition.destination_state) ? transition.destination_state : null;
+  const transitionType = isTransitionType(transition.transition_type) ? transition.transition_type : null;
+  if (!fromState || !toState || !transitionType) {
+    return null;
+  }
+  const groupsRaw = monitor.groups;
+  const group = Array.isArray(groupsRaw) && groupsRaw.length > 0 ? groupsRaw.map((g) => String(g)).join(",") : null;
+  const monitorId = typeof monitor.id === "number" ? monitor.id : 0;
+  const monitorName = typeof monitor.name === "string" && monitor.name.length > 0 ? monitor.name : `Monitor ${monitorId}`;
+  return {
+    timestamp: extractTimestamp(outer, inner),
+    monitorId,
+    monitorName,
+    group,
+    fromState,
+    toState,
+    transitionType,
+    eventId: String(event.id ?? "")
+  };
+}
+async function historyMonitor(eventsApi, monitorId, params, limits, site) {
+  const defaultFrom = hoursAgo(limits.defaultTimeRangeHours);
+  const defaultTo = now();
+  const [validFrom, validTo] = ensureValidTimeRange(
+    parseTime(params.from, defaultFrom),
+    parseTime(params.to, defaultTo)
+  );
+  const fromTime = new Date(validFrom * 1e3).toISOString();
+  const toTime = new Date(validTo * 1e3).toISOString();
+  const effectiveTransitionTypes = params.transitionType && params.transitionType.length > 0 ? params.transitionType : [...DEFAULT_HISTORY_TRANSITION_TYPES];
+  const query = buildMonitorHistoryQuery({
+    monitorId,
+    transitionType: effectiveTransitionTypes,
+    group: params.group
+  });
+  const transitions = [];
+  const maxEventsToProcess = 1e4;
+  const maxPages = 100;
+  let eventCount = 0;
+  let pageCount = 0;
+  const body = {
+    filter: {
+      query,
+      from: fromTime,
+      to: toTime
+    },
+    sort: "timestamp",
+    page: { limit: 1e3 }
+  };
+  let cursor;
+  while (pageCount < maxPages && eventCount < maxEventsToProcess) {
+    const pageBody = { ...body, page: { ...body.page, cursor } };
+    const response = await eventsApi.searchEvents({ body: pageBody });
+    const events = response.data ?? [];
+    if (events.length === 0) break;
+    for (const event of events) {
+      const transition = formatMonitorTransition(event);
+      if (transition !== null) {
+        transitions.push(transition);
+      }
+      eventCount++;
+      if (eventCount >= maxEventsToProcess) break;
+    }
+    cursor = response.meta?.page?.after;
+    if (!cursor) break;
+    pageCount++;
+  }
+  const truncated = eventCount >= maxEventsToProcess;
+  const resolvedGroup = params.group && params.group.length > 0 ? params.group : null;
+  const count = transitions.length;
+  const meta = {
+    monitorId,
+    query,
+    from: fromTime,
+    to: toTime,
+    transitionTypes: effectiveTransitionTypes,
+    group: resolvedGroup,
+    count,
+    totalFetched: eventCount,
+    truncated,
+    datadog_url: buildEventsUrl(query, validFrom, validTo, site)
+  };
+  return {
+    transitions,
+    count,
+    meta
+  };
+}
 async function listMonitors(api, params, limits, site) {
   const effectiveLimit = params.limit ?? limits.defaultLimit;
   const response = await api.listMonitors({
@@ -304339,7 +304543,7 @@ async function topMonitors(eventsApi, monitorsApi, params, limits, site) {
 function registerMonitorsTool(server, api, eventsApi, limits, readOnly = false, site = "datadoghq.com") {
   server.tool(
     "monitors",
-    `Manage Datadog monitors. Actions: list, get, search, create, update, delete, mute, unmute, top.
+    `Manage Datadog monitors. Actions: list, get, search, create, update, delete, mute, unmute, top, history.
 Filters: name, tags, groupStates (alert/warn/ok/no data).
 get/create/update return the full options object so callers can safely read-then-patch.
 
@@ -304361,8 +304565,25 @@ top: Ranked monitors by alert frequency with real monitor names and context brea
   - Returns: {rank, monitor_id, name (with {{template.vars}}), message (template), total_count, by_context}
   - Perfect for weekly/daily alert reports
   - Gets real monitor names from monitors API (not event titles)
-
-For generic event grouping (deployments, configs), use events tool instead.`,
+  - WARNING: total_count is the raw alert-event count and INCLUDES renotifies/re-evaluations.
+    For monitors stuck in Alert state, Datadog emits a renotify event every renotify_interval
+    minutes, which inflates this count well beyond the number of real fires. When the question
+    is "how many times did this monitor actually fire", use action=history instead.
+
+history: Count and list real state transitions for one monitor over a time window.
+  - Inputs: id (required, monitor ID), from/to (optional time range), transitionType (optional
+    filter, defaults to ["alert","alert recovery"]), group (optional multi-alert group filter).
+  - Returns: {transitions: [{timestamp, monitorId, monitorName, group, fromState, toState,
+    transitionType, eventId}], count, meta}
+  - count = transitions.length \u2014 the number of REAL state changes (fires + recoveries by
+    default), NOT the renotify-inflated count returned by action=top or events action=search.
+  - Backed by Datadog v2 events search with a hardcoded source:alert + @monitor.transition.
+    transition_type filter that excludes renotifies by default. To include renotifies, pass
+    transitionType including "renotify".
+
+For generic event grouping (deployments, configs), use events tool instead. Note that the
+events tool's action=search with source:alert ALSO includes renotifies; use its
+transitionType filter (or this action=history) for fires-only counts.`,
     InputSchema2,
     async ({
       action,
@@ -304377,7 +304598,9 @@ For generic event grouping (deployments, configs), use events tool instead.`,
       from,
       to,
       contextTags,
-      maxEvents
+      maxEvents,
+      transitionType,
+      group
     }) => {
       try {
         checkReadOnly(action, readOnly);
@@ -304432,6 +304655,22 @@ For generic event grouping (deployments, configs), use events tool instead.`,
                 site
               )
             );
+          case "history": {
+            const monitorIdString = requireParam(id, "id", "history");
+            const monitorId = Number.parseInt(monitorIdString, 10);
+            if (Number.isNaN(monitorId)) {
+              throw new Error(`Invalid monitor ID: ${monitorIdString}`);
+            }
+            return toolResult(
+              await historyMonitor(
+                eventsApi,
+                monitorId,
+                { from, to, transitionType, group },
+                limits,
+                site
+              )
+            );
+          }
           default:
             throw new Error(`Unknown action: ${action}`);
         }