holmesgpt 0.13.2__py3-none-any.whl → 0.18.4__py3-none-any.whl

holmes/plugins/toolsets/datadog/toolset_datadog_traces.py

@@ -1,43 +1,47 @@
 """Datadog Traces toolset for HolmesGPT."""
 
+import copy
 import json
 import logging
 import os
-import time
+import re
 from typing import Any, Dict, Optional, Tuple
 
+from pydantic import AnyUrl
+
 from holmes.core.tools import (
     CallablePrerequisite,
+    StructuredToolResult,
+    StructuredToolResultStatus,
     Tool,
+    ToolInvokeContext,
     ToolParameter,
     Toolset,
-    StructuredToolResult,
-    ToolResultStatus,
     ToolsetTag,
 )
+from holmes.plugins.toolsets.consts import STANDARD_END_DATETIME_TOOL_PARAM_DESCRIPTION
 from holmes.plugins.toolsets.datadog.datadog_api import (
+    MAX_RETRY_COUNT_ON_RATE_LIMIT,
     DataDogRequestError,
-    DatadogBaseConfig,
     execute_datadog_http_request,
     get_headers,
-    MAX_RETRY_COUNT_ON_RATE_LIMIT,
-)
-from holmes.plugins.toolsets.utils import (
-    process_timestamps_to_int,
-    toolset_name_for_one_liner,
 )
-from holmes.plugins.toolsets.datadog.datadog_traces_formatter import (
-    format_traces_list,
-    format_trace_hierarchy,
-    format_spans_search,
+from holmes.plugins.toolsets.datadog.datadog_models import DatadogTracesConfig
+from holmes.plugins.toolsets.datadog.datadog_url_utils import (
+    generate_datadog_spans_analytics_url,
+    generate_datadog_spans_url,
 )
 from holmes.plugins.toolsets.logging_utils.logging_api import (
     DEFAULT_TIME_SPAN_SECONDS,
 )
+from holmes.plugins.toolsets.utils import (
+    process_timestamps_to_int,
+    standard_start_datetime_tool_param_description,
+    toolset_name_for_one_liner,
+)
 
-
-class DatadogTracesConfig(DatadogBaseConfig):
-    indexes: list[str] = ["*"]
+# Valid percentile aggregations supported by Datadog
+PERCENTILE_AGGREGATIONS = ["pc75", "pc90", "pc95", "pc98", "pc99"]
 
 
 class DatadogTracesToolset(Toolset):
@@ -49,27 +53,18 @@ class DatadogTracesToolset(Toolset):
         super().__init__(
             name="datadog/traces",
             description="Toolset for interacting with Datadog APM to fetch and analyze traces",
-            docs_url="https://docs.datadoghq.com/api/latest/spans/",
+            docs_url="https://holmesgpt.dev/data-sources/builtin-toolsets/datadog/",
             icon_url="https://imgix.datadoghq.com//img/about/presskit/DDlogo.jpg",
             prerequisites=[CallablePrerequisite(callable=self.prerequisites_callable)],
             tools=[
-                FetchDatadogTracesList(toolset=self),
-                FetchDatadogTraceById(toolset=self),
-                FetchDatadogSpansByFilter(toolset=self),
+                GetSpans(toolset=self),
+                AggregateSpans(toolset=self),
             ],
-            experimental=True,
             tags=[ToolsetTag.CORE],
         )
-        self._reload_instructions()
-
-    def _reload_instructions(self):
-        """Load Datadog traces specific troubleshooting instructions."""
-        template_file_path = os.path.abspath(
-            os.path.join(
-                os.path.dirname(__file__), "instructions_datadog_traces.jinja2"
-            )
+        self._load_llm_instructions_from_file(
+            os.path.dirname(__file__), "instructions_datadog_traces.jinja2"
         )
-        self._load_llm_instructions(jinja_template=f"file://{template_file_path}")
 
     def prerequisites_callable(self, config: dict[str, Any]) -> Tuple[bool, str]:
         """Check prerequisites with configuration."""
@@ -136,13 +131,12 @@ class DatadogTracesToolset(Toolset):
             return False, f"Healthcheck failed with exception: {str(e)}"
 
     def get_example_config(self) -> Dict[str, Any]:
-        """Get example configuration for this toolset."""
-        return {
-            "dd_api_key": "<your_datadog_api_key>",
-            "dd_app_key": "<your_datadog_app_key>",
-            "site_api_url": "https://api.datadoghq.com",  # or https://api.datadoghq.eu for EU
-            "request_timeout": 60,
-        }
+        example_config = DatadogTracesConfig(
+            dd_api_key="<your_datadog_api_key>",
+            dd_app_key="<your_datadog_app_key>",
+            site_api_url=AnyUrl("https://api.datadoghq.com"),
+        )
+        return example_config.model_dump(mode="json")
 
 
 class BaseDatadogTracesTool(Tool):
@@ -151,79 +145,97 @@ class BaseDatadogTracesTool(Tool):
     toolset: "DatadogTracesToolset"
 
 
-class FetchDatadogTracesList(BaseDatadogTracesTool):
-    """Tool to fetch a list of traces from Datadog."""
+# Schema defines what fields to keep in compact mode
+COMPACT_SCHEMA = {
+    "custom": {
+        "duration": True,
+        "http": {"status_code": True, "host": True, "method": True, "url": True},
+    },
+    "status": True,
+    "start_timestamp": True,
+    "end_timestamp": True,
+    "error": True,
+    "single_span": True,
+    "span_id": True,
+    "trace_id": True,
+    "parent_id": True,
+    "service": True,
+    "resource_name": True,
+    "tags": {"_filter": "startswith", "_values": ["pod_name:"]},  # Generic array filter
+}
+
+
+class GetSpans(BaseDatadogTracesTool):
+    """Tool to search for spans with specific filters."""
 
     def __init__(self, toolset: "DatadogTracesToolset"):
         super().__init__(
-            name="fetch_datadog_traces",
-            description="Fetch a list of traces from Datadog with optional filters",
+            name="fetch_datadog_spans",
+            description="Search for spans in Datadog using span syntax. "
+            "Supports wildcards (*) for pattern matching: @http.route:*payment*, resource_name:*user*, service:*api*. "
+            "Uses the DataDog api endpoint: POST /api/v2/spans/events/search with 'query' parameter.",
             parameters={
-                "service": ToolParameter(
-                    description="Filter by service name",
-                    type="string",
-                    required=False,
-                ),
-                "operation": ToolParameter(
-                    description="Filter by operation name",
+                "query": ToolParameter(
+                    description="The search query following span syntax. Supports wildcards (*) for pattern matching. Examples: @http.route:*payment*, resource_name:*user*, service:*api*. Default: *",
                     type="string",
                     required=False,
                 ),
-                "resource": ToolParameter(
-                    description="Filter by resource name",
+                "start_datetime": ToolParameter(
+                    description=standard_start_datetime_tool_param_description(
+                        DEFAULT_TIME_SPAN_SECONDS
+                    ),
                     type="string",
                     required=False,
                 ),
-                "min_duration": ToolParameter(
-                    description="Minimum duration (e.g., '5s', '500ms', '1m')",
+                "end_datetime": ToolParameter(
+                    description=STANDARD_END_DATETIME_TOOL_PARAM_DESCRIPTION,
                     type="string",
                     required=False,
                 ),
-                "start_datetime": ToolParameter(
-                    description="Start time in RFC3339 format or relative time in seconds (negative for past)",
+                "timezone": ToolParameter(
+                    description="The timezone can be specified as GMT, UTC, an offset from UTC (like UTC+1), or as a Timezone Database identifier (like America/New_York). default: UTC",
                     type="string",
                     required=False,
                 ),
-                "end_datetime": ToolParameter(
-                    description="End time in RFC3339 format or relative time in seconds (negative for past)",
+                "cursor": ToolParameter(
+                    description="The returned paging point to use to get the next results. IMPORTANT: Cursors are single-use and stateful - never reuse the same cursor value multiple times or parallelize cursor-based calls. Each response provides a new cursor for the subsequent request.",
                     type="string",
                     required=False,
                 ),
                 "limit": ToolParameter(
-                    description="Maximum number of traces to return",
+                    description="Maximum number of spans to return. Default: 10. Warning: Using values higher than 10 may result in too much data and cause the tool call to fail.",
                     type="integer",
                     required=False,
                 ),
+                "sort_desc": ToolParameter(
+                    description="Get the results in descending order. default: true",
+                    type="boolean",
+                    required=False,
+                ),
+                "compact": ToolParameter(
+                    description="Return only essential fields to reduce output size. Use with higher limits (50-100) for initial exploration, then use compact=false with lower limits (5-10) for detailed investigation. Default: True",
+                    type="boolean",
+                    required=True,
+                ),
             },
             toolset=toolset,
         )
 
     def get_parameterized_one_liner(self, params: dict) -> str:
         """Get a one-liner description of the tool invocation."""
-        filters = []
-        if "service" in params:
-            filters.append(f"service={params['service']}")
-        if "operation" in params:
-            filters.append(f"operation={params['operation']}")
-        if "min_duration" in params:
-            filters.append(f"duration>{params['min_duration']}")
-
-        filter_str = ", ".join(filters) if filters else "all"
-        return f"{toolset_name_for_one_liner(self.toolset.name)}: Fetch Traces ({filter_str})"
-
-    def _invoke(
-        self, params: dict, user_approved: bool = False
-    ) -> StructuredToolResult:
-        """Execute the tool to fetch traces."""
+        return f"{toolset_name_for_one_liner(self.toolset.name)}: Search Spans ({params['query'] if 'query' in params else ''})"
+
+    def _invoke(self, params: dict, context: ToolInvokeContext) -> StructuredToolResult:
+        """Execute the tool to search spans."""
         if not self.toolset.dd_config:
             return StructuredToolResult(
-                status=ToolResultStatus.ERROR,
+                status=StructuredToolResultStatus.ERROR,
                 error="Datadog configuration not initialized",
                 params=params,
             )
 
         url = None
-        payload = None
+        payload: Optional[Dict[str, Any]] = None
 
         try:
             # Process timestamps
@@ -237,36 +249,14 @@ class FetchDatadogTracesList(BaseDatadogTracesTool):
             from_time_ms = from_time_int * 1000
             to_time_ms = to_time_int * 1000
 
-            # Build search query
-            query_parts = []
-
-            if params.get("service"):
-                query_parts.append(f"service:{params['service']}")
-
-            if params.get("operation"):
-                query_parts.append(f"operation_name:{params['operation']}")
-
-            if params.get("resource"):
-                query_parts.append(f"resource_name:{params['resource']}")
-
-            if params.get("min_duration"):
-                # Parse duration string (e.g., "5s", "500ms", "1m")
-                duration_str = params["min_duration"].lower()
-                if duration_str.endswith("ms"):
-                    duration_ns = int(float(duration_str[:-2]) * 1_000_000)
-                elif duration_str.endswith("s"):
-                    duration_ns = int(float(duration_str[:-1]) * 1_000_000_000)
-                elif duration_str.endswith("m"):
-                    duration_ns = int(float(duration_str[:-1]) * 60 * 1_000_000_000)
-                else:
-                    # Assume milliseconds if no unit
-                    duration_ns = int(float(duration_str) * 1_000_000)
-
-                query_parts.append(f"@duration:>{duration_ns}")
-
-            query = " ".join(query_parts) if query_parts else "*"
+            query: str = params.get("query") if params.get("query") else "*"  # type: ignore
+            limit = params.get("limit") if params.get("limit") else 10
+            if params.get("sort") is not None:
+                sort = "-timestamp" if params.get("sort") else True
+            else:
+                sort = "-timestamp"
 
-            # Prepare API request - use POST search endpoint
+            # Use POST endpoint for more complex searches
             url = f"{self.toolset.dd_config.site_api_url}/api/v2/spans/events/search"
             headers = get_headers(self.toolset.dd_config)
 
@@ -280,12 +270,17 @@ class FetchDatadogTracesList(BaseDatadogTracesTool):
                             "to": str(to_time_ms),
                             "indexes": self.toolset.dd_config.indexes,
                         },
-                        "page": {"limit": params.get("limit", 50)},
-                        "sort": "-timestamp",
+                        "page": {
+                            "limit": limit,
+                        },
+                        "sort": sort,
                     },
                 }
             }
 
+            if params.get("cursor"):
+                payload["data"]["attributes"]["page"]["cursor"] = params["cursor"]
+
             response = execute_datadog_http_request(
                 url=url,
                 headers=headers,
@@ -294,32 +289,28 @@ class FetchDatadogTracesList(BaseDatadogTracesTool):
                 method="POST",
             )
 
-            # Handle tuple response from POST requests
-            if isinstance(response, tuple):
-                spans, _ = response
-            elif response:
-                spans = response.get("data", [])
-            else:
-                spans = []
-
-            # Format the traces using the formatter
-            formatted_output = format_traces_list(spans, limit=params.get("limit", 50))
-            if not formatted_output:
-                return StructuredToolResult(
-                    status=ToolResultStatus.NO_DATA,
-                    params=params,
-                    data="No matching traces found.",
-                )
+            # Apply compact filtering if requested
+            if params.get("compact", False) and "data" in response:
+                response["data"] = [
+                    self._filter_span_attributes(span) for span in response["data"]
+                ]
+
+            web_url = generate_datadog_spans_url(
+                self.toolset.dd_config,
+                query,
+                from_time_ms,
+                to_time_ms,
+            )
 
             return StructuredToolResult(
-                status=ToolResultStatus.SUCCESS,
-                data=formatted_output,
+                status=StructuredToolResultStatus.SUCCESS,
+                data=response,
                 params=params,
+                url=web_url,
             )
 
         except DataDogRequestError as e:
             logging.exception(e, exc_info=True)
-
             if e.status_code == 429:
                 error_msg = f"Datadog API rate limit exceeded. Failed after {MAX_RETRY_COUNT_ON_RATE_LIMIT} retry attempts."
             elif e.status_code == 403:
@@ -331,7 +322,7 @@ class FetchDatadogTracesList(BaseDatadogTracesTool):
                 error_msg = f"Exception while querying Datadog: {str(e)}"
 
             return StructuredToolResult(
-                status=ToolResultStatus.ERROR,
+                status=StructuredToolResultStatus.ERROR,
                 error=error_msg,
                 params=params,
                 invocation=(
@@ -344,7 +335,7 @@ class FetchDatadogTracesList(BaseDatadogTracesTool):
         except Exception as e:
             logging.exception(e, exc_info=True)
             return StructuredToolResult(
-                status=ToolResultStatus.ERROR,
+                status=StructuredToolResultStatus.ERROR,
                 error=f"Unexpected error: {str(e)}",
                 params=params,
                 invocation=(
@@ -354,219 +345,257 @@ class FetchDatadogTracesList(BaseDatadogTracesTool):
                 ),
             )
 
+    def _apply_compact_schema(self, source: dict, schema: dict) -> dict:
+        """Apply schema to filter fields from source dict."""
+        result: Dict[str, Any] = {}
+
+        for key, value in schema.items():
+            if key not in source:
+                continue
+
+            source_value = source[key]
+
+            if isinstance(value, dict):
+                # Check if it's a filter directive for arrays
+                if "_filter" in value and isinstance(source_value, list):
+                    filter_type = value["_filter"]
+                    filter_values = value.get("_values", [])
+
+                    if filter_type == "startswith":
+                        # Filter array items that start with any of the specified values
+                        filtered = [
+                            item
+                            for item in source_value
+                            if isinstance(item, str)
+                            and any(item.startswith(prefix) for prefix in filter_values)
+                        ]
+                        if filtered:
+                            result[key] = filtered
+
+                elif isinstance(source_value, dict):
+                    # Regular nested object - recurse
+                    nested_result = self._apply_compact_schema(source_value, value)
+                    if nested_result:
+                        result[key] = nested_result
+
+            elif value is True:
+                # Copy the field as-is
+                result[key] = source_value
+
+        return result
+
+    def _filter_span_attributes(self, span: dict) -> dict:
+        """Filter span to include only essential fields."""
+        filtered_span = {
+            "id": span.get("id"),
+            "type": span.get("type"),
+        }
 
-class FetchDatadogTraceById(BaseDatadogTracesTool):
-    """Tool to fetch detailed information about a specific trace."""
-
-    def __init__(self, toolset: "DatadogTracesToolset"):
-        super().__init__(
-            name="fetch_datadog_trace_by_id",
-            description="Fetch detailed information about a specific trace by its ID",
-            parameters={
-                "trace_id": ToolParameter(
-                    description="The trace ID to fetch details for",
-                    type="string",
-                    required=True,
-                ),
-            },
-            toolset=toolset,
-        )
-
-    def get_parameterized_one_liner(self, params: dict) -> str:
-        """Get a one-liner description of the tool invocation."""
-        trace_id = params.get("trace_id", "unknown")
-        return f"{toolset_name_for_one_liner(self.toolset.name)}: Fetch Trace Details ({trace_id})"
-
-    def _invoke(
-        self, params: dict, user_approved: bool = False
-    ) -> StructuredToolResult:
-        """Execute the tool to fetch trace details."""
-        if not self.toolset.dd_config:
-            return StructuredToolResult(
-                status=ToolResultStatus.ERROR,
-                error="Datadog configuration not initialized",
-                params=params,
-            )
-
-        trace_id = params.get("trace_id")
-        if not trace_id:
-            return StructuredToolResult(
-                status=ToolResultStatus.ERROR,
-                error="trace_id parameter is required",
-                params=params,
-            )
-
-        url = None
-        payload = None
-
-        try:
-            # For Datadog, we need to search for all spans with the given trace_id
-            # Using a reasonable time window (last 7 days by default)
-            current_time = int(time.time())
-            from_time_ms = (current_time - 604800) * 1000  # 7 days ago
-            to_time_ms = current_time * 1000
-
-            url = f"{self.toolset.dd_config.site_api_url}/api/v2/spans/events/search"
-            headers = get_headers(self.toolset.dd_config)
-
-            payload = {
-                "data": {
-                    "type": "search_request",
-                    "attributes": {
-                        "filter": {
-                            "query": f"trace_id:{trace_id}",
-                            "from": str(from_time_ms),
-                            "to": str(to_time_ms),
-                            "indexes": self.toolset.dd_config.indexes,
-                        },
-                        "page": {"limit": 1000},  # Get all spans for the trace
-                        "sort": "timestamp",
-                    },
-                }
-            }
-
-            response = execute_datadog_http_request(
-                url=url,
-                headers=headers,
-                payload_or_params=payload,
-                timeout=self.toolset.dd_config.request_timeout,
-                method="POST",
-            )
-
-            # Handle tuple response from POST requests
-            if isinstance(response, tuple):
-                spans, _ = response
-            elif response:
-                spans = response.get("data", [])
-            else:
-                spans = []
-
-            # Format the trace hierarchy using the formatter
-            formatted_output = format_trace_hierarchy(trace_id, spans)
-            if not formatted_output:
-                return StructuredToolResult(
-                    status=ToolResultStatus.NO_DATA,
-                    params=params,
-                    data=f"No trace found for trace_id: {trace_id}",
-                )
-
-            return StructuredToolResult(
-                status=ToolResultStatus.SUCCESS,
-                data=formatted_output,
-                params=params,
+        if "attributes" in span:
+            filtered_span["attributes"] = self._apply_compact_schema(
+                span["attributes"], COMPACT_SCHEMA
             )
 
-        except DataDogRequestError as e:
-            logging.exception(e, exc_info=True)
+        return filtered_span
 
-            if e.status_code == 429:
-                error_msg = f"Datadog API rate limit exceeded. Failed after {MAX_RETRY_COUNT_ON_RATE_LIMIT} retry attempts."
-            elif e.status_code == 403:
-                error_msg = (
-                    f"Permission denied. Ensure your Datadog Application Key has the 'apm_read' "
-                    f"permission. Error: {str(e)}"
-                )
-            else:
-                error_msg = f"Exception while querying Datadog: {str(e)}"
 
-            return StructuredToolResult(
-                status=ToolResultStatus.ERROR,
-                error=error_msg,
-                params=params,
-                invocation=(
-                    json.dumps({"url": url, "payload": payload})
-                    if url and payload
-                    else None
-                ),
-            )
-
-        except Exception as e:
-            logging.exception(e, exc_info=True)
-            return StructuredToolResult(
-                status=ToolResultStatus.ERROR,
-                error=f"Unexpected error: {str(e)}",
-                params=params,
-                invocation=(
-                    json.dumps({"url": url, "payload": payload})
-                    if url and payload
-                    else None
-                ),
-            )
-
-
-class FetchDatadogSpansByFilter(BaseDatadogTracesTool):
-    """Tool to search for spans with specific filters."""
+class AggregateSpans(BaseDatadogTracesTool):
+    """Tool to aggregate span data into buckets and compute metrics and timeseries."""
 
     def __init__(self, toolset: "DatadogTracesToolset"):
         super().__init__(
-            name="fetch_datadog_spans",
-            description="Search for spans in Datadog with detailed filters",
+            name="aggregate_datadog_spans",
+            description="Aggregate spans into buckets and compute metrics and timeseries. "
+            "Uses the DataDog api endpoint: POST /api/v2/spans/analytics/aggregate",
             parameters={
                 "query": ToolParameter(
-                    description="Datadog search query (e.g., 'service:web-app @http.status_code:500')",
-                    type="string",
-                    required=False,
-                ),
-                "service": ToolParameter(
-                    description="Filter by service name",
+                    description="Search query following span syntax. Default: '*'",
                     type="string",
                     required=False,
                 ),
-                "operation": ToolParameter(
-                    description="Filter by operation name",
+                "start_datetime": ToolParameter(
+                    description=standard_start_datetime_tool_param_description(
+                        DEFAULT_TIME_SPAN_SECONDS
+                    ),
                     type="string",
                     required=False,
                 ),
-                "resource": ToolParameter(
-                    description="Filter by resource name",
+                "end_datetime": ToolParameter(
+                    description=STANDARD_END_DATETIME_TOOL_PARAM_DESCRIPTION,
                     type="string",
                     required=False,
                 ),
-                "tags": ToolParameter(
-                    description="Filter by tags (e.g., {'env': 'production', 'version': '1.2.3'})",
-                    type="object",
-                    required=False,
+                "compute": ToolParameter(
+                    description="List of metrics to compute from the matching spans. Supports up to 10 computes at the same time.",
+                    type="array",
+                    required=True,
+                    items=ToolParameter(
+                        type="object",
+                        properties={
+                            "aggregation": ToolParameter(
+                                type="string",
+                                required=True,
+                                enum=[
+                                    "count",
+                                    "cardinality",
+                                    "sum",
+                                    "min",
+                                    "max",
+                                    "avg",
+                                    "median",
+                                ]
+                                + PERCENTILE_AGGREGATIONS,
+                                description="The aggregation method.",
+                            ),
+                            "metric": ToolParameter(
+                                type="string",
+                                required=False,
+                                description="The span attribute to aggregate. Required for all non-count aggregations",
+                            ),
+                            "type": ToolParameter(
+                                type="string",
+                                required=False,
+                                enum=["total", "timeseries"],
+                                description="Compute type for the aggregation. Default: 'total'",
+                            ),
+                            "interval": ToolParameter(
+                                type="string",
+                                required=False,
+                                description="The time buckets for timeseries results (e.g., '5m', '1h'). The time buckets' size (only used for type=timeseries) Defaults to a resolution of 150 points.",
+                            ),
+                        },
+                    ),
                 ),
-                "start_datetime": ToolParameter(
-                    description="Start time in RFC3339 format or relative time in seconds (negative for past)",
-                    type="string",
+                "group_by": ToolParameter(
+                    description="List of facets to split the aggregate data by",
+                    type="array",
                     required=False,
+                    items=ToolParameter(
+                        type="object",
+                        properties={
+                            "facet": ToolParameter(
+                                type="string",
+                                required=True,
+                                description="The span attribute to split by",
+                            ),
+                            "limit": ToolParameter(
+                                type="integer",
+                                required=False,
+                                description="Maximum number of facet groups to return. Default: 10",
+                            ),
+                            "missing": ToolParameter(
+                                type="string",
+                                required=False,
+                                description="The value to use for spans that don't have the facet",
+                            ),
+                            "sort": ToolParameter(
+                                type="object",
+                                required=False,
+                                description="Sort configuration for the groups",
+                                properties={
+                                    # Not working correctly
+                                    # "aggregation": ToolParameter(
+                                    #     type="string",
+                                    #     required=True,
+                                    #     description="The aggregation method to sort by",
+                                    # ),
+                                    "metric": ToolParameter(
+                                        type="string",
+                                        required=False,
+                                        description="The metric to sort by when using a metric aggregation. (only used for type=measure).",
+                                    ),
+                                    "type": ToolParameter(
+                                        type="string",
+                                        required=False,
+                                        enum=["alphabetical", "measure"],
+                                        description="The type of sorting to use",
+                                    ),
+                                    "order": ToolParameter(
+                                        type="string",
+                                        required=False,
+                                        enum=["asc", "desc"],
+                                        description="The sort order. Default: 'desc'",
+                                    ),
+                                },
+                            ),
+                            "total": ToolParameter(
+                                type="boolean",
+                                required=False,
+                                description="Whether to include a 'total' group with all non-faceted results",
+                            ),
+                            "histogram": ToolParameter(
+                                type="object",
+                                required=False,
+                                description="Histogram configuration for numeric facets",
+                                properties={
+                                    "interval": ToolParameter(
+                                        type="number",
+                                        required=True,
+                                        description="The bin size for the histogram",
+                                    ),
+                                    "min": ToolParameter(
+                                        type="number",
+                                        required=False,
+                                        description="The minimum value for the histogram",
+                                    ),
+                                    "max": ToolParameter(
+                                        type="number",
+                                        required=False,
+                                        description="The maximum value for the histogram",
+                                    ),
+                                },
+                            ),
+                        },
+                    ),
                 ),
-                "end_datetime": ToolParameter(
-                    description="End time in RFC3339 format or relative time in seconds (negative for past)",
+                "timezone": ToolParameter(
+                    description="The timezone for time-based results (e.g., 'GMT', 'UTC', 'America/New_York'). Default: 'UTC'",
                     type="string",
                     required=False,
                 ),
-                "limit": ToolParameter(
-                    description="Maximum number of spans to return",
-                    type="integer",
-                    required=False,
-                ),
             },
             toolset=toolset,
         )
 
     def get_parameterized_one_liner(self, params: dict) -> str:
         """Get a one-liner description of the tool invocation."""
-        if "query" in params:
-            return f"{toolset_name_for_one_liner(self.toolset.name)}: Search Spans ({params['query']})"
-
-        filters = []
-        if "service" in params:
-            filters.append(f"service={params['service']}")
-        if "operation" in params:
-            filters.append(f"operation={params['operation']}")
-
-        filter_str = ", ".join(filters) if filters else "all"
-        return f"{toolset_name_for_one_liner(self.toolset.name)}: Search Spans ({filter_str})"
-
-    def _invoke(
-        self, params: dict, user_approved: bool = False
-    ) -> StructuredToolResult:
-        """Execute the tool to search spans."""
+        query = params.get("query", "*")
+        compute_info = ""
+        if params.get("compute"):
+            aggregations = [c.get("aggregation", "") for c in params["compute"]]
+            compute_info = f" (computing: {', '.join(aggregations)})"
+        return f"{toolset_name_for_one_liner(self.toolset.name)}: Aggregate Spans ({query}){compute_info}"
+
+    def _fix_percentile_aggregations(self, compute_params: list) -> list:
+        """Fix common percentile format mistakes that the LLM makes when choosing from the enum (e.g., p95 -> pc95).
+
+        Args:
+            compute_params: List of compute parameter dictionaries
+
+        Returns:
+            List of compute parameters with corrected aggregation values
+        """
+        # Deep copy the entire compute params to avoid modifying the original
+        processed_compute = copy.deepcopy(compute_params)
+
+        # Simple replacement for each known percentile
+        for compute_item in processed_compute:
+            if isinstance(compute_item, dict) and "aggregation" in compute_item:
+                agg_value = compute_item["aggregation"]
+                # Check if it matches p\d\d pattern (e.g., p95)
+                if re.match(r"^p\d{2}$", agg_value):
+                    # Convert to pc format and check if it's valid
+                    pc_version = "pc" + agg_value[1:]
+                    if pc_version in PERCENTILE_AGGREGATIONS:
+                        compute_item["aggregation"] = pc_version
+
+        return processed_compute
+
+    def _invoke(self, params: dict, context: ToolInvokeContext) -> StructuredToolResult:
+        """Execute the tool to aggregate spans."""
         if not self.toolset.dd_config:
             return StructuredToolResult(
-                status=ToolResultStatus.ERROR,
+                status=StructuredToolResultStatus.ERROR,
                 error="Datadog configuration not initialized",
                 params=params,
             )
@@ -586,51 +615,42 @@ class FetchDatadogSpansByFilter(BaseDatadogTracesTool):
             from_time_ms = from_time_int * 1000
             to_time_ms = to_time_int * 1000
 
-            # Build search query
-            query_parts = []
-
-            # If a custom query is provided, use it as the base
-            if params.get("query"):
-                query_parts.append(params["query"])
+            query = params.get("query", "*")
 
-            # Add additional filters
-            if params.get("service"):
-                query_parts.append(f"service:{params['service']}")
-
-            if params.get("operation"):
-                query_parts.append(f"operation_name:{params['operation']}")
+            # Build the request payload
+            url = f"{self.toolset.dd_config.site_api_url}/api/v2/spans/analytics/aggregate"
+            headers = get_headers(self.toolset.dd_config)
 
-            if params.get("resource"):
-                query_parts.append(f"resource_name:{params['resource']}")
+            # Build payload attributes first
+            # Process compute parameter to fix common p95->pc95 style mistakes
+            compute_params = params.get("compute", [])
+            processed_compute = self._fix_percentile_aggregations(compute_params)
+
+            attributes: Dict[str, Any] = {
+                "filter": {
+                    "query": query,
+                    "from": str(from_time_ms),
+                    "to": str(to_time_ms),
+                },
+                "compute": processed_compute,
+            }
 
-            # Add tag filters
-            if params.get("tags"):
-                tags = params["tags"]
-                if isinstance(tags, dict):
-                    for key, value in tags.items():
-                        query_parts.append(f"@{key}:{value}")
+            # Add optional fields
+            if params.get("group_by"):
+                attributes["group_by"] = params["group_by"]
 
-            query = " ".join(query_parts) if query_parts else "*"
+            # Add options if timezone is specified
+            options: Dict[str, Any] = {}
+            if params.get("timezone"):
+                options["timezone"] = params["timezone"]
 
-            # Use POST endpoint for more complex searches
-            url = f"{self.toolset.dd_config.site_api_url}/api/v2/spans/events/search"
-            headers = get_headers(self.toolset.dd_config)
+            if options:
+                attributes["options"] = options
 
             payload = {
                 "data": {
-                    "type": "search_request",
-                    "attributes": {
-                        "filter": {
-                            "query": query,
-                            "from": str(from_time_ms),
-                            "to": str(to_time_ms),
-                            "indexes": self.toolset.dd_config.indexes,
-                        },
-                        "page": {
-                            "limit": params.get("limit", 100),
-                        },
-                        "sort": "-timestamp",
-                    },
+                    "type": "aggregate_request",
+                    "attributes": attributes,
                 }
             }
 
@@ -642,27 +662,18 @@ class FetchDatadogSpansByFilter(BaseDatadogTracesTool):
                 method="POST",
             )
 
-            # Handle tuple response from POST requests
-            if isinstance(response, tuple):
-                spans, _ = response
-            elif response:
-                spans = response.get("data", [])
-            else:
-                spans = []
-
-            # Format the spans search results using the formatter
-            formatted_output = format_spans_search(spans)
-            if not formatted_output:
-                return StructuredToolResult(
-                    status=ToolResultStatus.NO_DATA,
-                    params=params,
-                    data="No matching spans found.",
-                )
+            web_url = generate_datadog_spans_analytics_url(
+                self.toolset.dd_config,
+                query,
+                from_time_ms,
+                to_time_ms,
+            )
 
             return StructuredToolResult(
-                status=ToolResultStatus.SUCCESS,
-                data=formatted_output,
+                status=StructuredToolResultStatus.SUCCESS,
+                data=response,
                 params=params,
+                url=web_url,
             )
 
         except DataDogRequestError as e:
@@ -678,7 +689,7 @@ class FetchDatadogSpansByFilter(BaseDatadogTracesTool):
                 error_msg = f"Exception while querying Datadog: {str(e)}"
 
             return StructuredToolResult(
-                status=ToolResultStatus.ERROR,
+                status=StructuredToolResultStatus.ERROR,
                 error=error_msg,
                 params=params,
                 invocation=(
@@ -691,7 +702,7 @@ class FetchDatadogSpansByFilter(BaseDatadogTracesTool):
         except Exception as e:
             logging.exception(e, exc_info=True)
             return StructuredToolResult(
-                status=ToolResultStatus.ERROR,
+                status=StructuredToolResultStatus.ERROR,
                 error=f"Unexpected error: {str(e)}",
                 params=params,
                 invocation=(