holmesgpt 0.16.2a0__py3-none-any.whl → 0.18.4__py3-none-any.whl

holmes/plugins/toolsets/git.py

@@ -1,21 +1,20 @@
 import base64
 import logging
-import requests  # type: ignore
 import os
-from typing import Any, Optional, Dict, List, Tuple
+from typing import Any, Dict, List, Optional, Tuple
+
+import requests  # type: ignore
 from pydantic import BaseModel
+
 from holmes.core.tools import (
+    CallablePrerequisite,
     StructuredToolResult,
     StructuredToolResultStatus,
-    ToolInvokeContext,
-)
-
-from holmes.core.tools import (
-    Toolset,
     Tool,
+    ToolInvokeContext,
     ToolParameter,
+    Toolset,
     ToolsetTag,
-    CallablePrerequisite,
 )
 from holmes.plugins.toolsets.utils import toolset_name_for_one_liner
 

holmes/plugins/toolsets/grafana/base_grafana_toolset.py

@@ -1,12 +1,11 @@
 import logging
+from abc import abstractmethod
 from typing import Any, ClassVar, Tuple, Type
 
 from holmes.core.tools import CallablePrerequisite, Tool, Toolset, ToolsetTag
 from holmes.plugins.toolsets.consts import TOOLSET_CONFIG_MISSING_ERROR
 from holmes.plugins.toolsets.grafana.common import GrafanaConfig
 
-from holmes.plugins.toolsets.grafana.grafana_api import grafana_health_check
-
 
 class BaseGrafanaToolset(Toolset):
     config_class: ClassVar[Type[GrafanaConfig]] = GrafanaConfig
@@ -39,16 +38,29 @@ class BaseGrafanaToolset(Toolset):
 
         try:
             self._grafana_config = self.config_class(**config)
-            return grafana_health_check(self._grafana_config)
+            return self.health_check()
 
         except Exception as e:
             logging.exception(f"Failed to set up grafana toolset {self.name}")
             return False, str(e)
 
+    @abstractmethod
+    def health_check(self) -> Tuple[bool, str]:
+        """
+        Check if the toolset is healthy and can connect to its data source.
+
+        Subclasses must implement this method to verify connectivity.
+        This method should NOT raise exceptions - catch them internally
+        and return (False, "error message") instead.
+
+        Returns:
+            Tuple[bool, str]: (True, "") on success, (False, "error message") on failure.
+        """
+        raise NotImplementedError("Subclasses must implement health_check()")
+
     def get_example_config(self):
         example_config = GrafanaConfig(
             api_key="YOUR API KEY",
             url="YOUR GRAFANA URL",
-            grafana_datasource_uid="UID OF DATASOURCE IN GRAFANA",
         )
         return example_config.model_dump()

holmes/plugins/toolsets/grafana/common.py

@@ -1,9 +1,6 @@
-import json
 from typing import Dict, Optional
-from pydantic import BaseModel
-import datetime
 
-from holmes.core.tools import StructuredToolResult, StructuredToolResultStatus
+from pydantic import BaseModel
 
 
 class GrafanaConfig(BaseModel):
@@ -19,7 +16,7 @@ class GrafanaConfig(BaseModel):
     url: str
     grafana_datasource_uid: Optional[str] = None
     external_url: Optional[str] = None
-    healthcheck: Optional[str] = "ready"
+    verify_ssl: bool = True
 
 
 def build_headers(api_key: Optional[str], additional_headers: Optional[Dict[str, str]]):
@@ -36,19 +33,6 @@ def build_headers(api_key: Optional[str], additional_headers: Optional[Dict[str,
     return headers
 
 
-def format_log(log: Dict) -> str:
-    log_str = log.get("log", "")
-    timestamp_nanoseconds = log.get("timestamp")
-    if timestamp_nanoseconds:
-        timestamp_seconds = int(timestamp_nanoseconds) // 1_000_000_000
-        dt = datetime.datetime.fromtimestamp(timestamp_seconds)
-        log_str = dt.strftime("%Y-%m-%dT%H:%M:%SZ") + " " + log_str
-    else:
-        log_str = json.dumps(log)
-
-    return log_str
-
-
 def get_base_url(config: GrafanaConfig) -> str:
     if config.grafana_datasource_uid:
         return f"{config.url}/api/datasources/proxy/uid/{config.grafana_datasource_uid}"
@@ -56,18 +40,6 @@ def get_base_url(config: GrafanaConfig) -> str:
         return config.url
 
 
-def ensure_grafana_uid_or_return_error_result(
-    config: GrafanaConfig,
-) -> Optional[StructuredToolResult]:
-    if not config.grafana_datasource_uid:
-        return StructuredToolResult(
-            status=StructuredToolResultStatus.ERROR,
-            error="This tool only works when the toolset is configued ",
-        )
-    else:
-        return None
-
-
 class GrafanaTempoLabelsConfig(BaseModel):
     pod: str = "k8s.pod.name"
     namespace: str = "k8s.namespace.name"

holmes/plugins/toolsets/grafana/grafana_tempo_api.py

@@ -13,7 +13,6 @@ from holmes.plugins.toolsets.grafana.common import (
     get_base_url,
 )
 
-
 logger = logging.getLogger(__name__)
 
 
@@ -104,6 +103,7 @@ class GrafanaTempoAPI:
                 headers=self.headers,
                 params=params,
                 timeout=timeout,
+                verify=self.config.verify_ssl,
             )
             response.raise_for_status()
             return response.json()
@@ -145,6 +145,7 @@ class GrafanaTempoAPI:
                 url,
                 headers=self.headers,
                 timeout=30,
+                verify=self.config.verify_ssl,
             )
 
             # Just check status code, don't try to parse JSON

holmes/plugins/toolsets/grafana/loki/instructions.jinja2

@@ -1,9 +1,25 @@
 Grafana Loki is a multi-tenant log aggregation system designed to store and query logs from all your applications and infrastructure.
 
-* Deleted K8s objects don’t delete their past logs. You can still find them by time-bounded queries on stable labels (e.g., namespace + app) or by regex on pod names.
-* If you can't find the kubernetes workload in the cluster YOU SHOULD still try to find logs from it using non specific values on labels.
+**IMPORTANT WILDCARD USAGE:**
+- **ALWAYS use wildcards** when searching for pods unless you have the COMPLETE pod name with all suffixes
+- Kubernetes pod names include deployment hash + replica ID (e.g., `nginx-ingress-7b9899-x2km9`, `frontend-5f4d3b2a1-abc123`)
+- When user says "nginx pod" or "frontend pod", search for `nginx-*` or `frontend-*` NOT just `nginx` or `frontend`
+- Loki supports wildcards: `*` matches any characters (e.g., `nginx-*`, `*ingress*`, `*-x2km9`)
+- For partial matches, use wildcards on both sides: `*keyword*` to find logs from any pod containing "keyword"
+
+**When user provides what looks like a complete pod name** (e.g., `my-workload-5f9d8b7c4d-x2km9`):
+- Query Loki directly with that exact pod name
+- Do NOT try to verify if the pod exists in Kubernetes first
+- This allows querying historical pods that have been deleted/replaced
+
 * If asked to check for logs, you must always try 1-2 of the best queries you can construct to search for the logs.
 
 Loki indexes log lines using labels to help find relevant log lines.
 For example a default Kubernetes labels setup would look like that
 {namespace="prod", app="backend-api", container="api", pod="backend-api-68b7d9df9c-xyz12", stream="stdout"}
+
+
+### Time Parameters
+- Use RFC3339 format: `2023-03-01T10:30:00Z`
+- Or relative seconds: `-3600` for 1 hour ago
+- If no time range is specificed use last 4 hours as default time.

holmes/plugins/toolsets/grafana/loki/toolset_grafana_loki.py

@@ -1,7 +1,11 @@
-from typing import Dict
-import os
 import json
+import os
+from typing import Dict, Optional, Tuple
+from urllib.parse import quote
+
 from holmes.core.tools import (
+    StructuredToolResult,
+    StructuredToolResultStatus,
     Tool,
     ToolInvokeContext,
     ToolParameter,
@@ -9,26 +13,85 @@ from holmes.core.tools import (
 from holmes.plugins.toolsets.consts import (
     STANDARD_END_DATETIME_TOOL_PARAM_DESCRIPTION,
 )
-
-from holmes.plugins.toolsets.grafana.common import get_base_url
-from holmes.plugins.toolsets.grafana.toolset_grafana import BaseGrafanaToolset
-from holmes.plugins.toolsets.utils import (
-    process_timestamps_to_rfc3339,
-    standard_start_datetime_tool_param_description,
+from holmes.plugins.toolsets.grafana.common import GrafanaConfig, get_base_url
+from holmes.plugins.toolsets.grafana.loki_api import (
+    execute_loki_query,
 )
+from holmes.plugins.toolsets.grafana.toolset_grafana import BaseGrafanaToolset
 from holmes.plugins.toolsets.logging_utils.logging_api import (
-    DEFAULT_TIME_SPAN_SECONDS,
     DEFAULT_LOG_LIMIT,
+    DEFAULT_TIME_SPAN_SECONDS,
 )
-from holmes.plugins.toolsets.grafana.loki_api import (
-    execute_loki_query,
+from holmes.plugins.toolsets.utils import (
+    process_timestamps_to_rfc3339,
+    standard_start_datetime_tool_param_description,
+    toolset_name_for_one_liner,
 )
 
-from holmes.plugins.toolsets.utils import toolset_name_for_one_liner
-from holmes.core.tools import StructuredToolResult, StructuredToolResultStatus
+
+def _build_grafana_loki_explore_url(
+    config: GrafanaConfig, query: str, start: str, end: str, limit: int = 100
+) -> Optional[str]:
+    if not config.grafana_datasource_uid:
+        return None
+    try:
+        base_url = config.external_url or config.url
+        datasource_uid = config.grafana_datasource_uid or "loki"
+
+        from_str = start if start else "now-1h"
+        to_str = end if end else "now"
+
+        pane_id = "tmp"
+        safe_query = query if query else "{}"
+        panes = {
+            pane_id: {
+                "datasource": datasource_uid,
+                "queries": [
+                    {
+                        "refId": "A",
+                        "datasource": {"type": "loki", "uid": datasource_uid},
+                        "expr": safe_query,
+                        "queryType": "range",
+                        "maxLines": limit,
+                    }
+                ],
+                "range": {"from": from_str, "to": to_str},
+            }
+        }
+
+        panes_encoded = quote(
+            json.dumps(panes, separators=(",", ":"), ensure_ascii=False), safe=""
+        )
+        return f"{base_url}/explore?schemaVersion=1&panes={panes_encoded}&orgId=1"
+    except Exception:
+        return None
 
 
 class GrafanaLokiToolset(BaseGrafanaToolset):
+    def health_check(self) -> Tuple[bool, str]:
+        """Test a dummy query to check if service available."""
+        (start, end) = process_timestamps_to_rfc3339(
+            start_timestamp=-1,
+            end_timestamp=None,
+            default_time_span_seconds=DEFAULT_TIME_SPAN_SECONDS,
+        )
+
+        c = self._grafana_config
+        try:
+            _ = execute_loki_query(
+                base_url=get_base_url(c),
+                api_key=c.api_key,
+                headers=c.headers,
+                query='{job="test_endpoint"}',
+                start=start,
+                end=end,
+                limit=1,
+                verify_ssl=c.verify_ssl,
+            )
+        except Exception as e:
+            return False, f"Unable to connect to Loki.\n{str(e)}"
+        return True, ""
+
     def __init__(self):
         super().__init__(
             name="grafana/loki",
@@ -68,7 +131,7 @@ class LokiQuery(Tool):
             required=False,
         ),
         "limit": ToolParameter(
-            description="Maximum number of entries to return (default: 100)",
+            description=f"Maximum number of entries to return (default: {DEFAULT_LOG_LIMIT})",
             type="integer",
             required=False,
         ),
@@ -85,28 +148,39 @@ class LokiQuery(Tool):
         )
 
         config = self.toolset._grafana_config
+        query_str = params.get("query", '{query="no_query_fallback"}')
         try:
             data = execute_loki_query(
                 base_url=get_base_url(config),
                 api_key=config.api_key,
                 headers=config.headers,
-                query=params.get(
-                    "query", '{query="no_query_fallback"}'
-                ),  # make sure a string returns. fall back to query that will return nothing.
+                query=query_str,
                 start=start,
                 end=end,
                 limit=params.get("limit") or DEFAULT_LOG_LIMIT,
+                verify_ssl=config.verify_ssl,
             )
+
+            explore_url = _build_grafana_loki_explore_url(
+                config,
+                query_str,
+                start,
+                end,
+                limit=params.get("limit") or DEFAULT_LOG_LIMIT,
+            )
+
             if data:
                 return StructuredToolResult(
                     status=StructuredToolResultStatus.SUCCESS,
-                    data=json.dumps(data),
+                    data=data,
                     params=params,
+                    url=explore_url,
                 )
             else:
                 return StructuredToolResult(
                     status=StructuredToolResultStatus.NO_DATA,
                     params=params,
+                    url=explore_url,
                 )
         except Exception as e:
             return StructuredToolResult(

holmes/plugins/toolsets/grafana/loki_api.py

@@ -42,6 +42,7 @@ def execute_loki_query(
     start: Union[int, str],
     end: Union[int, str],
     limit: int,
+    verify_ssl: bool = True,
 ) -> List[Dict]:
     params = {"query": query, "limit": limit, "start": start, "end": end}
     try:
@@ -50,6 +51,7 @@ def execute_loki_query(
             url,
             headers=build_headers(api_key=api_key, additional_headers=headers),
             params=params,  # type: ignore
+            verify=verify_ssl,
         )
         response.raise_for_status()
 
@@ -74,6 +76,7 @@ def query_loki_logs_by_label(
     label: str,
     namespace_search_key: str = "namespace",
     limit: int = 200,
+    verify_ssl: bool = True,
 ) -> List[Dict]:
     query = f'{{{namespace_search_key}="{namespace}", {label}="{label_value}"}}'
     if filter:
@@ -86,4 +89,5 @@ def query_loki_logs_by_label(
         start=start,
         end=end,
         limit=limit,
+        verify_ssl=verify_ssl,
     )

holmes/plugins/toolsets/grafana/toolset_grafana.py

@@ -1,29 +1,50 @@
 import os
-from typing import ClassVar, Dict, Optional, Type, cast
-from urllib.parse import urljoin
 from abc import ABC
+from typing import Any, ClassVar, Dict, Optional, Tuple, Type, cast
+from urllib.parse import urlencode, urljoin
+
+import requests  # type: ignore
+
 from holmes.core.tools import (
     StructuredToolResult,
+    StructuredToolResultStatus,
     Tool,
     ToolInvokeContext,
     ToolParameter,
-    StructuredToolResultStatus,
 )
 from holmes.plugins.toolsets.grafana.base_grafana_toolset import BaseGrafanaToolset
-import requests  # type: ignore
-
 from holmes.plugins.toolsets.grafana.common import (
-    get_base_url,
     GrafanaConfig,
     build_headers,
+    get_base_url,
 )
+from holmes.plugins.toolsets.json_filter_mixin import JsonFilterMixin
 from holmes.plugins.toolsets.utils import toolset_name_for_one_liner
 
 
 class GrafanaDashboardConfig(GrafanaConfig):
-    """Configuration specific to Grafana Dashboard toolset with api/health as default healthcheck"""
-
-    healthcheck: Optional[str] = "api/health"
+    """Configuration specific to Grafana Dashboard toolset."""
+
+    pass
+
+
+def _build_grafana_dashboard_url(
+    config: GrafanaDashboardConfig,
+    uid: Optional[str] = None,
+    query_params: Optional[Dict[str, Any]] = None,
+) -> Optional[str]:
+    try:
+        base_url = config.external_url or config.url
+        if uid:
+            return f"{base_url.rstrip('/')}/d/{uid}"
+        else:
+            query_string = urlencode(query_params, doseq=True) if query_params else ""
+            if query_string:
+                return f"{base_url.rstrip('/')}/dashboards?{query_string}"
+            else:
+                return f"{base_url.rstrip('/')}/dashboards"
+    except Exception:
+        return None
 
 
 class GrafanaToolset(BaseGrafanaToolset):
@@ -47,6 +68,15 @@ class GrafanaToolset(BaseGrafanaToolset):
             os.path.dirname(__file__), "toolset_grafana_dashboard.jinja2"
         )
 
+    def health_check(self) -> Tuple[bool, str]:
+        """Test connectivity by invoking GetDashboardTags tool."""
+        tool = GetDashboardTags(self)
+        try:
+            _ = tool._make_grafana_request("api/dashboards/tags", {})
+            return True, ""
+        except Exception as e:
+            return False, f"Failed to connect to Grafana {str(e)}"
+
     @property
     def grafana_config(self) -> GrafanaDashboardConfig:
         return cast(GrafanaDashboardConfig, self._grafana_config)
@@ -76,14 +106,21 @@ class BaseGrafanaTool(Tool, ABC):
         Returns:
             StructuredToolResult with the API response data
         """
-        url = urljoin(get_base_url(self._toolset.grafana_config), endpoint)
+        base_url = get_base_url(self._toolset.grafana_config)
+        if not base_url.endswith("/"):
+            base_url += "/"
+        url = urljoin(base_url, endpoint)
         headers = build_headers(
             api_key=self._toolset.grafana_config.api_key,
             additional_headers=self._toolset.grafana_config.headers,
         )
 
         response = requests.get(
-            url, headers=headers, params=query_params, timeout=timeout
+            url,
+            headers=headers,
+            params=query_params,
+            timeout=timeout,
+            verify=self._toolset.grafana_config.verify_ssl,
         )
         response.raise_for_status()
         data = response.json()
@@ -186,46 +223,83 @@ class SearchDashboards(BaseGrafanaTool):
         if params.get("page"):
             query_params["page"] = params["page"]
 
-        return self._make_grafana_request("/api/search", params, query_params)
+        result = self._make_grafana_request("api/search", params, query_params)
+
+        config = self._toolset.grafana_config
+        search_url = _build_grafana_dashboard_url(config, query_params=query_params)
+
+        if params.get("dashboardUIDs"):
+            uids = [
+                uid.strip() for uid in params["dashboardUIDs"].split(",") if uid.strip()
+            ]
+            if len(uids) == 1:
+                search_url = _build_grafana_dashboard_url(config, uid=uids[0])
+
+        return StructuredToolResult(
+            status=result.status,
+            data=result.data,
+            params=result.params,
+            url=search_url if search_url else None,
+        )
 
     def get_parameterized_one_liner(self, params: Dict) -> str:
         return f"{toolset_name_for_one_liner(self._toolset.name)}: Search Dashboards"
 
 
-class GetDashboardByUID(BaseGrafanaTool):
+class GetDashboardByUID(JsonFilterMixin, BaseGrafanaTool):
     def __init__(self, toolset: GrafanaToolset):
         super().__init__(
             toolset=toolset,
             name="grafana_get_dashboard_by_uid",
             description="Get a dashboard by its UID using the /api/dashboards/uid/:uid endpoint",
-            parameters={
-                "uid": ToolParameter(
-                    description="The unique identifier of the dashboard",
-                    type="string",
-                    required=True,
-                ),
-            },
+            parameters=self.extend_parameters(
+                {
+                    "uid": ToolParameter(
+                        description="The unique identifier of the dashboard",
+                        type="string",
+                        required=True,
+                    )
+                }
+            ),
         )
 
     def _invoke(self, params: dict, context: ToolInvokeContext) -> StructuredToolResult:
         uid = params["uid"]
-        return self._make_grafana_request(f"/api/dashboards/uid/{uid}", params)
+        result = self._make_grafana_request(f"api/dashboards/uid/{uid}", params)
+
+        dashboard_url = _build_grafana_dashboard_url(
+            self._toolset.grafana_config, uid=uid
+        )
+
+        filtered_result = self.filter_result(result, params)
+        filtered_result.url = dashboard_url if dashboard_url else result.url
+        return filtered_result
 
     def get_parameterized_one_liner(self, params: Dict) -> str:
         return f"{toolset_name_for_one_liner(self._toolset.name)}: Get Dashboard {params.get('uid', '')}"
 
 
-class GetHomeDashboard(BaseGrafanaTool):
+class GetHomeDashboard(JsonFilterMixin, BaseGrafanaTool):
     def __init__(self, toolset: GrafanaToolset):
         super().__init__(
             toolset=toolset,
             name="grafana_get_home_dashboard",
             description="Get the home dashboard using the /api/dashboards/home endpoint",
-            parameters={},
+            parameters=self.extend_parameters({}),
         )
 
     def _invoke(self, params: dict, context: ToolInvokeContext) -> StructuredToolResult:
-        return self._make_grafana_request("/api/dashboards/home", params)
+        result = self._make_grafana_request("api/dashboards/home", params)
+        config = self._toolset.grafana_config
+        dashboard_url = None
+        if isinstance(result.data, dict):
+            uid = result.data.get("dashboard", {}).get("uid")
+            if uid:
+                dashboard_url = _build_grafana_dashboard_url(config, uid=uid)
+
+        filtered_result = self.filter_result(result, params)
+        filtered_result.url = dashboard_url if dashboard_url else None
+        return filtered_result
 
     def get_parameterized_one_liner(self, params: Dict) -> str:
         return f"{toolset_name_for_one_liner(self._toolset.name)}: Get Home Dashboard"
@@ -241,7 +315,17 @@ class GetDashboardTags(BaseGrafanaTool):
         )
 
     def _invoke(self, params: dict, context: ToolInvokeContext) -> StructuredToolResult:
-        return self._make_grafana_request("/api/dashboards/tags", params)
+        result = self._make_grafana_request("api/dashboards/tags", params)
+
+        config = self._toolset.grafana_config
+        tags_url = _build_grafana_dashboard_url(config)
+
+        return StructuredToolResult(
+            status=result.status,
+            data=result.data,
+            params=result.params,
+            url=tags_url,
+        )
 
     def get_parameterized_one_liner(self, params: Dict) -> str:
         return f"{toolset_name_for_one_liner(self._toolset.name)}: Get Dashboard Tags"

holmes/plugins/toolsets/grafana/toolset_grafana_dashboard.jinja2

@@ -1,4 +1,26 @@
 ---
+  ## **IMPORTANT: Handling Grafana Dashboard URLs**
+
+  **When the user provides a Grafana dashboard URL (e.g., http://some-domain.com/d/09ec8aa1e996d6ffcd6817bbaff4db1b/kubernetes-api-server):**
+
+  1. **DO NOT use the internet/fetch_webpage tool** - Grafana URLs should always be handled by the grafana dashboards toolset
+  2. **Extract the dashboard parameters from the URL:**
+     - Pattern: `/d/{uid}/{dashboard-name}`
+     - Example: `/d/09ec8aa1e996d6ffcd6817bbaff4db1b/kubernetes-api-server` → UID is `09ec8aa1e996d6ffcd6817bbaff4db1b`
+  3. **Use `grafana_get_dashboard_by_uid` with the extracted UID** to fetch the dashboard definition
+  4. **Extract queries from the dashboard panels** and execute them with the appropriate toolset (Prometheus, Loki, etc.)
+
+  ### **Example Workflow:**
+  User: "Look at this graph: http://localhost:3000/d/abc123/my-dashboard?from=now-1h&to=now"
+  ↓
+  1. Recognize this is a Grafana URL (contains /d/)
+  2. Extract UID: abc123
+  3. Call grafana_get_dashboard_by_uid(uid="abc123")
+  4. Analyze dashboard panels and their queries
+  5. Execute relevant queries using the time range from the URL (from=now-1h, to=now)
+
+  **Key Point:** Always prefer the Grafana toolset for any URL pointing to a Grafana instance. This gives you access to the dashboard structure, panel queries, and metadata - not just HTML content.
+
 
 ## **Instruction: Prometheus Dashboard Query Execution**