holmesgpt 0.11.5__py3-none-any.whl

holmes/plugins/toolsets/grafana/toolset_grafana_tempo.py

@@ -0,0 +1,299 @@
+import os
+from typing import Any, Dict, List, cast
+
+import requests  # type: ignore
+import yaml  # type: ignore
+from pydantic import BaseModel
+
+from holmes.common.env_vars import load_bool
+from holmes.core.tools import (
+    StructuredToolResult,
+    Tool,
+    ToolParameter,
+    ToolResultStatus,
+)
+from holmes.plugins.toolsets.grafana.base_grafana_toolset import BaseGrafanaToolset
+from holmes.plugins.toolsets.grafana.common import (
+    GrafanaConfig,
+    build_headers,
+    get_base_url,
+)
+from holmes.plugins.toolsets.grafana.tempo_api import (
+    query_tempo_trace_by_id,
+    query_tempo_traces,
+)
+from holmes.plugins.toolsets.grafana.trace_parser import format_traces_list
+from holmes.plugins.toolsets.utils import get_param_or_raise, process_timestamps_to_int
+
+TEMPO_LABELS_ADD_PREFIX = load_bool("TEMPO_LABELS_ADD_PREFIX", True)
+
+ONE_HOUR_IN_SECONDS = 3600
+
+
+class GrafanaTempoLabelsConfig(BaseModel):
+    pod: str = "k8s.pod.name"
+    namespace: str = "k8s.namespace.name"
+    deployment: str = "k8s.deployment.name"
+    node: str = "k8s.node.name"
+    service: str = "service.name"
+
+
+class GrafanaTempoConfig(GrafanaConfig):
+    labels: GrafanaTempoLabelsConfig = GrafanaTempoLabelsConfig()
+
+
+class BaseGrafanaTempoToolset(BaseGrafanaToolset):
+    config_class = GrafanaTempoConfig
+
+    def get_example_config(self):
+        example_config = GrafanaTempoConfig(
+            api_key="YOUR API KEY",
+            url="YOUR GRAFANA URL",
+            grafana_datasource_uid="<UID of the tempo datasource to use>",
+        )
+        return example_config.model_dump()
+
+    @property
+    def grafana_config(self) -> GrafanaTempoConfig:
+        return cast(GrafanaTempoConfig, self._grafana_config)
+
+
+def validate_params(params: Dict[str, Any], expected_params: List[str]):
+    for param in expected_params:
+        if param in params and params[param] not in (None, "", [], {}):
+            return None
+
+    return f"At least one of the following argument is expected but none were set: {expected_params}"
+
+
+class GetTempoTraces(Tool):
+    def __init__(self, toolset: BaseGrafanaTempoToolset):
+        super().__init__(
+            name="fetch_tempo_traces",
+            description="""Lists Tempo traces. At least one of `service_name`, `pod_name` or `deployment_name` argument is required.""",
+            parameters={
+                "min_duration": ToolParameter(
+                    description="The minimum duration of traces to fetch, e.g., '5s' for 5 seconds.",
+                    type="string",
+                    required=True,
+                ),
+                "service_name": ToolParameter(
+                    description="Filter traces by service name",
+                    type="string",
+                    required=False,
+                ),
+                "pod_name": ToolParameter(
+                    description="Filter traces by pod name",
+                    type="string",
+                    required=False,
+                ),
+                "namespace_name": ToolParameter(
+                    description="Filter traces by namespace",
+                    type="string",
+                    required=False,
+                ),
+                "deployment_name": ToolParameter(
+                    description="Filter traces by deployment name",
+                    type="string",
+                    required=False,
+                ),
+                "node_name": ToolParameter(
+                    description="Filter traces by node",
+                    type="string",
+                    required=False,
+                ),
+                "start_datetime": ToolParameter(
+                    description="The beginning time boundary for the trace search period. String in RFC3339 format. If a negative integer, the number of seconds relative to the end_timestamp. Defaults to negative one hour (-3600)",
+                    type="string",
+                    required=False,
+                ),
+                "end_datetime": ToolParameter(
+                    description="The ending time boundary for the trace search period. String in RFC3339 format. Defaults to NOW().",
+                    type="string",
+                    required=False,
+                ),
+                "limit": ToolParameter(
+                    description="Maximum number of traces to return. Defaults to 50",
+                    type="string",
+                    required=False,
+                ),
+                "sort": ToolParameter(
+                    description="One of 'descending', 'ascending' or 'none' for no sorting. Defaults to descending",
+                    type="string",
+                    required=False,
+                ),
+            },
+        )
+        self._toolset = toolset
+
+    def _invoke(self, params: Dict) -> StructuredToolResult:
+        api_key = self._toolset.grafana_config.api_key
+        headers = self._toolset.grafana_config.headers
+        labels = self._toolset.grafana_config.labels
+
+        invalid_params_error = validate_params(
+            params, ["service_name", "pod_name", "deployment_name"]
+        )
+        if invalid_params_error:
+            return StructuredToolResult(
+                status=ToolResultStatus.ERROR,
+                error=invalid_params_error,
+                params=params,
+            )
+
+        start, end = process_timestamps_to_int(
+            params.get("start_datetime"),
+            params.get("end_datetime"),
+            default_time_span_seconds=3600,
+        )
+
+        prefix = ""
+        if TEMPO_LABELS_ADD_PREFIX:
+            prefix = "resource."
+
+        filters = []
+        if params.get("service_name"):
+            filters.append(f'{prefix}{labels.service}="{params.get("service_name")}"')
+        if params.get("pod_name"):
+            filters.append(f'{prefix}{labels.pod}="{params.get("pod_name")}"')
+        if params.get("namespace_name"):
+            filters.append(
+                f'{prefix}{labels.namespace}="{params.get("namespace_name")}"'
+            )
+        if params.get("deployment_name"):
+            filters.append(
+                f'{prefix}{labels.deployment}="{params.get("deployment_name")}"'
+            )
+        if params.get("node_name"):
+            filters.append(f'{prefix}{labels.node}="{params.get("node_name")}"')
+
+        filters.append(f'duration>{get_param_or_raise(params, "min_duration")}')
+
+        query = " && ".join(filters)
+        query = f"{{{query}}}"
+
+        base_url = get_base_url(self._toolset.grafana_config)
+        traces = query_tempo_traces(
+            base_url=base_url,
+            api_key=api_key,
+            headers=headers,
+            query=query,
+            start=start,
+            end=end,
+            limit=params.get("limit", 50),
+        )
+        return StructuredToolResult(
+            status=ToolResultStatus.SUCCESS,
+            data=format_traces_list(traces),
+            params=params,
+            invocation=query,
+        )
+
+    def get_parameterized_one_liner(self, params: Dict) -> str:
+        return f"Fetched Tempo traces with min_duration={params.get('min_duration')} ({str(params)})"
+
+
+class GetTempoTags(Tool):
+    def __init__(self, toolset: BaseGrafanaTempoToolset):
+        super().__init__(
+            name="fetch_tempo_tags",
+            description="List the tags available in Tempo",
+            parameters={
+                "start_datetime": ToolParameter(
+                    description="The beginning time boundary for the search period. String in RFC3339 format. If a negative integer, the number of seconds relative to the end_timestamp. Defaults to negative 8 hours (-3600)",
+                    type="string",
+                    required=False,
+                ),
+                "end_datetime": ToolParameter(
+                    description="The ending time boundary for the search period. String in RFC3339 format. Defaults to NOW().",
+                    type="string",
+                    required=False,
+                ),
+            },
+        )
+        self._toolset = toolset
+
+    def _invoke(self, params: Dict) -> StructuredToolResult:
+        api_key = self._toolset.grafana_config.api_key
+        headers = self._toolset.grafana_config.headers
+        start, end = process_timestamps_to_int(
+            start=params.get("start_datetime"),
+            end=params.get("end_datetime"),
+            default_time_span_seconds=8 * ONE_HOUR_IN_SECONDS,
+        )
+
+        base_url = get_base_url(self._toolset.grafana_config)
+        url = f"{base_url}/api/v2/search/tags?start={start}&end={end}"
+
+        try:
+            response = requests.get(
+                url,
+                headers=build_headers(api_key=api_key, additional_headers=headers),
+                timeout=60,
+            )
+            response.raise_for_status()  # Raise an error for non-2xx responses
+            data = response.json()
+            return StructuredToolResult(
+                status=ToolResultStatus.SUCCESS,
+                data=yaml.dump(data.get("scopes")),
+                params=params,
+            )
+        except requests.exceptions.RequestException as e:
+            raise Exception(
+                f"Failed to retrieve trace by ID after retries: {e} \n for URL: {url}"
+            )
+
+    def get_parameterized_one_liner(self, params: Dict) -> str:
+        return f"Fetched Tempo tags ({str(params)})"
+
+
+class GetTempoTraceById(Tool):
+    def __init__(self, toolset: BaseGrafanaTempoToolset):
+        super().__init__(
+            name="fetch_tempo_trace_by_id",
+            description="""Retrieves detailed information about a Tempo trace using its trace ID. Use this to investigate a trace.""",
+            parameters={
+                "trace_id": ToolParameter(
+                    description="The unique trace ID to fetch.",
+                    type="string",
+                    required=True,
+                ),
+            },
+        )
+        self._toolset = toolset
+
+    def _invoke(self, params: Dict) -> StructuredToolResult:
+        labels_mapping = self._toolset.grafana_config.labels
+        labels = list(labels_mapping.model_dump().values())
+
+        base_url = get_base_url(self._toolset.grafana_config)
+        trace_data = query_tempo_trace_by_id(
+            base_url=base_url,
+            api_key=self._toolset.grafana_config.api_key,
+            headers=self._toolset.grafana_config.headers,
+            trace_id=get_param_or_raise(params, "trace_id"),
+            key_labels=labels,
+        )
+        return StructuredToolResult(
+            status=ToolResultStatus.SUCCESS,
+            data=trace_data,
+            params=params,
+        )
+
+    def get_parameterized_one_liner(self, params: Dict) -> str:
+        return f"Fetched Tempo trace with trace_id={params.get('trace_id')} ({str(params)})"
+
+
+class GrafanaTempoToolset(BaseGrafanaTempoToolset):
+    def __init__(self):
+        super().__init__(
+            name="grafana/tempo",
+            description="Fetches kubernetes traces from Tempo",
+            icon_url="https://grafana.com/static/assets/img/blog/tempo.png",
+            docs_url="https://docs.robusta.dev/master/configuration/holmesgpt/toolsets/grafanatempo.html",
+            tools=[GetTempoTraces(self), GetTempoTraceById(self), GetTempoTags(self)],
+        )
+        template_file_path = os.path.abspath(
+            os.path.join(os.path.dirname(__file__), "toolset_grafana_tempo.jinja2")
+        )
+        self._load_llm_instructions(jinja_template=f"file://{template_file_path}")

holmes/plugins/toolsets/grafana/trace_parser.py

@@ -0,0 +1,195 @@
+from typing import Dict, List, Optional, Any
+from dataclasses import dataclass, field
+import base64
+from holmes.plugins.toolsets.utils import unix_nano_to_rfc3339
+
+
+@dataclass
+class Span:
+    span_id: str
+    parent_span_id: Optional[str]
+    name: str
+    service_name: str
+    start_time: int
+    end_time: int
+    attributes: Dict[str, Any] = field(default_factory=dict)
+    events: List[Dict[str, Any]] = field(default_factory=list)
+    children: List["Span"] = field(default_factory=list)
+    resource_attributes: Dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def duration_ms(self) -> float:
+        """Calculate duration in milliseconds"""
+        return (
+            self.end_time - self.start_time
+        ) / 1_000_000  # Convert nanoseconds to milliseconds
+
+
+def decode_id(encoded_id: str) -> str:
+    """Decode base64 IDs to a hex string for easier reading"""
+    return base64.b64decode(encoded_id).hex()
+
+
+def build_span_hierarchy(trace_data: Dict) -> List[Span]:
+    # Step 1: Extract all spans and create span objects
+    all_spans = {}
+
+    for batch in trace_data["batches"]:
+        # Extract service name and other resource attributes
+        service_name = "unknown"
+        resource_attributes = {}
+
+        for attr in batch["resource"]["attributes"]:
+            key = attr["key"]
+            value = list(attr["value"].values())[0]
+            resource_attributes[key] = value
+
+            if key == "service.name":
+                service_name = value
+
+        for scope_spans in batch["scopeSpans"]:
+            for span_data in scope_spans["spans"]:
+                span_id = decode_id(span_data["spanId"])
+
+                # Get parent span ID if it exists
+                parent_span_id = None
+                if "parentSpanId" in span_data:
+                    parent_span_id = decode_id(span_data["parentSpanId"])
+
+                # Create a Span object
+                span = Span(
+                    span_id=span_id,
+                    parent_span_id=parent_span_id,
+                    name=span_data["name"],
+                    service_name=service_name,
+                    start_time=int(span_data["startTimeUnixNano"]),
+                    end_time=int(span_data["endTimeUnixNano"]),
+                    attributes={
+                        attr["key"]: list(attr["value"].values())[0]
+                        for attr in span_data.get("attributes", [])
+                    },
+                    events=span_data.get("events", []),
+                    resource_attributes=resource_attributes,
+                )
+
+                all_spans[span_id] = span
+
+    # Step 2: Build the hierarchy by connecting parents and children
+    root_spans = []
+
+    for span in all_spans.values():
+        if span.parent_span_id is None:
+            # This is a root span
+            root_spans.append(span)
+        else:
+            # Add this span as a child to its parent
+            if span.parent_span_id in all_spans:
+                all_spans[span.parent_span_id].children.append(span)
+
+    return root_spans
+
+
+def format_labels(attributes, key_labels):
+    """Format the specified labels from attributes into a string"""
+    result = []
+    for key in key_labels:
+        if key in attributes:
+            result.append(f"{key}='{attributes[key]}'")
+
+    return " ".join(result) if result else None
+
+
+def format_span_tree(span: Span, level: int = 0, key_labels: List[str] = []) -> str:
+    """Format the span hierarchy in a tree format with timestamps and labels"""
+    span_tree_text = ""
+    indent = "  " * level
+    duration = span.duration_ms
+
+    span_tree_text += f"{indent}├─ {span.name} ({span.service_name}) - {duration:.2f}ms (span_id={span.span_id})\n"
+
+    start_time_str = unix_nano_to_rfc3339(span.start_time)
+    end_time_str = unix_nano_to_rfc3339(span.end_time)
+    span_tree_text += (
+        f"{indent}│  Datetime: start={start_time_str} end={end_time_str}\n"
+    )
+
+    if key_labels and span.resource_attributes:
+        resource_labels = format_labels(span.resource_attributes, key_labels)
+        if resource_labels:
+            span_tree_text += f"{indent}│  Resource labels: {resource_labels}\n"
+
+    if span.attributes:
+        span_tree_text += f"{indent}│  Attributes:\n"
+        for key, value in span.attributes.items():
+            span_tree_text += f"{indent}│    {key}: {value}\n"
+
+        if key_labels:
+            span_labels = format_labels(span.attributes, key_labels)
+            if span_labels:
+                span_tree_text += f"{indent}│  Span labels: {span_labels}\n"
+
+    if span.events:
+        span_tree_text += f"{indent}│  Events:\n"
+        for event in span.events:
+            event_name = event["name"]
+            event_time = int(event["timeUnixNano"])
+            event_time_str = unix_nano_to_rfc3339(event_time)
+            relative_time = (event_time - span.start_time) / 1_000_000
+            span_tree_text += f"{indent}│    {event_name} (+{relative_time:.2f}ms) at {event_time_str}\n"
+
+            if "attributes" in event and event["attributes"]:
+                for attr in event["attributes"]:
+                    attr_key = attr["key"]
+                    values = list(attr["value"].values())
+                    if len(values) == 1:
+                        span_tree_text += (
+                            f"{indent}│      {attr_key}: {str(values[0])}\n"
+                        )
+                    elif values:
+                        span_tree_text += f"{indent}│      {attr_key}: {str(values)}\n"
+
+    for child in sorted(span.children, key=lambda s: s.start_time):
+        span_tree_text += format_span_tree(child, level + 1, key_labels)
+
+    return span_tree_text
+
+
+def process_trace(
+    trace_data: Dict,
+    key_labels: List[str] = [
+        "service.name",
+        "service.version",
+        "k8s.deployment.name",
+        "k8s.node.name",
+        "k8s.pod.name",
+        "k8s.namespace.name",
+    ],
+) -> str:
+    root_spans = build_span_hierarchy(trace_data)
+
+    span_trees = []
+    for root_span in sorted(root_spans, key=lambda s: s.start_time):
+        span_trees.append(format_span_tree(root_span, key_labels=key_labels))
+
+    return "\n\n".join(span_trees)
+
+
+def format_traces_list(trace_data: Dict) -> str:
+    traces = trace_data.get("traces", [])
+
+    if len(traces) > 0:
+        traces_str = []
+        for trace in traces:
+            trace_str = f"Trace (traceID={trace.get('traceID')})"
+            trace_str += (
+                f" (durationMs={trace.get('durationMs')})\n"
+                if trace.get("durationMs") is not None
+                else "\n"
+            )
+            trace_str += f"\tstartTime={unix_nano_to_rfc3339(int(trace.get('startTimeUnixNano')))}"
+            trace_str += f" rootServiceName={trace.get('trootServiceName')}"
+            trace_str += f" rootTraceName={trace.get('rootTraceName')}"
+            traces_str.append(trace_str)
+        return "\n".join(traces_str)
+    else:
+        return "No matching trace could be found"

holmes/plugins/toolsets/helm.yaml

@@ -0,0 +1,42 @@
+toolsets:
+  helm/core:
+    description: "Read access to cluster's Helm charts and releases"
+    docs_url: "https://docs.robusta.dev/master/configuration/holmesgpt/toolsets/helm.html"
+    icon_url: "https://helm.sh/img/helm.svg"
+    tags:
+      - core
+    prerequisites:
+      - command: "helm version"
+
+    tools:
+      - name: "helm_list"
+        description: "Use to get all the current helm releases"
+        command: "helm list"
+
+      - name: "helm_values"
+        description: "Use to gather Helm values or any released helm chart"
+        command: "helm get values -a {{ release_name }} -n {{ namespace }} -o json"
+
+      - name: "helm_status"
+        description: "Check the status of a Helm release"
+        command: "helm status {{ release_name }} -n {{ namespace }}"
+
+      - name: "helm_history"
+        description: "Get the revision history of a Helm release"
+        command: "helm history {{ release_name }} -n {{ namespace }}"
+
+      - name: "helm_manifest"
+        description: "Fetch the generated Kubernetes manifest for a Helm release"
+        command: "helm get manifest {{ release_name }} -n {{ namespace }}"
+
+      - name: "helm_hooks"
+        description: "Get the hooks for a Helm release"
+        command: "helm get hooks {{ release_name }} -n {{ namespace }}"
+
+      - name: "helm_chart"
+        description: "Show the chart used to create a Helm release"
+        command: "helm get chart {{ release_name }} -n {{ namespace }}"
+
+      - name: "helm_notes"
+        description: "Show the notes provided by the Helm chart"
+        command: "helm get notes {{ release_name }} -n {{ namespace }}"