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

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

@@ -0,0 +1,117 @@
+from typing import Dict
+import os
+import json
+from holmes.core.tools import (
+    Tool,
+    ToolInvokeContext,
+    ToolParameter,
+)
+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.logging_utils.logging_api import (
+    DEFAULT_TIME_SPAN_SECONDS,
+    DEFAULT_LOG_LIMIT,
+)
+from holmes.plugins.toolsets.grafana.loki_api import (
+    execute_loki_query,
+)
+
+from holmes.plugins.toolsets.utils import toolset_name_for_one_liner
+from holmes.core.tools import StructuredToolResult, StructuredToolResultStatus
+
+
+class GrafanaLokiToolset(BaseGrafanaToolset):
+    def __init__(self):
+        super().__init__(
+            name="grafana/loki",
+            description="Runs loki log queries using Grafana Loki or Loki directly.",
+            icon_url="https://grafana.com/media/docs/loki/logo-grafana-loki.png",
+            docs_url="https://holmesgpt.dev/data-sources/builtin-toolsets/grafanaloki/",
+            tools=[],
+        )
+
+        self.tools = [LokiQuery(toolset=self)]
+        instructions_filepath = os.path.abspath(
+            os.path.join(os.path.dirname(__file__), "instructions.jinja2")
+        )
+        self._load_llm_instructions(jinja_template=f"file://{instructions_filepath}")
+
+
+class LokiQuery(Tool):
+    toolset: GrafanaLokiToolset
+    name: str = "grafana_loki_query"
+    description: str = "Run a query against Grafana Loki using LogQL query language."
+    parameters: Dict[str, ToolParameter] = {
+        "query": ToolParameter(
+            description="LogQL query string.",
+            type="string",
+            required=True,
+        ),
+        "start": ToolParameter(
+            description=standard_start_datetime_tool_param_description(
+                DEFAULT_TIME_SPAN_SECONDS
+            ),
+            type="string",
+            required=False,
+        ),
+        "end": ToolParameter(
+            description=STANDARD_END_DATETIME_TOOL_PARAM_DESCRIPTION,
+            type="string",
+            required=False,
+        ),
+        "limit": ToolParameter(
+            description="Maximum number of entries to return (default: 100)",
+            type="integer",
+            required=False,
+        ),
+    }
+
+    def get_parameterized_one_liner(self, params) -> str:
+        return f"{toolset_name_for_one_liner(self.toolset.name)}: loki query {params}"
+
+    def _invoke(self, params: dict, context: ToolInvokeContext) -> StructuredToolResult:
+        (start, end) = process_timestamps_to_rfc3339(
+            start_timestamp=params.get("start"),
+            end_timestamp=params.get("end"),
+            default_time_span_seconds=DEFAULT_TIME_SPAN_SECONDS,
+        )
+
+        config = self.toolset._grafana_config
+        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.
+                start=start,
+                end=end,
+                limit=params.get("limit") or DEFAULT_LOG_LIMIT,
+            )
+            if data:
+                return StructuredToolResult(
+                    status=StructuredToolResultStatus.SUCCESS,
+                    data=json.dumps(data),
+                    params=params,
+                )
+            else:
+                return StructuredToolResult(
+                    status=StructuredToolResultStatus.NO_DATA,
+                    params=params,
+                )
+        except Exception as e:
+            return StructuredToolResult(
+                status=StructuredToolResultStatus.ERROR,
+                params=params,
+                error=str(e),
+                url=f"{get_base_url(config)}/loki/api/v1/query_range",
+            )

holmes/plugins/toolsets/grafana/toolset_grafana.py

@@ -1,127 +1,247 @@
-from typing import Dict, List
-from urllib.parse import urlencode, urljoin
+import os
+from typing import ClassVar, Dict, Optional, Type, cast
+from urllib.parse import urljoin
+from abc import ABC
 from holmes.core.tools import (
     StructuredToolResult,
     Tool,
+    ToolInvokeContext,
     ToolParameter,
-    ToolResultStatus,
+    StructuredToolResultStatus,
 )
 from holmes.plugins.toolsets.grafana.base_grafana_toolset import BaseGrafanaToolset
 import requests  # type: ignore
-import logging
 
+from holmes.plugins.toolsets.grafana.common import (
+    get_base_url,
+    GrafanaConfig,
+    build_headers,
+)
 from holmes.plugins.toolsets.utils import toolset_name_for_one_liner
 
 
-class ListAndBuildGrafanaDashboardURLs(Tool):
-    def __init__(self, toolset: BaseGrafanaToolset):
+class GrafanaDashboardConfig(GrafanaConfig):
+    """Configuration specific to Grafana Dashboard toolset with api/health as default healthcheck"""
+
+    healthcheck: Optional[str] = "api/health"
+
+
+class GrafanaToolset(BaseGrafanaToolset):
+    config_class: ClassVar[Type[GrafanaDashboardConfig]] = GrafanaDashboardConfig
+
+    def __init__(self):
+        super().__init__(
+            name="grafana/dashboards",
+            description="Provides tools for interacting with Grafana dashboards",
+            icon_url="https://w7.pngwing.com/pngs/434/923/png-transparent-grafana-hd-logo-thumbnail.png",
+            docs_url="https://holmesgpt.dev/data-sources/builtin-toolsets/grafanadashboards/",
+            tools=[
+                SearchDashboards(self),
+                GetDashboardByUID(self),
+                GetHomeDashboard(self),
+                GetDashboardTags(self),
+            ],
+        )
+
+        self._load_llm_instructions_from_file(
+            os.path.dirname(__file__), "toolset_grafana_dashboard.jinja2"
+        )
+
+    @property
+    def grafana_config(self) -> GrafanaDashboardConfig:
+        return cast(GrafanaDashboardConfig, self._grafana_config)
+
+
+class BaseGrafanaTool(Tool, ABC):
+    """Base class for Grafana tools with common HTTP request functionality."""
+
+    def __init__(self, toolset: GrafanaToolset, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._toolset = toolset
+
+    def _make_grafana_request(
+        self,
+        endpoint: str,
+        params: dict,
+        query_params: Optional[Dict] = None,
+        timeout: int = 30,
+    ) -> StructuredToolResult:
+        """Make a GET request to Grafana API and return structured result.
+
+        Args:
+            endpoint: API endpoint path (e.g., "/api/search")
+            params: Original parameters passed to the tool
+            query_params: Optional query parameters for the request
+
+        Returns:
+            StructuredToolResult with the API response data
+        """
+        url = urljoin(get_base_url(self._toolset.grafana_config), 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
+        )
+        response.raise_for_status()
+        data = response.json()
+
+        return StructuredToolResult(
+            status=StructuredToolResultStatus.SUCCESS,
+            data=data,
+            url=url,
+            params=params,
+        )
+
+
+class SearchDashboards(BaseGrafanaTool):
+    def __init__(self, toolset: GrafanaToolset):
         super().__init__(
-            name="list_and_build_grafana_dashboard_urls",
-            description="Lists all available Grafana dashboard urls",
+            toolset=toolset,
+            name="grafana_search_dashboards",
+            description="Search for Grafana dashboards and folders using the /api/search endpoint",
             parameters={
-                "cluster_name": ToolParameter(
-                    description="The cluster name. Defaults to None.",
+                "query": ToolParameter(
+                    description="Search text to filter dashboards",
                     type="string",
                     required=False,
                 ),
-                "namespace": ToolParameter(
-                    description="The namespace for filtering dashboards.",
+                "tag": ToolParameter(
+                    description="Search dashboards by tag",
                     type="string",
                     required=False,
                 ),
-                "node_name": ToolParameter(
-                    description="The node name to filter for node-related dashboards.",
+                "type": ToolParameter(
+                    description="Filter by type: 'dash-folder' or 'dash-db'",
                     type="string",
                     required=False,
                 ),
-                "pod_name": ToolParameter(
-                    description="The pod name to filter dashboards.",
+                "dashboardIds": ToolParameter(
+                    description="List of dashboard IDs to filter (comma-separated)",
                     type="string",
                     required=False,
                 ),
+                "dashboardUIDs": ToolParameter(
+                    description="List of dashboard UIDs to search for (comma-separated)",
+                    type="string",
+                    required=False,
+                ),
+                "folderUIDs": ToolParameter(
+                    description="List of folder UIDs to search within (comma-separated)",
+                    type="string",
+                    required=False,
+                ),
+                "starred": ToolParameter(
+                    description="Return only starred dashboards",
+                    type="boolean",
+                    required=False,
+                ),
+                "limit": ToolParameter(
+                    description="Maximum results (default 1000, max 5000)",
+                    type="integer",
+                    required=False,
+                ),
+                "page": ToolParameter(
+                    description="Page number for pagination",
+                    type="integer",
+                    required=False,
+                ),
             },
         )
-        self._toolset = toolset
 
-    def _invoke(
-        self, params: dict, user_approved: bool = False
-    ) -> StructuredToolResult:
-        url = urljoin(
-            self._toolset._grafana_config.url, "/api/search?query=&type=dash-db"
+    def _invoke(self, params: dict, context: ToolInvokeContext) -> StructuredToolResult:
+        query_params = {}
+        if params.get("query"):
+            query_params["query"] = params["query"]
+        if params.get("tag"):
+            query_params["tag"] = params["tag"]
+        if params.get("type"):
+            query_params["type"] = params["type"]
+        if params.get("dashboardIds"):
+            # Check if dashboardIds also needs to be passed as multiple params
+            dashboard_ids = params["dashboardIds"].split(",")
+            query_params["dashboardIds"] = [
+                dashboard_id.strip()
+                for dashboard_id in dashboard_ids
+                if dashboard_id.strip()
+            ]
+        if params.get("dashboardUIDs"):
+            # Handle dashboardUIDs as a list - split comma-separated values
+            dashboard_uids = params["dashboardUIDs"].split(",")
+            query_params["dashboardUIDs"] = [
+                uid.strip() for uid in dashboard_uids if uid.strip()
+            ]
+        if params.get("folderUIDs"):
+            # Check if folderUIDs also needs to be passed as multiple params
+            folder_uids = params["folderUIDs"].split(",")
+            query_params["folderUIDs"] = [
+                uid.strip() for uid in folder_uids if uid.strip()
+            ]
+        if params.get("starred") is not None:
+            query_params["starred"] = str(params["starred"]).lower()
+        if params.get("limit"):
+            query_params["limit"] = params["limit"]
+        if params.get("page"):
+            query_params["page"] = params["page"]
+
+        return self._make_grafana_request("/api/search", params, query_params)
+
+    def get_parameterized_one_liner(self, params: Dict) -> str:
+        return f"{toolset_name_for_one_liner(self._toolset.name)}: Search Dashboards"
+
+
+class GetDashboardByUID(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,
+                ),
+            },
         )
-        headers = {"Authorization": f"Bearer {self._toolset._grafana_config.api_key}"}
-
-        try:
-            response = requests.get(url, headers=headers)
-            response.raise_for_status()
-            dashboards = response.json()
-            formatted_dashboards: List[str] = []
-            base_url = (
-                self._toolset._grafana_config.external_url
-                or self._toolset._grafana_config.url
-            )
-            for dash in dashboards:
-                dashboard_url = urljoin(
-                    base_url,
-                    f"/d/{dash['uid']}/{dash['uri'].split('/')[-1]}",
-                )
-
-                params_dict = {
-                    "var-cluster": params.get("cluster_name", ""),
-                    "var-namespace": params.get("namespace", ""),
-                    "var-pod": params.get("pod_name", ""),
-                    "var-node": params.get("node_name", ""),
-                    "var-datasource": self._toolset._grafana_config.grafana_datasource_uid,
-                    "refresh": "5s",
-                }
-
-                # If filtering for nodes, ensure only node-related dashboards are included
-                if params.get("node_name") and "node" not in dash["title"].lower():
-                    continue
-
-                # we add all params since if the dashboard isnt configured for a param it will ignore it if it is added
-                query_string = urlencode({k: v for k, v in params_dict.items() if v})
-                dashboard_url = (
-                    f"{dashboard_url}?{query_string}" if query_string else dashboard_url
-                )
-
-                formatted_dashboards.append(
-                    f"Title: {dash['title']}\nURL: {dashboard_url}\n"
-                )
-
-            return StructuredToolResult(
-                status=ToolResultStatus.SUCCESS
-                if formatted_dashboards
-                else ToolResultStatus.NO_DATA,
-                data="\n".join(formatted_dashboards)
-                if formatted_dashboards
-                else "No dashboards found.",
-                url=url,
-                params=params,
-            )
-        except requests.RequestException as e:
-            logging.error(f"Error fetching dashboards: {str(e)}")
-            return StructuredToolResult(
-                status=ToolResultStatus.ERROR,
-                error=f"Error fetching dashboards: {str(e)}",
-                url=url,
-                params=params,
-            )
+
+    def _invoke(self, params: dict, context: ToolInvokeContext) -> StructuredToolResult:
+        uid = params["uid"]
+        return self._make_grafana_request(f"/api/dashboards/uid/{uid}", params)
 
     def get_parameterized_one_liner(self, params: Dict) -> str:
-        return (
-            f"{toolset_name_for_one_liner(self._toolset.name)}: List Grafana Dashboards"
+        return f"{toolset_name_for_one_liner(self._toolset.name)}: Get Dashboard {params.get('uid', '')}"
+
+
+class GetHomeDashboard(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={},
         )
 
+    def _invoke(self, params: dict, context: ToolInvokeContext) -> StructuredToolResult:
+        return self._make_grafana_request("/api/dashboards/home", params)
 
-class GrafanaToolset(BaseGrafanaToolset):
-    def __init__(self):
+    def get_parameterized_one_liner(self, params: Dict) -> str:
+        return f"{toolset_name_for_one_liner(self._toolset.name)}: Get Home Dashboard"
+
+
+class GetDashboardTags(BaseGrafanaTool):
+    def __init__(self, toolset: GrafanaToolset):
         super().__init__(
-            name="grafana/grafana",
-            description="Provides tools for interacting with Grafana dashboards",
-            icon_url="https://w7.pngwing.com/pngs/434/923/png-transparent-grafana-hd-logo-thumbnail.png",
-            docs_url="",
-            tools=[
-                ListAndBuildGrafanaDashboardURLs(self),
-            ],
+            toolset=toolset,
+            name="grafana_get_dashboard_tags",
+            description="Get all tags used across dashboards using the /api/dashboards/tags endpoint",
+            parameters={},
         )
+
+    def _invoke(self, params: dict, context: ToolInvokeContext) -> StructuredToolResult:
+        return self._make_grafana_request("/api/dashboards/tags", params)
+
+    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

@@ -0,0 +1,27 @@
+---
+
+## **Instruction: Prometheus Dashboard Query Execution**
+
+**When running Prometheus queries from Grafana dashboards:**
+
+### **Key Rules:**
+1. **Always run as range queries** (not instant queries) to match dashboard behavior
+2. **Use dashboard's time range** from JSON: `"time": {"from": "now-1h", "to": "now"}`
+3. **Substitute variables:**
+   - `$__rate_interval` → `1m` (1-hour range) or `5m` (3+ hour range)
+   - `$cluster` → omit if empty
+4. **Copy query exactly** including `ceil()`, `sort_desc()`, etc.
+
+### **Example:**
+```
+Dashboard: "now-1h" + query with [$__rate_interval]
+↓
+Execute: start="-3600" + query with [1m]
+```
+
+### **Ignore:**
+- `"refresh": "10s"` (UI setting, not query-related)
+
+**This ensures you see the same time series data and historical spikes that users see on their dashboards.**
+
+---