Improve Grafana/Loki/Tempo configuration docs with deployment context

docs/data-sources/builtin-toolsets/grafanaloki.md

@@ -37,33 +37,46 @@ HolmesGPT queries your self-hosted Loki through your Grafana instance's datasour
 **Find your Loki datasource UID:**
 
 ```bash
-# Port forward to Grafana
+# If Grafana isn't already reachable from where you're running this, port-forward first:
 kubectl port-forward svc/grafana 3000:80
 
-# Get Loki datasource UID
+# Otherwise, replace http://localhost:3000 with the URL Holmes will use to reach Grafana
+# (e.g. https://grafana.example.com for an ingress, or the in-cluster service URL).
 curl -s -u admin:admin http://localhost:3000/api/datasources | jq '.[] | select(.type == "loki") | .uid'
 ```
 
+Pick the `api_url` that matches where Holmes is running:
+
 ```yaml-toolset-config
 toolsets:
   grafana/loki:
     enabled: true
     config:
-      api_url: http://grafana.monitoring.svc.cluster.local  # Your Grafana URL
+      # In-cluster (Holmes running in Kubernetes):
+      api_url: http://grafana.monitoring.svc.cluster.local
+      # Out-of-cluster (Holmes CLI on a laptop, or Holmes running outside the cluster):
+      # api_url: https://grafana.example.com           # ingress / external hostname
+      # api_url: http://<external-ip-or-loadbalancer>  # external LoadBalancer
+      # api_url: http://localhost:3000                 # via `kubectl port-forward`
       api_key: <your grafana API key>
       grafana_datasource_uid: <the UID of the loki data source in Grafana>
 ```
 
 ### Self-Hosted Loki - Direct Connection
 
-HolmesGPT connects directly to a self-hosted Loki API endpoint without going through Grafana.
+HolmesGPT connects directly to a self-hosted Loki API endpoint without going through Grafana. Pick the `api_url` that matches where Holmes is running:
 
 ```yaml-toolset-config
 toolsets:
   grafana/loki:
     enabled: true
     config:
+      # In-cluster (Holmes running in Kubernetes):
       api_url: http://loki.monitoring.svc.cluster.local:3100
+      # Out-of-cluster (Holmes CLI on a laptop, or Holmes running outside the cluster):
+      # api_url: https://loki.example.com         # ingress / external hostname
+      # api_url: http://<external-ip>:3100        # external LoadBalancer
+      # api_url: http://localhost:3100            # via `kubectl port-forward svc/loki 3100:3100`
       additional_headers:
         X-Scope-OrgID: "<tenant id>"  # Only needed for multi-tenant Loki
 ```

docs/data-sources/builtin-toolsets/grafanatempo.md

@@ -39,23 +39,26 @@ See this [video](https://www.loom.com/share/f969ab3af509444693802254ab040791?sid
 **Find your Tempo datasource UID:**
 
 ```bash
-# Port forward to Grafana
+# If Grafana isn't already reachable from where you're running this, port-forward first:
 kubectl port-forward svc/robusta-grafana 3000:80
 
-# Get Tempo datasource UID
+# Otherwise, replace http://localhost:3000 with the URL Holmes will use to reach Grafana
+# (e.g. https://grafana.example.com for an ingress, or the in-cluster service URL).
 curl -s -u <username>:<password> http://localhost:3000/api/datasources | jq '.[] | select(.type == "tempo") | .uid'
 ```
 
 === "Holmes CLI"
 
-    Add the following to **~/.holmes/config.yaml**. Create the file if it doesn't exist:
+    Add the following to **~/.holmes/config.yaml**. Create the file if it doesn't exist. Use a `api_url` that's reachable from the machine running `holmes` (a laptop running the CLI typically can't resolve `*.svc.cluster.local`):
 
     ```yaml
     toolsets:
       grafana/tempo:
         enabled: true
         config:
-          api_url: <your grafana url>  # e.g. http://grafana.monitoring.svc.cluster.local
+          # Out-of-cluster (CLI on a laptop): use an ingress, external hostname, or `kubectl port-forward`
+          api_url: https://grafana.example.com
+          # api_url: http://localhost:3000  # via `kubectl port-forward svc/grafana 3000:80`
           api_key: <your grafana service account token>
           grafana_datasource_uid: <the UID of the tempo data source in Grafana>
     ```
@@ -138,14 +141,16 @@ HolmesGPT connects directly to a self-hosted Tempo API endpoint without going th
 
 === "Holmes CLI"
 
-    Add the following to **~/.holmes/config.yaml**. Create the file if it doesn't exist:
+    Add the following to **~/.holmes/config.yaml**. Create the file if it doesn't exist. Use a `api_url` that's reachable from the machine running `holmes` (a laptop running the CLI typically can't resolve `*.svc.cluster.local`):
 
     ```yaml
     toolsets:
       grafana/tempo:
         enabled: true
         config:
-          api_url: http://tempo.monitoring.svc.cluster.local:3200
+          # Out-of-cluster (CLI on a laptop): use an ingress, external hostname, or `kubectl port-forward`
+          api_url: https://tempo.example.com
+          # api_url: http://localhost:3200  # via `kubectl port-forward svc/tempo 3200:3200`
           additional_headers:
             X-Scope-OrgID: "<tenant id>"  # Only needed for multi-tenant Tempo
     ```