diff --git a/docs/configuration/holmesgpt/builtin_toolsets.rst b/docs/configuration/holmesgpt/builtin_toolsets.rst index 2c9656bef..3091825a5 100644 --- a/docs/configuration/holmesgpt/builtin_toolsets.rst +++ b/docs/configuration/holmesgpt/builtin_toolsets.rst @@ -10,7 +10,8 @@ Builtin Toolsets toolsets/aws toolsets/confluence toolsets/docker - toolsets/grafana + toolsets/grafanaloki + toolsets/grafanatempo toolsets/helm toolsets/internet toolsets/kafka diff --git a/docs/configuration/holmesgpt/custom_toolsets.rst b/docs/configuration/holmesgpt/custom_toolsets.rst index 9ece59804..771ad980a 100644 --- a/docs/configuration/holmesgpt/custom_toolsets.rst +++ b/docs/configuration/holmesgpt/custom_toolsets.rst @@ -7,76 +7,138 @@ Custom toolsets Examples -------- -Below are examples of predefined toolsets for various use cases, such as managing GitHub repositories, diagnosing Kubernetes clusters, and making HTTP requests. In these examples, we will demonstrate how to add these toolsets to Holmes. +Below are examples of custom toolsets and how to add them to Holmes: -Example 1: Github Toolset -^^^^^^^^^^^^^^^^^^^^^^^^^ +Example 1: Grafana Toolset +^^^^^^^^^^^^^^^^^^^^^^^^^^^ -This toolset enables Holmes to interact with fetch information from github repositories. +This toolset lets Holmes view Grafana dashboards and suggest relevant dashboards to the user: +**Prerequisites:** -.. code-block:: yaml +- Grafana URL (e.g. http://localhost:3000 or https://grafana.example.com) +- Grafana service account token with **Basic role -> Viewer** and **Data sources -> Reader** permissions. Check out this `video `_ on creating a Grafana service account token. + +**Configuration:** + +.. md-tab-set:: + + .. md-tab-item:: Robusta Helm Chart + + **Helm Values:** + + .. code-block:: yaml + + holmes: + # provide environment variables the toolset needs - can be pulled from secrets or provided in plaintext + additionalEnvVars: + - name: GRAFANA_API_KEY + value: + - name: GRAFANA_URL + value: + + # define the toolset + toolsets: + grafana: + # this tool can only be enabled if these prerequisites are met + prerequisites: + # we need the GRAFANA_URL and GRAFANA_API_KEY environment variables to be set + - env: + - "GRAFANA_URL" + - "GRAFANA_API_KEY" + # curl must be installed - we check by running `curl --version` (if it's not installed, the command will fail) + - command: "curl --version" + + # human-readable description of the toolset (this is not seen by the AI model - its just for users) + description: "Grafana tools" + + # tools (capabilities) that will be provided to HolmesGPT when this toolset is enabled + tools: + - name: "grafana_get_dashboard" + # the LLM sees this description and uses it to decide when to use this tool + description: "Get list of grafana dashboards" + # the command that will be executed when this tool is used + # environment variables like GRAFANA_URL and GRAFANA_API_KEY can be used in the command + # they will not be exposed to the AI model, as the AI model doesn't see the command that was run + command: "curl \"${GRAFANA_URL}/api/search\" -H \"Authorization: Bearer ${GRAFANA_API_KEY}\"" + + - name: "grafana_get_url" + description: "Get the URL of a Grafana dashboard by UID, including the real URL of Grafana" + # in this command we use a variable called `{{ dashboard_uid }}` + # unlike enviroment variables that were provided by the user, variables like `{{ dashboard_uid }}` are provided by the AI model + # the AI model sees the tool description, decides to use this tool, and then provides a value for all {{ template_variables }} to invoke the tool + command: "echo \"${GRAFANA_URL}/d/{{ dashboard_uid }}\"" + + Update your Helm values with the provided YAML configuration, then apply the changes with Helm upgrade: + + .. code-block:: bash + + helm upgrade robusta robusta/robusta --values=generated_values.yaml --set clusterName= + + After the deployment is complete, you can open the HolmesGPT chat in the Robusta SaaS UI and ask questions like *what grafana dashboard should I look at to investigate high pod cpu?*. + + **Suggesting relevant dashboards during alert investigations:** Add runbook instructions to your alert in the Robusta UI, instructing Holmes to search for related Grafana dashboards. + + .. image:: /images/custom-grafana-toolset.png + :width: 600 + :align: center + + .. md-tab-item:: Holmes CLI + + **grafana_toolset.yaml:** + + .. code-block:: yaml - holmes: toolsets: - github_tools: - description: "Tools for managing GitHub repositories" - tags: - - cli + grafana: + # this tool can only be enabled if these prerequisites are met prerequisites: + # we need the GRAFANA_URL and GRAFANA_API_KEY environment variables to be set - env: - - "GITHUB_TOKEN" + - "GRAFANA_URL" + - "GRAFANA_API_KEY" + # curl must be installed - we check by running `curl --version` (if it's not installed, the command will fail) - command: "curl --version" + + # human-readable description of the toolset (this is not seen by the AI model - its just for users) + description: "Grafana tools" + + # tools (capabilities) that will be provided to HolmesGPT when this toolset is enabled tools: - # Parameters are inferred from placeholders such as `{{ username }}` in the command. - # Holmes uses these placeholders to identify and request the required inputs for the tool. - - name: "list_user_repos" - description: "Lists all repositories for a GitHub user" - command: "curl -H 'Authorization: token ${GITHUB_TOKEN}' https://api.github.com/users/{{ username }}/repos" - - - name: "show_recent_commits" - description: "Shows the most recent commits for a repository" - command: "cd {{ repo_dir }} && git log -{{number_of_commits}} --oneline" - - # Here, parameters `owner` and `repo` are explicitly defined with details like type, - # description, and whether they are required. Explicitly defining parameters is - # particularly useful if: - # - You want to enforce parameter requirements (e.g., `owner` and `repo` are required). - # - You want to define optional parameters with default behavior. - - name: "get_repo_details" - description: "Fetches details of a specific repository" - command: "curl -H 'Authorization: token ${GITHUB_TOKEN}' https://api.github.com/repos/{{ owner }}/{{ repo }}" - parameters: - owner: - type: "string" - description: "Owner of the repository." - required: true - repo: - type: "string" - description: "Name of the repository." - required: true - - - name: "get_recent_commits" - description: "Fetches the most recent commits for a repository" - command: "curl -H 'Authorization: token {{ github_token }}' https://api.github.com/repos/{{ owner }}/{{ repo }}/commits?per_page={{ limit }} " + - name: "grafana_get_dashboard" + # the LLM sees this description and uses it to decide when to use this tool + description: "Get list of grafana dashboards" + # the command that will be executed when this tool is used + # environment variables like GRAFANA_URL and GRAFANA_API_KEY can be used in the command + # they will not be exposed to the AI model, as the AI model doesn't see the command that was run + command: "curl \"${GRAFANA_URL}/api/search\" -H \"Authorization: Bearer ${GRAFANA_API_KEY}\"" + - name: "grafana_get_url" + description: "Get the URL of a Grafana dashboard by UID, including the real url of grafana" + # in this command we use a variable called `{{ dashboard_uid }}` + # unlike enviroment variables that were provided by the user, variables like `{{ dashboard_uid }}` are provided by the AI model + # the AI model sees the tool description, decides to use this tool, and then provides a value for all {{ template_variables }} to invoke the tool + command: "echo \"${GRAFANA_URL}/d/{{ dashboard_uid }}\"" -Update the ``generated_values.yaml`` file with the provided YAML configuration, then apply the changes by executing the Helm upgrade command: + Set the appropriate environment variables and run Holmes: -.. code-block:: bash + .. code-block:: bash - helm upgrade robusta robusta/robusta --values=generated_values.yaml --set clusterName= + export GRAFANA_API_KEY="" + export GRAFANA_URL="" + + To test, run: -After the deployment is complete, the GitHub toolset will be available for Holmes. LLM will be able to use these tools to interact with GitHub repositories directly. + .. code-block:: bash + holmes ask -t grafana_toolset.yaml "what grafana dashboard should I look at to investigate high pod cpu?" Example 2: Kubernetes Diagnostics Toolset ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This toolset provides diagnostics for Kubernetes clusters, helping developers identify and resolve issues. - .. code-block:: yaml holmes: @@ -104,11 +166,6 @@ This toolset provides diagnostics for Kubernetes clusters, helping developers id description: "List all evicted pods in a specific namespace." command: "kubectl get pods -n {{ namespace }} --field-selector=status.phase=Failed | grep Evicted" - - name: "kubectl_drain_node" - description: "Drain a node safely by evicting all pods." - command: "kubectl drain {{ node_name }} --ignore-daemonsets --force --delete-emptydir-data" - - Update the ``generated_values.yaml`` file with the provided YAML configuration, then apply the changes by executing the Helm upgrade command: .. code-block:: bash @@ -118,43 +175,117 @@ Update the ``generated_values.yaml`` file with the provided YAML configuration, Once deployed, Holmes will have access to advanced diagnostic tools for Kubernetes clusters. For example, you can ask Holmes, ``"Can you do a node health check?"`` and it will automatically use the newly added tools to provide you the answer. -Example 3: HTTP Toolset -^^^^^^^^^^^^^^^^^^^^^^^ - -The HTTP Toolset allows Holmes to retrieve website content and execute queries with customizable parameters. - -.. code-block:: yaml - - - holmes: - toolsets: - http_tools: - description: "A simple toolset for fetching a website's content." - docs_url: "https://example.com" - icon_url: "https://example.com/favicon.ico" - tags: - - cluster - prerequisites: - - command: "curl -o /dev/null -s -w '%{http_code}' https://example.com " - expected_output: "200" - tools: - - - name: "fetch_url" - description: "Fetch the content of any website using a GET request." - command: "curl -X GET {{ url }}" - - - name: "fetch_url_with_params" - description: "Fetch a website's content with query parameters." - command: "curl -X GET '{{ url }}?{{ key }}={{ value }}'" - - -Once you have updated the ``generated_values.yaml`` file, apply the changes by running the Helm upgrade command: - -.. code-block:: bash - - helm upgrade robusta robusta/robusta --values=generated_values.yaml --set clusterName= +Example 3: GitHub Toolset +^^^^^^^^^^^^^^^^^^^^^^^^^ -Once deployed, you can ask Holmes, ``"Can you fetch data from https://example.com with key=search and value=tools?"``. +This toolset enables Holmes to fetch information from GitHub repositories. + +First `create a GitHub Personal Access Token with fine-grained permissions `_. For this example, you can leave the default permissions. + +.. md-tab-set:: + + .. md-tab-item:: Robusta Helm Chart + + **Helm Values:** + + .. code-block:: yaml + + holmes: + # provide environment variables the toolset needs + additionalEnvVars: + - name: GITHUB_TOKEN + value: + + # define the toolset itself + toolsets: + github_tools: + description: "Tools for managing GitHub repositories" + tags: + - cli + prerequisites: + - env: + - "GITHUB_TOKEN" + - command: "curl --version" + tools: + - name: "get_recent_commits" + description: "Fetches the most recent commits for a repository" + command: "curl -H 'Authorization: token ${GITHUB_TOKEN}' https://api.github.com/repos/{{ owner }}/{{ repo }}/commits?per_page={{ limit }} " + + - name: "get_repo_details" + description: "Fetches details of a specific repository" + command: "curl -H 'Authorization: token ${GITHUB_TOKEN}' https://api.github.com/repos/{{ owner }}/{{ repo }}" + + # In the above examples, LLM-provided parameters like {{ owner }} are inferred automatically from the command + # you can also define them explicitly - this is useful if: + # - You want to enforce parameter requirements (e.g., `owner` and `repo` are required). + # - You want to define provide a default value for optional parameters. + parameters: + owner: + type: "string" + description: "Owner of the repository." + required: true + repo: + type: "string" + description: "Name of the repository." + required: true + + Update your Helm values with the provided YAML configuration, then apply the changes with Helm upgrade: + + .. code-block:: bash + + helm upgrade robusta robusta/robusta --values=generated_values.yaml --set clusterName= + + After the deployment is complete, the GitHub toolset will be available. HolmesGPT will be able to use it to interact with GitHub repositories. + For example, you can now open the HolmesGPT chat in the Robusta SaaS UI and ask, *who made the last commit to the robusta-dev/holmesgpt repo on github?*. + + .. image:: /images/custom-github-toolset.png + :width: 600 + :align: center + + .. md-tab-item:: Holmes CLI + + First, add the following environment vairables: + + .. code-block:: bash + + export GITHUB_TOKEN="" + + Then, add the following to **~/.holmes/config.yaml**, creating the file if it doesn't exist: + + .. code-block:: yaml + + toolsets: + github_tools: + description: "Tools for managing GitHub repositories" + tags: + - cli + prerequisites: + - env: + - "GITHUB_TOKEN" + - command: "curl --version" + tools: + - name: "get_recent_commits" + description: "Fetches the most recent commits for a repository" + command: "curl -H 'Authorization: token ${GITHUB_TOKEN}' https://api.github.com/repos/{{ owner }}/{{ repo }}/commits?per_page={{ limit }} " + + # In the above examples, LLM-provided parameters like {{ owner }} are inferred automatically from the command + # you can also define them explicitly - this is useful if: + # - You want to enforce parameter requirements (e.g., `owner` and `repo` are required). + # - You want to define provide a default value for optional parameters. + parameters: + owner: + type: "string" + description: "Owner of the repository." + required: true + repo: + type: "string" + description: "Name of the repository." + required: true + To test, run: + + .. code-block:: yaml + + holmes ask -t github_toolset.yaml "who made the last commit to the robusta-dev/holmesgpt repo on github?" Reference diff --git a/docs/configuration/holmesgpt/toolsets/_toolset_configuration.inc.rst b/docs/configuration/holmesgpt/toolsets/_toolset_configuration.inc.rst index 3705b865b..33bb6106b 100644 --- a/docs/configuration/holmesgpt/toolsets/_toolset_configuration.inc.rst +++ b/docs/configuration/holmesgpt/toolsets/_toolset_configuration.inc.rst @@ -1,11 +1,7 @@ -.. details:: Enable this integration +Update your Helm values (generated_values.yaml) with the above configuration and run a Helm upgrade: - To enable this integration, copy the above example into your Helm values for Robusta (``generated_values.yaml``). +.. code-block:: bash - After making changes, apply them using Helm: - - .. code-block:: bash - - helm upgrade robusta robusta/robusta --values=generated_values.yaml --set clusterName= + helm upgrade robusta robusta/robusta --values=generated_values.yaml --set clusterName= diff --git a/docs/configuration/holmesgpt/toolsets/argocd.rst b/docs/configuration/holmesgpt/toolsets/argocd.rst index 5f4091bf0..f4f321d5a 100644 --- a/docs/configuration/holmesgpt/toolsets/argocd.rst +++ b/docs/configuration/holmesgpt/toolsets/argocd.rst @@ -39,7 +39,7 @@ HolmesGPT needs permission to establish a port-forward to ArgoCD. The configurat toolsets: argocd/core: enabled: true - + .. note:: Change the namespace ``--port-forward-namespace `` to the namespace in which your argocd service @@ -48,25 +48,55 @@ HolmesGPT needs permission to establish a port-forward to ArgoCD. The configurat The option ``--grpc-web`` in ``ARGOCD_OPTS`` prevents some connection errors from leaking into the tool responses and provides a cleaner output for HolmesGPT. +.. include:: ./_toolset_configuration.inc.rst + 2. Server URL ^^^^^^^^^^^^^ This is the recommended approach if your argocd is reachable through a public DNS. -.. code-block:: yaml - holmes: - additionalEnvVars: - - name: ARGOCD_AUTH_TOKEN - value: - - name: ARGOCD_SERVER - value: argocd.example.com - toolsets: - argocd/core: - enabled: true +.. md-tab-set:: -.. include:: ./_toolset_configuration.inc.rst + .. md-tab-item:: Robusta Helm Chart + + .. code-block:: yaml + + holmes: + additionalEnvVars: + - name: ARGOCD_AUTH_TOKEN + value: + - name: ARGOCD_SERVER + value: argocd.example.com + toolsets: + argocd/core: + enabled: true + + .. include:: ./_toolset_configuration.inc.rst + + .. md-tab-item:: Holmes CLI + + First create the `ARGOCD_AUTH_TOKEN` environment variable: + + .. code-block:: shell + + export ARGOCD_AUTH_TOKEN="" + export ARGOCD_SERVER="argocd.example.com" + + Then add the following to **~/.holmes/config.yaml**, creating the file if it doesn't exist: + + .. code-block:: yaml + + toolsets: + argocd/core: + enabled: true + + To test, run: + + .. code-block:: yaml + + holmes ask "Which argocd applications are failing and why?" Capabilities ------------ diff --git a/docs/configuration/holmesgpt/toolsets/aws.rst b/docs/configuration/holmesgpt/toolsets/aws.rst index a51bc6b56..33925f415 100644 --- a/docs/configuration/holmesgpt/toolsets/aws.rst +++ b/docs/configuration/holmesgpt/toolsets/aws.rst @@ -1,5 +1,5 @@ AWS -=== +===== Security -------- @@ -8,26 +8,58 @@ Set of tools to audit AWS cloudtrail events and audit logs. Configuration -************* +*************** + + +.. md-tab-set:: + + .. md-tab-item:: Robusta Helm Chart + + .. code-block:: yaml + + holmes: + additionalEnvVars: + - name: AWS_ACCESS_KEY_ID + value: AKIAIOSFODNN7EXAMPLE + - name: AWS_SECRET_ACCESS_KEY + value: =wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY + - name: AWS_DEFAULT_REGION + value: us-west-2 + toolsets: + aws/security: + enabled: true + + .. include:: ./_toolset_configuration.inc.rst + + .. md-tab-item:: Holmes CLI + + + First, add the following environment vairables: + + .. code-block:: yaml + + export AWS_ACCESS_KEY_ID="" + export AWS_SECRET_ACCESS_KEY="" + export AWS_DEFAULT_REGION="us-west-2" + + + Then, add the following to **~/.holmes/config.yaml**, creating the file if it doesn't exist: + + .. code-block:: yaml -.. code-block:: yaml + toolsets: + aws/security: + enabled: true - holmes: - additionalEnvVars: - - name: AWS_ACCESS_KEY_ID - value: AKIAIOSFODNN7EXAMPLE - - name: AWS_SECRET_ACCESS_KEY - value: =wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY - - name: AWS_DEFAULT_REGION - value: us-west-2 - toolsets: - aws/security: - enabled: true -.. include:: ./_toolset_configuration.inc.rst + To test, run: + + .. code-block:: yaml + + holmes ask "Are there any security misconfigurations my signup application, particularly in the database?" Capabilities -************ +************** .. include:: ./_toolset_capabilities.inc.rst .. list-table:: @@ -45,31 +77,61 @@ Capabilities RDS ---- +---- Read access to Amazon RDS instances, events and logs Configuration -************ +**************** + +.. md-tab-set:: + + .. md-tab-item:: Robusta Helm Chart + + .. code-block:: yaml + + holmes: + additionalEnvVars: + - name: AWS_ACCESS_KEY_ID + value: AKIXDDDSDSdSA + - name: AWS_SECRET_ACCESS_KEY + value: =wJalrXUtnFEMI/KNG/bPxRfiCYEXAMPLEKEY + - name: AWS_DEFAULT_REGION + value: us-west-2 + toolsets: + aws/rds: + enabled: true + + .. include:: ./_toolset_configuration.inc.rst + + .. md-tab-item:: Holmes CLI + + First, add the following environment vairables: -.. code-block:: yaml + .. code-block:: yaml - holmes: - additionalEnvVars: - - name: AWS_ACCESS_KEY_ID - value: AKIAIOSFODNN7EXAMPLE - - name: AWS_SECRET_ACCESS_KEY - value: =wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY - - name: AWS_DEFAULT_REGION - value: us-west-2 - toolsets: - aws/rds: - enabled: true + export AWS_ACCESS_KEY_ID="" + export AWS_SECRET_ACCESS_KEY="" + export AWS_DEFAULT_REGION="us-west-2" + + Then, add the following to **~/.holmes/config.yaml**, creating the file if it doesn't exist: + + .. code-block:: yaml + + toolsets: + aws/rds: + enabled: true + + To test, run: + + .. code-block:: yaml + + holmes ask "Why is my signup application slow, also look into the database" -.. include:: ./_toolset_configuration.inc.rst Capabilities -************ +************* + .. include:: ./_toolset_capabilities.inc.rst .. list-table:: diff --git a/docs/configuration/holmesgpt/toolsets/confluence.rst b/docs/configuration/holmesgpt/toolsets/confluence.rst index 6800c918a..17a4d8f98 100644 --- a/docs/configuration/holmesgpt/toolsets/confluence.rst +++ b/docs/configuration/holmesgpt/toolsets/confluence.rst @@ -3,27 +3,50 @@ Confluence By enabling this toolset, HolmesGPT will be able to fetch confluence pages. This is particularly useful if you store runbooks in Confluence and want Holmes to run investigations using these runbooks. -This toolset requires an `API key `_. +This toolset requires an `Atlassian API Key `_. Configuration ------------- -.. code-block:: yaml - - holmes: - additionalEnvVars: - - name: CONFLUENCE_USER - value: - - name: CONFLUENCE_API_KEY - value: - - name: CONFLUENCE_BASE_URL - value: - toolsets: - confluence: - enabled: true - -.. include:: ./_toolset_configuration.inc.rst +.. md-tab-set:: + + .. md-tab-item:: Robusta Helm Chart + + **Helm Values:** + + .. code-block:: yaml + + holmes: + additionalEnvVars: + - name: CONFLUENCE_USER + value: + - name: CONFLUENCE_API_KEY + value: + - name: CONFLUENCE_BASE_URL + value: + toolsets: + confluence: + enabled: true + + .. include:: ./_toolset_configuration.inc.rst + + .. md-tab-item:: Holmes CLI + + Set the following environment variables and the Confluence toolset will be automatically enabled: + + .. code-block:: shell + + export CONFLUENCE_USER="" + export CONFLUENCE_API_KEY="" + export CONFLUENCE_BASE_URL="" + + + To test, run: + + .. code-block:: yaml + + holmes ask "why is my application failing? Get revelant runbooks from Confluence" Capabilities ------------ diff --git a/docs/configuration/holmesgpt/toolsets/grafana.rst b/docs/configuration/holmesgpt/toolsets/grafana.rst deleted file mode 100644 index c98271f12..000000000 --- a/docs/configuration/holmesgpt/toolsets/grafana.rst +++ /dev/null @@ -1,118 +0,0 @@ -Grafana -======= - -Loki ----- - -By enabling this toolset, HolmesGPT will be able to consult node and pod logs from `Loki `_ -by proxying through a `Grafana `_ instance. - -In the future this toolset will be able to run any query against Loki logs. - -Configuration -^^^^^^^^^^^^^ - -The configuration requires a `service account token `_ -from your Grafana instance. - -.. code-block:: yaml - - holmes: - toolsets: - grafana/loki: - enabled: true - config: - api_key: - url: https://xxxxxxx.grafana.net # Your Grafana cloud account URL - -You can optionally tweak the search terms used by the toolset. This is only needed if your Loki logs settings for pod, -namespace and node differ from the defaults listed below. To do so, add these search keys to the configuration: - -.. code-block:: yaml - - holmes: - toolsets: - grafana/loki: - enabled: true - config: - api_key: - url: https://xxxxxxx.grafana.net # Your Grafana cloud account URL - pod_name_search_key: "pod" - namespace_search_key: "namespace" - node_name_search_key: "node" - -.. include:: ./_toolset_configuration.inc.rst - -Capabilities -^^^^^^^^^^^^ - -.. include:: ./_toolset_capabilities.inc.rst - -.. list-table:: - :header-rows: 1 - :widths: 30 70 - - * - Tool Name - - Description - * - list_loki_datasources - - Fetches the Loki data sources in Grafana - * - fetch_loki_logs_by_node - - Fetches the Loki logs for a given node - * - fetch_loki_logs_by_label - - Fetches the Loki logs for a label and value from a Tempo trace - * - fetch_loki_logs_by_pod - - Fetches the Loki logs for a given pod - - -Tempo ------ - -By enabling this toolset, HolmesGPT will be able to fetch trace information from Grafana -Tempo to debug performance related issues. - - -Configuration -^^^^^^^^^^^^^ - -Tempo is configured the using the same Grafana settings as the Grafana Loki toolset. The configuration requires -a `service account token `_ from -your Grafana instance. - -.. code-block:: yaml - - holmes: - toolsets: - grafana/tempo: - enabled: true - config: - api_key: - url: https://xxxxxxx.grafana.net # Your Grafana cloud account URL - -.. include:: ./_toolset_configuration.inc.rst - -Capabilities -^^^^^^^^^^^^ -.. include:: ./_toolset_capabilities.inc.rst - -.. list-table:: - :header-rows: 1 - :widths: 30 70 - - * - Tool Name - - Description - * - list_all_datasources - - Fetches All the data sources in Grafana - * - fetch_tempo_traces_by_min_duration - - Lists Tempo traces ids that exceed a specified minimum duration in a given time range - * - fetch_tempo_trace_by_id - - Retrieves detailed information about a Tempo trace using its trace ID. Use this to investigate a trace. - - -Getting Grafana URL ------------------------ - -You can find the Grafana URL required for Loki and Tempo in your Grafana cloud account settings. - -.. image:: /images/grafana-url-for-holmes.png - :width: 600 - :align: center diff --git a/docs/configuration/holmesgpt/toolsets/grafanaloki.rst b/docs/configuration/holmesgpt/toolsets/grafanaloki.rst new file mode 100644 index 000000000..275f8e8c3 --- /dev/null +++ b/docs/configuration/holmesgpt/toolsets/grafanaloki.rst @@ -0,0 +1,120 @@ +Loki (Grafana) +=============== + +By enabling this toolset, HolmesGPT will be able to query logs from `Loki `_ +by proxying through a `Grafana `_ instance. + +After this toolset is enabled, you can ask Holmes questions like: *Look at my cluster with kubectl, pick an arbitrary node, then fetch logs from loki for that node. Summarize all problems you find.* + +Prerequisites +^^^^^^^^^^^^^ +A `Grafana service account token `_ +with the following permissions: + +* Basic role -> Viewer +* Data sources -> Reader + +Check out this `video `_ on creating a Grafana service account token. + +Getting Grafana URL +----------------------- + +You can find the Grafana URL required for Loki and Tempo in your Grafana cloud account settings. + +.. image:: /images/grafana-url-for-holmes.png + :width: 600 + :align: center + +Configuration +^^^^^^^^^^^^^ + +.. md-tab-set:: + + .. md-tab-item:: Robusta Helm Chart + + Add the following to **Robusta's Helm values:** + + .. code-block:: yaml + + holmes: + toolsets: + grafana/loki: + enabled: true + config: + api_key: + url: # e.g. https://acme-corp.grafana.net + + .. include:: ./_toolset_configuration.inc.rst + + You can optionally tweak the search terms used by the toolset. This is only needed if your Loki logs settings for pod, + namespace and node differ from the defaults listed below. To do so, add these search keys to the configuration: + + .. code-block:: yaml + + holmes: + toolsets: + grafana/loki: + enabled: true + config: + api_key: + url: # e.g. https://acme-corp.grafana.net + pod_name_search_key: "pod" + namespace_search_key: "namespace" + node_name_search_key: "node" + + .. md-tab-item:: Holmes CLI + + Add the following to **~/.holmes/config.yaml**, creating the file if it doesn't exist: + + .. code-block:: yaml + + toolsets: + grafana/loki: + enabled: true + config: + api_key: + url: # e.g. https://acme-corp.grafana.net + + You can optionally tweak the search terms used by the toolset. This is only needed if your Loki logs settings for pod, + namespace and node differ from the defaults listed below. To do so, add these search keys to the configuration: + + .. code-block:: yaml + + toolsets: + grafana/loki: + enabled: true + config: + api_key: + url: # e.g. https://acme-corp.grafana.net + pod_name_search_key: "pod" + namespace_search_key: "namespace" + node_name_search_key: "node" + + To test, run: + + .. code-block:: yaml + + holmes ask "Which applications have an issue and check the logs on loki for the reasons" + +Capabilities +^^^^^^^^^^^^ + +.. include:: ./_toolset_capabilities.inc.rst + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Tool Name + - Description + * - list_loki_datasources + - Fetches the Loki data sources in Grafana + * - fetch_loki_logs_by_node + - Fetches the Loki logs for a given node + * - fetch_loki_logs_by_label + - Fetches the Loki logs for a label and value from a Tempo trace + * - fetch_loki_logs_by_pod + - Fetches the Loki logs for a given pod + + + diff --git a/docs/configuration/holmesgpt/toolsets/grafanatempo.rst b/docs/configuration/holmesgpt/toolsets/grafanatempo.rst new file mode 100644 index 000000000..3579de43c --- /dev/null +++ b/docs/configuration/holmesgpt/toolsets/grafanatempo.rst @@ -0,0 +1,81 @@ + +Tempo (Grafana) +================ + +By enabling this toolset, HolmesGPT will be able to fetch trace information from Grafana +Tempo to debug performance related issues, like high latency in your application. + +Prerequisites +^^^^^^^^^^^^^ +A `Grafana service account token `_ +with the following permissions: + +* Basic role -> Viewer +* Data sources -> Reader + +Check out this `video `_ on creating a Grafana service account token. + +Getting Grafana URL +----------------------- + +You can find the Grafana URL required for Loki and Tempo in your Grafana cloud account settings. + +.. image:: /images/grafana-url-for-holmes.png + :width: 600 + :align: center + +Configuration +^^^^^^^^^^^^^ + +.. md-tab-set:: + + .. md-tab-item:: Robusta Helm Chat + + .. code-block:: yaml + + holmes: + toolsets: + grafana/tempo: + enabled: true + config: + api_key: + url: https://grafana-url + + .. include:: ./_toolset_configuration.inc.rst + + .. md-tab-item:: Holmes CLI + + Add the following to **~/.holmes/config.yaml**, creating the file if it doesn't exist: + + .. code-block:: yaml + + toolsets: + grafana/tempo: + enabled: true + config: + api_key: + url: # e.g. https://acme-corp.grafana.net + + To test, run: + + .. code-block:: yaml + + holmes ask "The payments DB is very slow, check tempo for any trace data" + +Capabilities +^^^^^^^^^^^^ +.. include:: ./_toolset_capabilities.inc.rst + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Tool Name + - Description + * - list_all_datasources + - Fetches All the data sources in Grafana + * - fetch_tempo_traces_by_min_duration + - Lists Tempo traces ids that exceed a specified minimum duration in a given time range + * - fetch_tempo_trace_by_id + - Retrieves detailed information about a Tempo trace using its trace ID. Use this to investigate a trace. + diff --git a/docs/configuration/holmesgpt/toolsets/opensearch.rst b/docs/configuration/holmesgpt/toolsets/opensearch.rst index ba392cd63..a0d5e4859 100644 --- a/docs/configuration/holmesgpt/toolsets/opensearch.rst +++ b/docs/configuration/holmesgpt/toolsets/opensearch.rst @@ -77,4 +77,4 @@ Capabilities * - opensearch_get_cluster_settings - Retrieve the cluster's settings * - opensearch_get_cluster_health - - Retrieve the cluster's health + - Retrieve the cluster's health \ No newline at end of file diff --git a/docs/configuration/holmesgpt/toolsets/slab.rst b/docs/configuration/holmesgpt/toolsets/slab.rst index b6f01e138..7f68d49b4 100644 --- a/docs/configuration/holmesgpt/toolsets/slab.rst +++ b/docs/configuration/holmesgpt/toolsets/slab.rst @@ -7,17 +7,47 @@ Retrieve your Slab `API token - toolsets: +.. md-tab-set:: + + .. md-tab-item:: Robusta Helm Chart + + .. code-block:: yaml + + holmes: + additionalEnvVars: + - name: SLAB_API_KEY + value: + toolsets: + slab: + enabled: true + + .. include:: ./_toolset_configuration.inc.rst + + + .. md-tab-item:: Holmes CLI + + First create the following environment variable: + + .. code-block:: shell + + export SLAB_API_KEY="" + + + Then add the following to **~/.holmes/config.yaml**, creating the file if it doesn't exist: + + .. code-block:: yaml + + toolsets: slab: - enabled: true + enabled: true + + To test, run: + + .. code-block:: yaml + + holmes ask "Why is my pod failing, if its a crashloopbackoff use the runbooks from slab" -.. include:: ./_toolset_configuration.inc.rst Capabilities ------------ diff --git a/docs/images/custom-github-toolset.png b/docs/images/custom-github-toolset.png new file mode 100644 index 000000000..b1f918f49 Binary files /dev/null and b/docs/images/custom-github-toolset.png differ diff --git a/docs/images/custom-grafana-toolset.png b/docs/images/custom-grafana-toolset.png new file mode 100644 index 000000000..de4933dbf Binary files /dev/null and b/docs/images/custom-grafana-toolset.png differ