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

holmes/plugins/toolsets/opensearch/opensearch_query_assist.py

@@ -0,0 +1,78 @@
+import logging
+import os
+from typing import Any, Dict
+
+from holmes.core.tools import (
+    StructuredToolResult,
+    StructuredToolResultStatus,
+    Tool,
+    ToolParameter,
+    Toolset,
+    ToolsetTag,
+    ToolInvokeContext,
+    ToolsetEnvironmentPrerequisite,
+)
+
+
+class PplQueryAssistTool(Tool):
+    def __init__(self, toolset: "OpenSearchQueryAssistToolset"):
+        super().__init__(
+            name="opensearch_ppl_query_assist",
+            description="Generate valid OpenSearch Piped Processing Language (PPL) queries to suggest to users for execution",
+            parameters={
+                "query": ToolParameter(
+                    description="Valid OpenSearch Piped Processing Language (PPL) query to suggest to users for execution",
+                    type="string",
+                    required=True,
+                ),
+            },
+        )
+        self._toolset = toolset
+
+    def _invoke(self, params: dict, context: ToolInvokeContext) -> StructuredToolResult:
+        try:
+            query = params.get("query", "")
+            response_data = {"query": query}
+            return StructuredToolResult(
+                status=StructuredToolResultStatus.SUCCESS,
+                data=response_data,
+                params=params,
+            )
+
+        except Exception as e:
+            logging.exception(f"error using {self.name} tool")
+            return StructuredToolResult(
+                status=StructuredToolResultStatus.ERROR,
+                error=f"Failed to generate PPL query: {str(e)}",
+                params=params,
+            )
+
+    def get_parameterized_one_liner(self, params: Dict) -> str:
+        query = params.get("query", "")
+        return f"OpenSearchQueryToolset: Query ({query})"
+
+
+class OpenSearchQueryAssistToolset(Toolset):
+    """OpenSearch query assist with PPL queries"""
+
+    def __init__(self):
+        super().__init__(
+            name="opensearch/query_assist",
+            description="OpenSearch query assist with PPL queries.",
+            experimental=True,
+            icon_url="https://opensearch.org/assets/brand/PNG/Mark/opensearch_mark_default.png",
+            tools=[PplQueryAssistTool(self)],
+            tags=[ToolsetTag.CORE],
+            prerequisites=[ToolsetEnvironmentPrerequisite(env=["OPENSEARCH_URL"])],
+        )
+
+    def get_example_config(self) -> Dict[str, Any]:
+        return {"opensearch_url": "http://localhost:9200"}
+
+    def _reload_instructions(self):
+        template_file_path = os.path.abspath(
+            os.path.join(
+                os.path.dirname(__file__), "opensearch_query_assist_instructions.jinja2"
+            )
+        )
+        self._load_llm_instructions(jinja_template=f"file://{template_file_path}")

holmes/plugins/toolsets/opensearch/opensearch_query_assist_instructions.jinja2

@@ -0,0 +1,223 @@
+# Query Generation
+You have access to the opensearch_ppl_query_assist tool to help you generate your valid, accurate OpenSearch Piped Processing Language (PPL) queries.
+DO NOT PROVIDE INVALID QUERIES. ALWAYS CHECK YOUR QUERY WITH VALID QUERIES FIRST.
+
+Once a valid query is generated, you MUST provide a concise, but informative breakdown of each part of the query structure
+
+## CRITICAL: Query Intent Detection
+
+ALWAYS check if the user's question is about:
+
+* Log Analysis: Errors, warnings, messages, patterns, tool usage
+* Metrics Analysis: Performance, latency, throughput, resource usage
+* Time-based Analysis: "Last X hours/days", "recent", "today", "since"
+* Aggregation Requests: Count, sum, average, top, frequency
+* Troubleshooting: Issues, problems, failures, debugging
+
+If ANY of the above apply → Generate PPL query IMMEDIATELY and use the OpenSearch Dashboards Page State
+
+### Example GOOD response:
+I've retrieved your current query from the query bar `source=logs-otel-v1* | STAT count() BY severityText` and it
+appears there is a typo in "STAT", it should be "STATS". Below is the fixed query:
+```
+source=logs-otel-v1* | STATS count() BY severityText
+```
+
+
+## CRITICAL: OpenSearch Dashboards Page State
+User may be using this agent from OpenSearch Dashboards (OSD) for which provides the current page state.
+It may be included in the conversation history as a system message.
+
+IMPORTANT: YOU CAN USE THE CURRENT USE QUERY TO HELP ENHANCE/MODIFY/FIX/SUGGEST VALID QUERY USING THE SAME INDEX PATTERN
+REFER TO "Core PPL Commands" FOR SYNTAX
+
+```
+## OpenSearch PPL Query Language
+
+### PPL (Piped Processing Language) Overview
+PPL is OpenSearch's query language for analyzing logs, metrics, and traces. It uses a pipe-based syntax similar to Unix commands, processing data through sequential transformations.
+
+### Core PPL Commands
+
+**Data Source & Search:**
+- `source=<index>` or `search source=<index>` - Specify data source
+- `source=<cluster>:<index>` - Cross-cluster search
+- `| where <condition>` - Filter results
+- `| fields <field-list>` - Project specific fields
+- `| fields - <field-list>` - Exclude specific fields
+
+**Data Transformation:**
+- `| stats <aggregation> by <field>` - Aggregate data (count(), sum(), avg(), min(), max())
+- `| eval <field>=<expression>` - Create calculated fields
+- `| sort [+|-] <field>` - Sort results (+ ascending, - descending)
+- `| head <n>` - Return first n results
+- `| tail <n>` - Return last n results
+- `| dedup <field-list>` - Remove duplicates
+
+**Advanced Analysis:**
+- `| top [N] <field>` - Find most common values
+- `| rare [N] <field>` - Find least common values
+- `| parse <field> <regex>` - Extract fields using regex patterns
+- `| grok <field> <pattern>` - Parse using grok patterns
+- `| patterns <field> [SIMPLE_PATTERN|BRAIN]` - Extract log patterns
+
+**Time Series:**
+- `| trendline SMA(<period>, <field>)` - Calculate moving averages
+- `| fillnull with <value> in <fields>` - Replace null values
+
+**Joins & Lookups:**
+- `| join <table>` - Join with another dataset
+- `| lookup <table> <field>` - Enrich with lookup data (requires Calcite)
+
+**Pattern Extraction:**
+- `| patterns message BRAIN` - Semantic log pattern extraction
+- `| patterns new_field='extracted' pattern='[0-9]' message` - Custom regex patterns
+
+### PPL Query Examples for Observability
+
+**Error Analysis:**
+```ppl
+source=ai-agent-logs-*
+| where level="ERROR"
+| stats count() by message
+| sort - count
+```
+
+**Service Latency Analysis:**
+```ppl
+source=traces
+| where service="checkout"
+| stats avg(duration) as avg_latency, max(duration) as max_latency by endpoint
+| where avg_latency > 100
+```
+
+**Log Pattern Detection:**
+```ppl
+source=ai-agent-audit-logs-*
+| patterns message BRAIN
+| stats count() by patterns_field
+| top 10 patterns_field
+```
+
+**Time-based Aggregation:**
+```ppl
+source=metrics
+| eval hour=date_format(timestamp, 'HH')
+| stats avg(cpu_usage) by hour, host
+| sort hour
+```
+
+**Multi-field Correlation:**
+```ppl
+source=ai-agent-logs-*
+| parse message '.*thread_id=(?<tid>[^,]+).*run_id=(?<rid>[^,]+)'
+| stats count() by tid, rid, level
+| where count > 100
+```
+
+**Advanced PPL Query Patterns:**
+
+**Top N Analysis with Filtering:**
+```ppl
+source=ai-agent-logs-*
+| where timestamp >= now() - 1h
+| top 20 message by level
+| where level in ["ERROR", "WARN"]
+```
+
+**Deduplication and Unique Values:**
+```ppl
+source=ai-agent-audit-logs-*
+| dedup thread_id
+| fields thread_id, run_id, timestamp
+| sort - timestamp
+```
+
+**Fillnull for Missing Data Handling:**
+```ppl
+source=ai-agent-metrics-*
+| fillnull with 0 in cpu_usage, memory_usage
+| stats avg(cpu_usage) as avg_cpu, avg(memory_usage) as avg_mem by host
+```
+
+**Rare Events Detection:**
+```ppl
+source=ai-agent-logs-*
+| rare 10 error_code
+| where count < 5
+```
+
+**Field Extraction with Grok:**
+```ppl
+source=ai-agent-logs-*
+| grok message '%{TIMESTAMP_ISO8601:timestamp} %{LOGLEVEL:level} %{GREEDYDATA:msg}'
+| stats count() by level
+```
+
+**Time Span Aggregations:**
+```ppl
+source=ai-agent-metrics-*
+| stats count() by span(timestamp, 5m) as time_bucket, status
+| where status != 200
+```
+
+**Eval with Conditional Logic:**
+```ppl
+source=ai-agent-logs-*
+| eval severity = case(
+    level = "ERROR", 1,
+    level = "WARN", 2,
+    level = "INFO", 3,
+    else = 4
+  )
+| stats count() by severity
+```
+
+**Join Operations (with Calcite enabled):**
+```ppl
+source=ai-agent-logs-*
+| join left=l right=r on l.thread_id = r.thread_id
+  [ source=ai-agent-audit-logs-* ]
+| fields l.timestamp, l.message, r.tool_name
+```
+
+**Subquery for Complex Filtering:**
+```ppl
+source=ai-agent-logs-*
+| where thread_id in [
+    source=ai-agent-audit-logs-*
+    | where tool_name = "opensearch__search"
+    | fields thread_id
+  ]
+```
+
+**Trendline for Moving Averages:**
+```ppl
+source=ai-agent-metrics-*
+| trendline SMA(5, cpu_usage) as cpu_trend
+| fields timestamp, cpu_usage, cpu_trend
+```
+
+### PPL Best Practices
+
+1. **Index Patterns**: Use wildcards for daily indices: `source=ai-agent-logs-*`
+2. **Field Extraction**: Use `parse` for structured logs, `patterns` for unstructured
+3. **Performance**: Apply `where` filters early in the pipeline
+4. **Aggregations**: Use `stats` before `sort` for better performance
+5. **Null Handling**: Use `fillnull` to handle missing data in calculations
+
+### OpenSearch Index Patterns (Current Environment)
+- `ai-agent-logs-YYYY.MM.DD` - Application logs
+- `ai-agent-audit-logs-YYYY.MM.DD` - Audit logs
+- `ai-agent-metrics-YYYY.MM.DD` - Prometheus metrics
+
+## Query Response Formatting
+You MUST respond with queries in the following format. `ppl` contains the valid ppl query
+```typescript
+query: {
+ ppl: string,
+}
+```
+
+## More PPL Queries
+{% include "opensearch_ppl_query_docs.jinja2" %}

holmes/plugins/toolsets/opensearch/opensearch_traces.py

@@ -7,6 +7,7 @@ from cachetools import TTLCache  # type: ignore
 from holmes.core.tools import (
     CallablePrerequisite,
     Tool,
+    ToolInvokeContext,
     ToolParameter,
     ToolsetTag,
 )
@@ -18,7 +19,7 @@ from holmes.plugins.toolsets.opensearch.opensearch_utils import (
     add_auth_header,
     get_search_url,
 )
-from holmes.core.tools import StructuredToolResult, ToolResultStatus
+from holmes.core.tools import StructuredToolResult, StructuredToolResultStatus
 from holmes.plugins.toolsets.utils import get_param_or_raise, toolset_name_for_one_liner
 
 TRACES_FIELDS_CACHE_KEY = "cached_traces_fields"
@@ -34,9 +35,7 @@ class GetTracesFields(Tool):
         self._toolset = toolset
         self._cache = None
 
-    def _invoke(
-        self, params: dict, user_approved: bool = False
-    ) -> StructuredToolResult:
+    def _invoke(self, params: dict, context: ToolInvokeContext) -> StructuredToolResult:
         try:
             if not self._cache and self._toolset.opensearch_config.fields_ttl_seconds:
                 self._cache = TTLCache(
@@ -48,7 +47,7 @@ class GetTracesFields(Tool):
                 if cached_response:
                     logging.debug("traces fields returned from cache")
                     return StructuredToolResult(
-                        status=ToolResultStatus.SUCCESS,
+                        status=StructuredToolResultStatus.SUCCESS,
                         data=cached_response,
                         params=params,
                     )
@@ -81,7 +80,7 @@ class GetTracesFields(Tool):
             if self._cache:
                 self._cache[TRACES_FIELDS_CACHE_KEY] = response
             return StructuredToolResult(
-                status=ToolResultStatus.SUCCESS,
+                status=StructuredToolResultStatus.SUCCESS,
                 data=response,
                 params=params,
             )
@@ -90,21 +89,21 @@ class GetTracesFields(Tool):
                 "Timeout while fetching opensearch traces fields", exc_info=True
             )
             return StructuredToolResult(
-                status=ToolResultStatus.ERROR,
+                status=StructuredToolResultStatus.ERROR,
                 error="Request timed out while fetching opensearch traces fields",
                 params=params,
             )
         except RequestException as e:
             logging.warning("Failed to fetch opensearch traces fields", exc_info=True)
             return StructuredToolResult(
-                status=ToolResultStatus.ERROR,
+                status=StructuredToolResultStatus.ERROR,
                 error=f"Network error while opensearch traces fields: {str(e)}",
                 params=params,
             )
         except Exception as e:
             logging.warning("Failed to process opensearch traces fields", exc_info=True)
             return StructuredToolResult(
-                status=ToolResultStatus.ERROR,
+                status=StructuredToolResultStatus.ERROR,
                 error=f"Unexpected error: {str(e)}",
                 params=params,
             )
@@ -129,9 +128,7 @@ class TracesSearchQuery(Tool):
         self._toolset = toolset
         self._cache = None
 
-    def _invoke(
-        self, params: dict, user_approved: bool = False
-    ) -> StructuredToolResult:
+    def _invoke(self, params: dict, context: ToolInvokeContext) -> StructuredToolResult:
         err_msg = ""
         try:
             body = json.loads(get_param_or_raise(params, "query"))
@@ -157,7 +154,7 @@ class TracesSearchQuery(Tool):
 
             logs_response.raise_for_status()
             return StructuredToolResult(
-                status=ToolResultStatus.SUCCESS,
+                status=StructuredToolResultStatus.SUCCESS,
                 data=json.dumps(logs_response.json()),
                 params=params,
             )
@@ -166,14 +163,14 @@ class TracesSearchQuery(Tool):
                 "Timeout while fetching opensearch traces search", exc_info=True
             )
             return StructuredToolResult(
-                status=ToolResultStatus.ERROR,
+                status=StructuredToolResultStatus.ERROR,
                 error=f"Request timed out while fetching opensearch traces search {err_msg}",
                 params=params,
             )
         except RequestException as e:
             logging.warning("Failed to fetch opensearch traces search", exc_info=True)
             return StructuredToolResult(
-                status=ToolResultStatus.ERROR,
+                status=StructuredToolResultStatus.ERROR,
                 error=f"Network error while opensearch traces search {err_msg} : {str(e)}",
                 params=params,
             )
@@ -182,7 +179,7 @@ class TracesSearchQuery(Tool):
                 "Failed to process opensearch traces search ", exc_info=True
             )
             return StructuredToolResult(
-                status=ToolResultStatus.ERROR,
+                status=StructuredToolResultStatus.ERROR,
                 error=f"Unexpected error {err_msg}: {str(e)}",
                 params=params,
             )