holmesgpt 0.14.1a0__py3-none-any.whl → 0.14.2__py3-none-any.whl

holmes/plugins/toolsets/datadog/toolset_datadog_logs.py

@@ -3,6 +3,7 @@ from enum import Enum
 import json
 import logging
 from typing import Any, Optional, Dict, Tuple, Set
+from urllib.parse import urlencode
 from holmes.core.tools import (
     CallablePrerequisite,
     ToolsetTag,
@@ -16,6 +17,8 @@ from holmes.plugins.toolsets.datadog.datadog_api import (
     execute_paginated_datadog_http_request,
     get_headers,
     MAX_RETRY_COUNT_ON_RATE_LIMIT,
+    enhance_error_message,
+    preprocess_time_fields,
 )
 from holmes.plugins.toolsets.logging_utils.logging_api import (
     DEFAULT_TIME_SPAN_SECONDS,
@@ -99,23 +102,28 @@ def fetch_paginated_logs(
         "page": {"limit": calculate_page_size(params, dd_config, [])},
     }
 
+    # Preprocess time fields to ensure correct format
+    processed_payload = preprocess_time_fields(payload, "/api/v2/logs/events/search")
+
     logs, cursor = execute_paginated_datadog_http_request(
         url=url,
         headers=headers,
-        payload_or_params=payload,
+        payload_or_params=processed_payload,
         timeout=dd_config.request_timeout,
     )
 
     while cursor and len(logs) < limit:
-        payload["page"]["cursor"] = cursor
+        processed_payload["page"]["cursor"] = cursor
+        processed_payload["page"]["limit"] = calculate_page_size(
+            params, dd_config, logs
+        )
         new_logs, cursor = execute_paginated_datadog_http_request(
             url=url,
             headers=headers,
-            payload_or_params=payload,
+            payload_or_params=processed_payload,
             timeout=dd_config.request_timeout,
         )
         logs += new_logs
-        payload["page"]["limit"] = calculate_page_size(params, dd_config, logs)
 
     # logs are fetched descending order. Unified logging API follows the pattern of kubectl logs where oldest logs are first
     logs.reverse()
@@ -129,14 +137,73 @@ def format_logs(raw_logs: list[dict]) -> str:
     logs = []
 
     for raw_log_item in raw_logs:
+        # Extract timestamp - Datadog returns it in ISO format
+        timestamp = raw_log_item.get("attributes", {}).get("timestamp", "")
+        if not timestamp:
+            # Fallback to @timestamp if timestamp is not in attributes
+            timestamp = raw_log_item.get("attributes", {}).get("@timestamp", "")
+
+        # Extract message
         message = raw_log_item.get("attributes", {}).get(
             "message", json.dumps(raw_log_item)
         )
-        logs.append(message)
+
+        # Format as: [timestamp] message
+        if timestamp:
+            logs.append(f"[{timestamp}] {message}")
+        else:
+            logs.append(message)
 
     return "\n".join(logs)
 
 
+def generate_datadog_logs_url(
+    dd_config: DatadogLogsConfig,
+    params: FetchPodLogsParams,
+    storage_tier: DataDogStorageTier,
+) -> str:
+    """Generate a Datadog web UI URL for the logs query."""
+    from holmes.plugins.toolsets.utils import process_timestamps_to_int
+    from holmes.plugins.toolsets.datadog.datadog_api import convert_api_url_to_app_url
+
+    # Convert API URL to app URL using the shared helper
+    base_url = convert_api_url_to_app_url(dd_config.site_api_url)
+
+    # Build the query string
+    query = f"{dd_config.labels.namespace}:{params.namespace}"
+    query += f" {dd_config.labels.pod}:{params.pod_name}"
+    if params.filter:
+        filter = params.filter.replace('"', '\\"')
+        query += f' "{filter}"'
+
+    # Process timestamps - get Unix timestamps in seconds
+    (from_time_seconds, to_time_seconds) = process_timestamps_to_int(
+        start=params.start_time,
+        end=params.end_time,
+        default_time_span_seconds=DEFAULT_TIME_SPAN_SECONDS,
+    )
+
+    # Convert to milliseconds for Datadog web UI
+    from_time_ms = from_time_seconds * 1000
+    to_time_ms = to_time_seconds * 1000
+
+    # Build URL parameters matching Datadog's web UI format
+    url_params = {
+        "query": query,
+        "from_ts": str(from_time_ms),
+        "to_ts": str(to_time_ms),
+        "live": "true",
+        "storage": storage_tier.value,
+    }
+
+    # Add indexes if not default
+    if dd_config.indexes != ["*"]:
+        url_params["index"] = ",".join(dd_config.indexes)
+
+    # Construct the full URL
+    return f"{base_url}/logs?{urlencode(url_params)}"
+
+
 class DatadogLogsToolset(BasePodLoggingToolset):
     dd_config: Optional[DatadogLogsConfig] = None
 
@@ -181,29 +248,134 @@ class DatadogLogsToolset(BasePodLoggingToolset):
 
                 if raw_logs:
                     logs_str = format_logs(raw_logs)
+                    # Generate Datadog web UI URL
+                    datadog_url = generate_datadog_logs_url(
+                        self.dd_config, params, storage_tier
+                    )
+                    logs_with_link = f"{logs_str}\n\nView in Datadog: {datadog_url}"
                     return StructuredToolResult(
                         status=StructuredToolResultStatus.SUCCESS,
-                        data=logs_str,
+                        data=logs_with_link,
+                        url=datadog_url,
                         params=params.model_dump(),
                     )
 
+            # Include detailed diagnostic context
+            query = f"{self.dd_config.labels.namespace}:{params.namespace} {self.dd_config.labels.pod}:{params.pod_name}"
+            if params.filter:
+                query += f' "{params.filter}"'
+
+            # Get actual time range used
+            (from_time, to_time) = process_timestamps_to_rfc3339(
+                start_timestamp=params.start_time,
+                end_timestamp=params.end_time,
+                default_time_span_seconds=DEFAULT_TIME_SPAN_SECONDS,
+            )
+
+            # Generate Datadog web UI URL for the last storage tier checked
+            datadog_url = generate_datadog_logs_url(
+                self.dd_config, params, self.dd_config.storage_tiers[-1]
+            )
+
+            # Build diagnostic information
+            diagnostics: Dict[str, Any] = {
+                "query_executed": query,
+                "time_range": f"{from_time} to {to_time}",
+                "indexes_searched": self.dd_config.indexes,
+                "storage_tiers_checked": [
+                    tier.value for tier in self.dd_config.storage_tiers
+                ],
+                "field_mappings": {
+                    "namespace_field": self.dd_config.labels.namespace,
+                    "pod_field": self.dd_config.labels.pod,
+                },
+                "limit": params.limit or self.dd_config.default_limit,
+                "datadog_url": datadog_url,
+            }
+
+            # Format diagnostic info as structured text
+            error_msg = (
+                f"No logs found.\n\n"
+                f"Diagnostic Information:\n"
+                f"----------------------\n"
+                f"Query executed: {diagnostics['query_executed']}\n"
+                f"Time range: {diagnostics['time_range']}\n"
+                f"Indexes searched: {diagnostics['indexes_searched']}\n"
+                f"Storage tiers checked: {', '.join(str(tier) for tier in diagnostics.get('storage_tiers_checked', []))}\n"
+                f"Field mappings:\n"
+                f"  - Namespace field: {diagnostics.get('field_mappings', {}).get('namespace_field', 'N/A')}\n"
+                f"  - Pod field: {diagnostics.get('field_mappings', {}).get('pod_field', 'N/A')}\n"
+                f"Limit: {diagnostics['limit']}\n\n"
+                f"View in Datadog: {diagnostics['datadog_url']}"
+            )
+
             return StructuredToolResult(
                 status=StructuredToolResultStatus.NO_DATA,
+                error=error_msg,
+                url=datadog_url,
                 params=params.model_dump(),
             )
 
         except DataDogRequestError as e:
             logging.exception(e, exc_info=True)
 
+            # Always try to generate Datadog URL for debugging
+            try:
+                datadog_url = generate_datadog_logs_url(
+                    self.dd_config, params, self.dd_config.storage_tiers[0]
+                )
+            except Exception:
+                datadog_url = None
+
             # Provide more specific error message for rate limiting failures
             if e.status_code == 429:
                 error_msg = f"Datadog API rate limit exceeded. Failed after {MAX_RETRY_COUNT_ON_RATE_LIMIT} retry attempts."
+                if datadog_url:
+                    error_msg += f"\nView in Datadog: {datadog_url}"
+            elif e.status_code == 400:
+                # Use enhanced error message for validation errors
+                error_msg = enhance_error_message(
+                    e,
+                    "/api/v2/logs/events/search",
+                    "POST",
+                    str(self.dd_config.site_api_url),
+                )
+
+                # Add query context
+                query = f"{self.dd_config.labels.namespace}:{params.namespace} {self.dd_config.labels.pod}:{params.pod_name}"
+                if params.filter:
+                    query += f' "{params.filter}"'
+                error_msg += f"\n\nQuery attempted: {query}"
+
+                # Add Datadog web UI URL to error message
+                if datadog_url:
+                    error_msg += f"\nView in Datadog: {datadog_url}"
             else:
-                error_msg = f"Exception while querying Datadog: {str(e)}"
+                # Include full API error details and query context
+                error_msg = (
+                    f"Datadog API error (status {e.status_code}): {e.response_text}"
+                )
+                query = f"{self.dd_config.labels.namespace}:{params.namespace} {self.dd_config.labels.pod}:{params.pod_name}"
+                if params.filter:
+                    query += f' "{params.filter}"'
+                error_msg += f"\nQuery: {query}"
+
+                # Get actual time range used
+                (from_time, to_time) = process_timestamps_to_rfc3339(
+                    start_timestamp=params.start_time,
+                    end_timestamp=params.end_time,
+                    default_time_span_seconds=DEFAULT_TIME_SPAN_SECONDS,
+                )
+                error_msg += f"\nTime range: {from_time} to {to_time}"
+
+                # Add Datadog web UI URL to error message
+                if datadog_url:
+                    error_msg += f"\nView in Datadog: {datadog_url}"
 
             return StructuredToolResult(
                 status=StructuredToolResultStatus.ERROR,
                 error=error_msg,
+                url=datadog_url,
                 params=params.model_dump(),
                 invocation=json.dumps(e.payload),
             )
@@ -224,7 +396,7 @@ class DatadogLogsToolset(BasePodLoggingToolset):
         Returns (success, error_message).
         """
         try:
-            logging.info("Performing Datadog configuration healthcheck...")
+            logging.debug("Performing Datadog configuration healthcheck...")
             healthcheck_params = FetchPodLogsParams(
                 namespace="*",
                 pod_name="*",
@@ -254,7 +426,7 @@ class DatadogLogsToolset(BasePodLoggingToolset):
         if not config:
             return (
                 False,
-                TOOLSET_CONFIG_MISSING_ERROR,
+                "Datadog logs toolset requires configuration. Please provide: dd_api_key, dd_app_key, and site_api_url in your Holmes config. For more details, see https://holmesgpt.dev/data-sources/builtin-toolsets/datadog/",
             )
 
         try:

holmes/plugins/toolsets/datadog/toolset_datadog_metrics.py

@@ -54,7 +54,7 @@ class ListActiveMetrics(BaseDatadogMetricsTool):
     def __init__(self, toolset: "DatadogMetricsToolset"):
         super().__init__(
             name="list_active_datadog_metrics",
-            description=f"List active metrics from Datadog for the last {ACTIVE_METRICS_DEFAULT_LOOK_BACK_HOURS} hours. This includes metrics that have actively reported data points, including from pods no longer in the cluster.",
+            description=f"[datadog/metrics toolset] List active metrics from Datadog for the last {ACTIVE_METRICS_DEFAULT_LOOK_BACK_HOURS} hours. This includes metrics that have actively reported data points, including from pods no longer in the cluster.",
             parameters={
                 "from_time": ToolParameter(
                     description=f"Start time for listing metrics. Can be an RFC3339 formatted datetime (e.g. '2023-03-01T10:30:00Z') or a negative integer for relative seconds from now (e.g. -86400 for 24 hours ago). Defaults to {ACTIVE_METRICS_DEFAULT_LOOK_BACK_HOURS} hours ago",
@@ -149,7 +149,27 @@ class ListActiveMetrics(BaseDatadogMetricsTool):
                     f"and 'timeseries_query' permissions. Error: {str(e)}"
                 )
             else:
-                error_msg = f"Exception while querying Datadog: {str(e)}"
+                # Include full API error details for better debugging
+                error_msg = (
+                    f"Datadog API error (status {e.status_code}): {e.response_text}"
+                )
+                if params:
+                    # ListActiveMetrics parameters: from_time, host, tag_filter
+                    if params.get("host"):
+                        error_msg += f"\nHost filter: {params.get('host')}"
+                    if params.get("tag_filter"):
+                        error_msg += f"\nTag filter: {params.get('tag_filter')}"
+
+                    from_time_param = params.get("from_time")
+                    if from_time_param:
+                        time_desc = from_time_param
+                    else:
+                        time_desc = f"default (last {ACTIVE_METRICS_DEFAULT_LOOK_BACK_HOURS} hours)"
+                    error_msg += f"\nTime range: {time_desc}"
+
+                    # Note: We cannot generate a Datadog Metrics Explorer URL for ListActiveMetrics
+                    # because the Metrics Explorer requires a specific metric query,
+                    # while ListActiveMetrics just lists available metrics without querying any specific one
 
             return StructuredToolResult(
                 status=StructuredToolResultStatus.ERROR,
@@ -184,7 +204,7 @@ class QueryMetrics(BaseDatadogMetricsTool):
     def __init__(self, toolset: "DatadogMetricsToolset"):
         super().__init__(
             name="query_datadog_metrics",
-            description="Query timeseries data from Datadog for a specific metric, including historical data for pods no longer in the cluster",
+            description="[datadog/metrics toolset] Query timeseries data from Datadog for a specific metric, including historical data for pods no longer in the cluster",
             parameters={
                 "query": ToolParameter(
                     description="The metric query string (e.g., 'system.cpu.user{host:myhost}')",
@@ -261,9 +281,29 @@ class QueryMetrics(BaseDatadogMetricsTool):
             output_type = params.get("output_type", "Plain")
 
             if not series:
+                # Include detailed context in error message
+                from_time_param = params.get("from_time")
+                to_time_param = params.get("to_time")
+
+                if from_time_param:
+                    from_desc = from_time_param
+                else:
+                    from_desc = (
+                        f"default (last {DEFAULT_TIME_SPAN_SECONDS // 86400} days)"
+                    )
+
+                to_desc = to_time_param or "now"
+
+                error_msg = (
+                    f"The query returned no data.\n"
+                    f"Query: {params.get('query', 'not specified')}\n"
+                    f"Time range: {from_desc} to {to_desc}\n"
+                    f"Please check your query syntax and ensure data exists for this time range."
+                )
+
                 return StructuredToolResult(
                     status=StructuredToolResultStatus.NO_DATA,
-                    error="The query returned no data. Please check your query syntax and time range.",
+                    error=error_msg,
                     params=params,
                 )
 
@@ -333,7 +373,25 @@ class QueryMetrics(BaseDatadogMetricsTool):
                     f"and 'timeseries_query' permissions. Error: {str(e)}"
                 )
             else:
-                error_msg = f"Exception while querying Datadog: {str(e)}"
+                # Include full API error details for better debugging
+                error_msg = (
+                    f"Datadog API error (status {e.status_code}): {e.response_text}"
+                )
+                if params:
+                    error_msg += f"\nQuery: {params.get('query', 'not specified')}"
+
+                    from_time_param = params.get("from_time")
+                    to_time_param = params.get("to_time")
+
+                    if from_time_param:
+                        from_desc = from_time_param
+                    else:
+                        from_desc = (
+                            f"default (last {DEFAULT_TIME_SPAN_SECONDS // 86400} days)"
+                        )
+
+                    to_desc = to_time_param or "now"
+                    error_msg += f"\nTime range: {from_desc} to {to_desc}"
 
             return StructuredToolResult(
                 status=StructuredToolResultStatus.ERROR,
@@ -364,7 +422,7 @@ class QueryMetricsMetadata(BaseDatadogMetricsTool):
     def __init__(self, toolset: "DatadogMetricsToolset"):
         super().__init__(
             name="get_datadog_metric_metadata",
-            description="Get metadata about one or more metrics including their type, description, unit, and other properties",
+            description="[datadog/metrics toolset] Get metadata about one or more metrics including their type, description, unit, and other properties",
             parameters={
                 "metric_names": ToolParameter(
                     description="Comma-separated list of metric names to get metadata for (e.g., 'system.cpu.user, system.mem.used')",
@@ -480,7 +538,7 @@ class ListMetricTags(BaseDatadogMetricsTool):
     def __init__(self, toolset: "DatadogMetricsToolset"):
         super().__init__(
             name="list_datadog_metric_tags",
-            description="List all available tags and aggregations for a specific metric. This helps in building queries by showing what dimensions are available for filtering.",
+            description="[datadog/metrics toolset] List all available tags and aggregations for a specific metric. This helps in building queries by showing what dimensions are available for filtering.",
             parameters={
                 "metric_name": ToolParameter(
                     description="The name of the metric to get tags for (e.g., 'system.cpu.user', 'container.memory.usage')",
@@ -537,7 +595,14 @@ class ListMetricTags(BaseDatadogMetricsTool):
                     f"permissions. Error: {str(e)}"
                 )
             else:
-                error_msg = f"Exception while querying Datadog: {str(e)}"
+                # Include full API error details for better debugging
+                error_msg = (
+                    f"Datadog API error (status {e.status_code}): {e.response_text}"
+                )
+                if params:
+                    error_msg += (
+                        f"\nMetric name: {params.get('metric_name', 'not specified')}"
+                    )
 
             return StructuredToolResult(
                 status=StructuredToolResultStatus.ERROR,
@@ -586,7 +651,7 @@ class DatadogMetricsToolset(Toolset):
 
     def _perform_healthcheck(self, dd_config: DatadogMetricsConfig) -> Tuple[bool, str]:
         try:
-            logging.info("Performing Datadog metrics configuration healthcheck...")
+            logging.debug("Performing Datadog metrics configuration healthcheck...")
 
             url = f"{dd_config.site_api_url}/api/v1/validate"
             headers = get_headers(dd_config)
@@ -615,7 +680,7 @@ class DatadogMetricsToolset(Toolset):
         if not config:
             return (
                 False,
-                TOOLSET_CONFIG_MISSING_ERROR,
+                "Datadog metrics toolset requires configuration. Please provide: dd_api_key, dd_app_key, and site_api_url in your Holmes config. For more details, see https://holmesgpt.dev/data-sources/builtin-toolsets/datadog/",
             )
 
         try:

holmes/plugins/toolsets/datadog/toolset_datadog_rds.py

@@ -69,7 +69,7 @@ class GenerateRDSPerformanceReport(BaseDatadogRDSTool):
     def __init__(self, toolset: "DatadogRDSToolset"):
         super().__init__(
             name="datadog_rds_performance_report",
-            description="Generate a comprehensive performance report for a specific RDS instance including latency, resource utilization, and storage metrics with analysis",
+            description="[datadog/rds toolset] Generate a comprehensive performance report for a specific RDS instance including latency, resource utilization, and storage metrics with analysis",
             parameters={
                 "db_instance_identifier": ToolParameter(
                     description="The RDS database instance identifier",
@@ -364,7 +364,7 @@ class GetTopWorstPerformingRDSInstances(BaseDatadogRDSTool):
     def __init__(self, toolset: "DatadogRDSToolset"):
         super().__init__(
             name="datadog_rds_top_worst_performing",
-            description="Get a summarized report of the top worst performing RDS instances based on latency, CPU utilization, and error rates",
+            description="[datadog/rds toolset] Get a summarized report of the top worst performing RDS instances based on latency, CPU utilization, and error rates",
             parameters={
                 "top_n": ToolParameter(
                     description=f"Number of worst performing instances to return (default: {DEFAULT_TOP_INSTANCES})",

holmes/plugins/toolsets/datadog/toolset_datadog_traces.py

@@ -156,7 +156,7 @@ class FetchDatadogTracesList(BaseDatadogTracesTool):
     def __init__(self, toolset: "DatadogTracesToolset"):
         super().__init__(
             name="fetch_datadog_traces",
-            description="Fetch a list of traces from Datadog with optional filters",
+            description="[datadog/traces toolset] Fetch a list of traces from Datadog with optional filters",
             parameters={
                 "service": ToolParameter(
                     description="Filter by service name",
@@ -360,7 +360,7 @@ class FetchDatadogTraceById(BaseDatadogTracesTool):
     def __init__(self, toolset: "DatadogTracesToolset"):
         super().__init__(
             name="fetch_datadog_trace_by_id",
-            description="Fetch detailed information about a specific trace by its ID",
+            description="[datadog/traces toolset] Fetch detailed information about a specific trace by its ID",
             parameters={
                 "trace_id": ToolParameter(
                     description="The trace ID to fetch details for",
@@ -499,7 +499,7 @@ class FetchDatadogSpansByFilter(BaseDatadogTracesTool):
     def __init__(self, toolset: "DatadogTracesToolset"):
         super().__init__(
             name="fetch_datadog_spans",
-            description="Search for spans in Datadog with detailed filters",
+            description="[datadog/traces toolset] Search for spans in Datadog with detailed filters",
             parameters={
                 "query": ToolParameter(
                     description="Datadog search query (e.g., 'service:web-app @http.status_code:500')",

holmes/plugins/toolsets/grafana/toolset_grafana_loki.py

@@ -14,6 +14,7 @@ from holmes.plugins.toolsets.logging_utils.logging_api import (
     LoggingCapability,
     PodLoggingTool,
     DEFAULT_TIME_SPAN_SECONDS,
+    DEFAULT_LOG_LIMIT,
 )
 from holmes.plugins.toolsets.utils import (
     process_timestamps_to_rfc3339,
@@ -94,7 +95,7 @@ class GrafanaLokiToolset(BasePodLoggingToolset):
             label_value=params.pod_name,
             start=start,
             end=end,
-            limit=params.limit or 2000,
+            limit=params.limit or DEFAULT_LOG_LIMIT,
         )
         if logs:
             logs.sort(key=lambda x: x["timestamp"])

holmes/plugins/toolsets/grafana/toolset_grafana_tempo.py

@@ -242,9 +242,9 @@ Examples:
             import logging
 
             logger = logging.getLogger(__name__)
-            logger.info(f"Tempo query: {stats_query}")
+            logger.debug(f"Tempo query: {stats_query}")
 
-            logger.info(f"start: {start}, end: {end}")
+            logger.debug(f"start: {start}, end: {end}")
 
             all_traces_response = api.search_traces_by_query(
                 q=stats_query,
@@ -253,7 +253,7 @@ Examples:
                 limit=1000,
             )
 
-            logger.info(f"Response: {all_traces_response}")
+            logger.debug(f"Response: {all_traces_response}")
 
             traces = all_traces_response.get("traces", [])
             if not traces:

holmes/plugins/toolsets/logging_utils/logging_api.py

@@ -18,7 +18,7 @@ from holmes.plugins.toolsets.utils import get_param_or_raise
 DEFAULT_LOG_LIMIT = 100
 SECONDS_PER_DAY = 24 * 60 * 60
 DEFAULT_TIME_SPAN_SECONDS = 7 * SECONDS_PER_DAY  # 1 week in seconds
-DEFAULT_GRAPH_TIME_SPAN_SECONDS = 1 * SECONDS_PER_DAY  # 1 day in seconds
+DEFAULT_GRAPH_TIME_SPAN_SECONDS = 1 * 60 * 60  # 1 hour in seconds
 
 POD_LOGGING_TOOL_NAME = "fetch_pod_logs"