ROB-1267: update docs for logging toolsets due to unified logging refactor (#1823)

* ROB-1267: update docs for logging toolsets due to unified logging refactor

Author: nherment

docs/configuration/holmesgpt/builtin_toolsets.rst

@@ -19,7 +19,8 @@ Builtin Toolsets
    toolsets/kafka
    toolsets/kubernetes
    toolsets/notion
-   toolsets/opensearch
+   toolsets/opensearch_logs
+   toolsets/opensearch_status
    toolsets/prometheus
    toolsets/rabbitmq
    toolsets/robusta
@@ -105,9 +106,14 @@ by the user by providing credentials or API keys to external systems.
         :link: toolsets/notion
         :link-type: doc
 
-    .. grid-item-card:: :octicon:`cpu;1em;` OpenSearch
+    .. grid-item-card:: :octicon:`cpu;1em;` OpenSearch logs
         :class-card: sd-bg-light sd-bg-text-light
-        :link: toolsets/opensearch
+        :link: toolsets/opensearch_logs
+        :link-type: doc
+
+    .. grid-item-card:: :octicon:`cpu;1em;` OpenSearch status
+        :class-card: sd-bg-light sd-bg-text-light
+        :link: toolsets/opensearch_status
         :link-type: doc
 
     .. grid-item-card:: :octicon:`cpu;1em;` Prometheus

docs/configuration/holmesgpt/index.rst

@@ -365,7 +365,7 @@ Builtin toolsets
 
 Built-in toolsets cover essential areas like pod status inspection, node health analysis,
 application diagnostics, and resource utilization monitoring. These toolsets include access to
-Kubernetes events and logs, AWS, Grafana, Opensearch, etc. See the full list :doc:`here <builtin_toolsets>`.
+Kubernetes events and logs, AWS, Grafana, OpenSearch, etc. See the full list :doc:`here <builtin_toolsets>`.
 
 Custom toolsets
 ----------------

docs/configuration/holmesgpt/toolsets/_disable_default_logging_toolset.inc.rst

@@ -0,0 +1,31 @@
+
+Disabling the Default Logging Toolset
+*****************************************
+
+The default HolmesGPT logging tool **must** be disabled if you use a different datasource for logs.
+HolmesGPT may still use kubectl to fetch logs and never call your datasource if ``kubernetes/logs`` is not disabled. 
+To disable the default logging toolset, add the following to your holmes configuration:
+
+.. md-tab-set::
+
+  .. md-tab-item:: Robusta Helm Chart
+
+    .. code-block:: yaml
+
+      holmes:
+        toolsets:
+          kubernetes/logs:
+            enabled: false
+
+
+    .. 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:
+        kubernetes/logs:
+          enabled: false

docs/configuration/holmesgpt/toolsets/_toolsets_that_provide_logging.inc.rst

@@ -1,5 +1,6 @@
 HolmesGPT provides several out-of-the-box alternatives for log access. You can select from these options:
 
-* :ref:`kubernetes/logs <toolset_kubernetes_logs>`: Access logs with ``kubectl logs`` commands. **This is the default toolset.**
+* :ref:`kubernetes/logs <toolset_kubernetes_logs>`: Access logs directly through Kubernetes. **This is the default toolset.**
 * :ref:`coralogix/logs <toolset_coralogix_logs>`: Access logs through Coralogix.
 * :ref:`grafana/loki <toolset_grafana_loki>`: Access Loki logs by proxying through a Grafana instance.
+* :ref:`opensearch/logs <toolset_opensearch_logs>`: Access logs through OpenSearch.

docs/configuration/holmesgpt/toolsets/coralogix_logs.rst

@@ -3,10 +3,10 @@
 Coralogix logs
 ==============
 
-By enabling this toolset, HolmesGPT will fetch node and pods logs from `Coralogix <https://coralogix.com/>`_.
+By enabling this toolset, HolmesGPT will fetch pod logs from `Coralogix <https://coralogix.com/>`_.
 
 You **should** enable this toolset to replace the default :ref:`kubernetes/logs <toolset_kubernetes_logs>`
-toolset if all your kubernetes/pod logs are consolidated inside Coralogix. It will make it easier for HolmesGPT
+toolset if all your kubernetes pod logs are consolidated inside Coralogix. It will make it easier for HolmesGPT
 to fetch incident logs, including the ability to precisely consult past logs.
 
 
@@ -43,7 +43,7 @@ Configuration
               team_hostname: my-team # Your team's hostname in coralogix, without the domain part
 
           kubernetes/logs:
-            enabled: false # Disable HolmesGPT's default logging mechanism
+            enabled: false # HolmesGPT's default logging mechanism MUST be disabled
 
 
     .. include:: ./_toolset_configuration.inc.rst
@@ -63,13 +63,13 @@ Configuration
             team_hostname: my-team # Your team's hostname in coralogix
 
         kubernetes/logs:
-          enabled: false # Disable HolmesGPT's default logging mechanism
+          enabled: false # HolmesGPT's default logging mechanism MUST be disabled
 
 Advanced Configuration
 ^^^^^^^^^^^^^^^^^^^^^^
 
 Frequent logs and archive
-****************************
+*************************
 
 By default, holmes fetched the logs from the `Frequent search <https://coralogix.com/docs/user-guides/account-management/tco-optimizer/logs/#frequent-search-data-high-priority>`_ 
 tier and only fetch logs from the `Archive` tier if the frequent search returned no result.
@@ -100,10 +100,10 @@ Here is a description of each possible log retrieval methodology:
 - **BOTH_FREQUENT_SEARCH_AND_ARCHIVE** Always use both the frequent search and the archive to fetch logs. The result contains merged data which is deduplicated and sorted by timestamp.
 
 Search labels
-***************
+*************
 
 You can tweak the labels used by the toolset to identify kubernetes resources. This is **optional** and only needed if your
-logs settings for ``pod``, ``namespace``, ``application`` and ``subsystem`` differ from the defaults in the example below.
+logs settings for ``pod`` and ``namespace`` differ from the defaults in the example below.
 
 .. code-block:: yaml
 
@@ -114,8 +114,6 @@ logs settings for ``pod``, ``namespace``, ``application`` and ``subsystem`` diff
         labels: # OPTIONAL: tweak the filters used by HolmesGPT if your coralogix configuration is non standard
           namespace: "kubernetes.namespace_name"
           pod: "kubernetes.pod_name"
-          application: "coralogix.metadata.applicationName"
-          subsystem: "coralogix.metadata.subsystemName"
         ...
 
 
@@ -126,19 +124,8 @@ You can verify what labels to use by attempting to run a query in the coralogix
   :align: center
 
 
-Disabling the default toolset
-*********************************
 
-If Coralogix is your primary datasource for logs, it is **advised** to disable the default HolmesGPT logging
-tool by disabling the ``kubernetes/logs`` toolset. Without this. HolmesGPT may still use kubectl to
-fetch logs instead of Coralogix.
-
-.. code-block:: yaml
-
-    holmes:
-        toolsets:
-            kubernetes/logs:
-                enabled: false
+.. include:: ./_disable_default_logging_toolset.inc.rst
 
 
 Capabilities
@@ -152,5 +139,5 @@ Capabilities
 
    * - Tool Name
      - Description
-   * - fetch_coralogix_logs_for_resource
+   * - fetch_pod_logs
      - Retrieve logs using coralogix

docs/configuration/holmesgpt/toolsets/grafanaloki.rst

@@ -3,7 +3,7 @@
 Loki
 ====
 
-By enabling this toolset, HolmesGPT will fetch node and pods logs from `Loki <https://grafana.com/oss/loki/>`_.
+By enabling this toolset, HolmesGPT will fetch pod logs from `Loki <https://grafana.com/oss/loki/>`_.
 Loki can be accessed directly or by proxying through a `Grafana <https://grafana.com/oss/grafana/>`_ instance.
 
 You **should** enable this toolset to replace the default :ref:`kubernetes/logs <toolset_kubernetes_logs>`
@@ -20,7 +20,7 @@ Proxying through Grafana
 This is the recommended approach because we intend to add more capabilities to the toolset that are only available with Grafana.
 
 Prerequisites
--------------
+*************
 
 A `Grafana service account token <https://grafana.com/docs/grafana/latest/administration/service-accounts/>`_
 with the following permissions:
@@ -79,7 +79,7 @@ A simple way to get the datasource UID is to access the Grafana API by running t
 
 
 Configuration (grafana proxy)
------------------------------
+*****************************
 
 
 .. md-tab-set::
@@ -98,7 +98,7 @@ Configuration (grafana proxy)
               grafana_datasource_uid: <the UID of the loki data source in Grafana>
 
           kubernetes/logs:
-            enabled: false # Disable HolmesGPT's default logging mechanism
+            enabled: false # HolmesGPT's default logging mechanism MUST be disabled
 
 
     .. include:: ./_toolset_configuration.inc.rst
@@ -118,7 +118,7 @@ Configuration (grafana proxy)
             grafana_datasource_uid: <the UID of the loki data source in Grafana>
 
         kubernetes/logs:
-          enabled: false # Disable HolmesGPT's default logging mechanism
+          enabled: false # HolmesGPT's default logging mechanism MUST be disabled
 
 Direct connection
 ^^^^^^^^^^^^^^^^^
@@ -128,7 +128,7 @@ This is done by not setting the ``grafana_datasource_uid`` field. Not setting th
 assume that it is directly connecting to Loki.
 
 Configuration (direct connection)
----------------------------------
+*********************************
 
 .. md-tab-set::
 
@@ -146,7 +146,7 @@ Configuration (direct connection)
                 X-Scope-OrgID: "<tenant id>" # Set the X-Scope-OrgID if loki multitenancy is enabled
 
           kubernetes/logs:
-            enabled: false # Disable HolmesGPT's default logging mechanism
+            enabled: false # HolmesGPT's default logging mechanism MUST be disabled
 
 
     .. include:: ./_toolset_configuration.inc.rst
@@ -166,13 +166,14 @@ Configuration (direct connection)
               X-Scope-OrgID: "<tenant id>" # Set the X-Scope-OrgID if loki multitenancy is enabled
 
         kubernetes/logs:
-          enabled: false # Disable HolmesGPT's default logging mechanism
+          enabled: false # HolmesGPT's default logging mechanism MUST be disabled
 
 
 Advanced configuration
 ^^^^^^^^^^^^^^^^^^^^^^
 
-**Search labels**
+Search labels
+*************
 
 You can tweak the labels used by the toolset to identify kubernetes resources. This is only needed if your
 Loki logs settings for ``pod``, and ``namespace`` differ from the defaults in the example above.
@@ -223,19 +224,7 @@ Use the following commands to list Loki's labels and determine which ones to use
     curl http://localhost:3100/loki/api/v1/labels
 
 
-**Disabling the default toolset**
-
-If Loki is your primary datasource for logs, it is **advised** to disable the default HolmesGPT logging
-tool by disabling the ``kubernetes/logs`` toolset. Without this. HolmesGPT may still use kubectl to
-fetch logs instead of Loki.
-
-.. code-block:: yaml
-
-    holmes:
-        toolsets:
-            kubernetes/logs:
-                enabled: false
-
+.. include:: ./_disable_default_logging_toolset.inc.rst
 
 Capabilities
 ^^^^^^^^^^^^
@@ -248,7 +237,5 @@ Capabilities
 
    * - Tool Name
      - Description
-   * - fetch_loki_logs_for_resource
-     - Fetches the Loki logs for a given kubernetes resource
-   * - fetch_loki_logs
-     - Fetches Loki logs from any query
+   * - fetch_pod_logs
+     - Fetches pod logs

docs/configuration/holmesgpt/toolsets/grafanatempo.rst

@@ -135,9 +135,6 @@ Configuration (direct connection)
               headers:
                 X-Scope-OrgID: "<tenant id>" # Set the X-Scope-OrgID if tempo multitenancy is enabled
 
-          kubernetes/logs:
-            enabled: false # Disable HolmesGPT's default logging mechanism
-
 
     .. include:: ./_toolset_configuration.inc.rst
 
@@ -155,9 +152,6 @@ Configuration (direct connection)
             headers:
               X-Scope-OrgID: "<tenant id>" # Set the X-Scope-OrgID if tempo multitenancy is enabled
 
-        kubernetes/logs:
-          enabled: false # Disable HolmesGPT's default logging mechanism
-
 
 Advanced configuration
 ^^^^^^^^^^^^^^^^^^^^^^

docs/configuration/holmesgpt/toolsets/kubernetes.rst

@@ -6,7 +6,7 @@ Core :checkmark:`_`
 --------------------
 .. include:: ./_toolset_enabled_by_default.inc.rst
 
-By enabling this toolset, HolmesGPT will be able to describe and find kubernetes resources like
+By enabling this toolset, HolmesGPT will be able to describe and find Kubernetes resources like
 nodes, deployments, pods, etc.
 
 Configuration
@@ -90,22 +90,8 @@ Capabilities
 
    * - Tool Name
      - Description
-   * - kubectl_previous_logs
-     - Run `kubectl logs --previous` on a single Kubernetes pod. Used to fetch logs for a pod that crashed and see logs from before the crash. Never give a deployment name or a resource that is not a pod.
-   * - kubectl_previous_logs_all_containers
-     - Run `kubectl logs --previous` on a single Kubernetes pod. Used to fetch logs for a pod that crashed and see logs from before the crash.
-   * - kubectl_container_previous_logs
-     - Run `kubectl logs --previous` on a single container of a Kubernetes pod. Used to fetch logs for a pod that crashed and see logs from before the crash.
-   * - kubectl_logs
-     - Run `kubectl logs` on a single Kubernetes pod. Never give a deployment name or a resource that is not a pod.
-   * - kubectl_logs_all_containers
-     - Run `kubectl logs` on all containers within a single Kubernetes pod.
-   * - kubectl_container_logs
-     - Run `kubectl logs` on a single container within a Kubernetes pod. This is to get the logs of a specific container in a multi-container pod.
-   * - kubectl_logs_grep
-     - Search for a specific term in the logs of a single Kubernetes pod. Only provide a pod name, not a deployment or other resource.
-   * - kubectl_logs_all_containers_grep
-     - kubectl logs {{pod_name}} -n {{ namespace }} --all-containers | grep {{ search_term }}
+   * - fetch_pod_logs
+     - Fetches logs from a kubernetes pod
 
 
 Live metrics