docs: improve documentation about o11y (#1265)

* docs: change documentation about o11y

* docs: fix splunk requirements for docker compose

Author: omrozowicz-splunk

charts/splunk-connect-for-snmp/values.yaml

@@ -107,8 +107,9 @@ sim:
   # Enables sending data to Splunk Observability/SignalFx.
 
   # WARNING:
-  # The Splunk Observability Cloud integration (`sim`) is experimental. Effective use depends on well‑curated SNMP profiles whose metric names, types, and dimensions align with Splunk Observability data model expectations. Profiles not tailored may produce superfluous metrics. Validate and refine profiles in controlled environments before enabling sim.enabled: true for broader use; otherwise keep it disabled. Future releases may change configuration behavior.
-  # In order to use it, you must set `enabled` flag in `values.yaml` to `true`
+  # The Splunk Observability Cloud integration (sim) uses the Splunk OpenTelemetry Collector as an additional component in our pipeline. In this setup, the collector transforms metrics received via Splunk HEC into the SignalFx format for ingestion into Splunk Observability Cloud.
+  # Because this path is primarily a transformation layer rather than a native O11y instrumentation, the resulting metrics may not fully match Splunk Observability Cloud’s data model, naming conventions, or recommended dimensions.
+  # We recommend validating output carefully in a controlled environment before enabling sim.enabled: true broadly, and adjusting SNMP profiles or transformation rules to ensure consistency.
   enabled: false
   # Splunk Observability org access token.
   # Required for Splunk Observability (if `realm` is specified).

docs/dashboard.md

@@ -21,7 +21,7 @@ show the status of SC4SNMP tasks.
 !!! info
     Dashboard is compatible starting from version **1.11.0** and requires the `logLevel` set at least to **INFO**.
 
-1. [Create metrics index](splunk-requirements.md#requirements-for-splunk-enterprise-or-enterprise-cloud) in Splunk.
+1. [Create metrics index](dockercompose/0-splunk-requirements.md#requirements-for-splunk-enterprise-or-enterprise-cloud) in Splunk.
 2. Enable metrics logging for your runtime:
     * For Kubernetes install [Splunk OpenTelemetry Collector for K8S](microk8s/sck-installation.md)
     * For Docker Compose use [Splunk logging driver for docker](dockercompose/9-splunk-logging.md)

docs/splunk-requirements.md …s/dockercompose/0-splunk-requirements.mddocs/splunk-requirements.md renamed to docs/dockercompose/0-splunk-requirements.md docs/splunk-requirements.md renamed to docs/dockercompose/0-splunk-requirements.md

@@ -14,19 +14,9 @@ See the following prerequisites for the Splunk Connect for SNMP.
        * netops (event type)
 
 > **_Note:_** `netmetrics` and `netops` are the default names of SC4SNMP indexes. You can use the index names of your choice and
-> reference it in the `values.yaml` file later on. See [SC4SNMP Parameters](microk8s/sc4snmp-installation.md#configure-splunk-enterprise-or-splunk-cloud-connection) for details.
+> reference it in the `.env` file later on. See [SC4SNMP Parameters](6-env-file-configuration.md#splunk-instance) for details.
 
 2. Create or obtain a new Splunk HTTP Event Collector token and the correct HTTPS endpoint.
 3. Verify the token using [curl](https://docs.splunk.com/Documentation/Splunk/8.1.3/Data/FormateventsforHTTPEventCollector). The endpoint must use a publicly trusted certificate authority.
 4. Use the shared IP address for SNMP traps. Simple and POC deployments will use the same IP address as the host server. For an HA deployment, use the management interface and the IP address of each cluster member. 
-5. Obtain the IP address of an internal DNS server that can resolve the Splunk Endpoint.
-
-### Requirements for Splunk Infrastructure Monitoring
-
-!!!warning 
-    The Splunk Observability Cloud integration is experimental. Effective use depends on well‑curated SNMP profiles whose metric names, types, and dimensions align with Splunk Observability data model expectations. Profiles not tailored may produce superfluous metrics. Future releases may change configuration behavior.
-
-Obtain the following from your Splunk Observability Cloud environment:
-
-1. Realm
-2. Token
+5. Obtain the IP address of an internal DNS server that can resolve the Splunk Endpoint.

docs/dockercompose/6-env-file-configuration.md

@@ -62,6 +62,7 @@ Inside the directory with the docker compose files, there is a `.env`. Variables
 | `SPLUNK_METRIC_NAME_HYPHEN_TO_UNDERSCORE` | Replaces hyphens with underscores in generated metric names to ensure compatibility with Splunk's metric schema                       |
 | `IGNORE_EMPTY_VARBINDS`                   | Details can be found in [empty snmp response message issue](../troubleshooting/polling-issues.md#empty-snmp-response-message-problem) |
 | `SPLUNK_LOG_INDEX`                        | Event index in Splunk where logs from docker containers would be sent                                                                 |
+
 ## Workers
 
 ### General

docs/microk8s/configuration/sim-configuration.md

@@ -1,8 +1,9 @@
 # OTEL and Splunk Observability Cloud configuration
 
-!!!warning 
-    The Splunk Observability Cloud integration (`sim`) is experimental. Effective use depends on well‑curated SNMP profiles whose metric names, types, and dimensions align with Splunk Observability data model expectations. Profiles not tailored may produce superfluous metrics. Validate and refine profiles in controlled environments before enabling sim.enabled: true for broader use; otherwise keep it disabled. Future releases may change configuration behavior.
-    Splunk OpenTelemetry Collector is a component that provides an option to send metrics to Splunk Observability Cloud.
+!!! warning 
+    The Splunk Observability Cloud integration (sim) uses the Splunk OpenTelemetry Collector as an additional component in our pipeline. In this setup, the collector transforms metrics received via Splunk HEC into the SignalFx format for ingestion into Splunk Observability Cloud.
+    Because this path is primarily a transformation layer rather than a native O11y instrumentation, the resulting metrics may not fully match Splunk Observability Cloud’s data model, naming conventions, or recommended dimensions.
+    We recommend validating output carefully in a controlled environment before enabling sim.enabled: true broadly, and adjusting SNMP profiles or transformation rules to ensure consistency.
 
 ```yaml
 sim:

docs/microk8s/configuration/values-params-description.md

@@ -48,8 +48,9 @@ Detailed documentation about configuring UI can be found in [Enable GUI](../gui/
 Detailed documentation about configuring sim can be found in [Splunk Infrastructure Monitoring](sim-configuration.md).
 
 !!!warning 
-    The Splunk Observability Cloud integration (`sim`) is experimental. Effective use depends on well‑curated SNMP profiles whose metric names, types, and dimensions align with Splunk Observability data model expectations. Profiles not tailored may produce superfluous metrics. Validate and refine profiles in controlled environments before enabling sim.enabled: true for broader use; otherwise keep it disabled. Future releases may change configuration behavior.
-    Splunk OpenTelemetry Collector is a component that provides an option to send metrics to Splunk Observability Cloud.
+  The Splunk Observability Cloud integration (sim) uses the Splunk OpenTelemetry Collector as an additional component in our pipeline. In this setup, the collector transforms metrics received via Splunk HEC into the SignalFx format for ingestion into Splunk Observability Cloud.
+  Because this path is primarily a transformation layer rather than a native O11y instrumentation, the resulting metrics may not fully match Splunk Observability Cloud’s data model, naming conventions, or recommended dimensions.
+  We recommend validating output carefully in a controlled environment before enabling sim.enabled: true broadly, and adjusting SNMP profiles or transformation rules to ensure consistency.
 
 
 | Variable                                        | Description                                                                                                                     | Default |

docs/microk8s/splunk-requirements.md

@@ -0,0 +1,34 @@
+# Prerequisites for the Splunk Connect for SNMP
+
+See the following prerequisites for the Splunk Connect for SNMP.
+
+### Requirements for Splunk Enterprise or Enterprise Cloud
+
+1. Manually create the following indexes in Splunk:
+   
+   * Indexes to store Splunk Connect for SNMP logs and metrics: 
+       * em_metrics (metrics type)
+       * em_logs (event type)
+   * Destination indexes for forwarding SNMP data: 
+       * netmetrics (metrics type)
+       * netops (event type)
+   
+> **_Note:_** `netmetrics` and `netops` are the default names of SC4SNMP indexes. You can use the index names of your choice and
+> reference it in the `values.yaml` file later on. See [SC4SNMP Parameters](../microk8s/sc4snmp-installation.md#configure-splunk-enterprise-or-splunk-cloud-connection) for details.
+
+2. Create or obtain a new Splunk HTTP Event Collector token and the correct HTTPS endpoint.
+3. Verify the token using [curl](https://docs.splunk.com/Documentation/Splunk/8.1.3/Data/FormateventsforHTTPEventCollector). The endpoint must use a publicly trusted certificate authority.
+4. Use the shared IP address for SNMP traps. Simple and POC deployments will use the same IP address as the host server. For an HA deployment, use the management interface and the IP address of each cluster member. 
+5. Obtain the IP address of an internal DNS server that can resolve the Splunk Endpoint.
+
+### Requirements for Splunk Infrastructure Monitoring
+
+!!! warning 
+    The Splunk Observability Cloud integration (sim) uses the Splunk OpenTelemetry Collector as an additional component in our pipeline. In this setup, the collector transforms metrics received via Splunk HEC into the SignalFx format for ingestion into Splunk Observability Cloud.
+    Because this path is primarily a transformation layer rather than a native O11y instrumentation, the resulting metrics may not fully match Splunk Observability Cloud’s data model, naming conventions, or recommended dimensions.
+    We recommend validating output carefully in a controlled environment before enabling sim.enabled: true broadly, and adjusting SNMP profiles or transformation rules to ensure consistency.
+
+Obtain the following from your Splunk Observability Cloud environment:
+
+1. Realm
+2. Token

mkdocs.yml

@@ -45,7 +45,7 @@ nav:
       - High-level design: "architecture/design.md"
       - Infrastructure Planning: "architecture/planning.md"
   - Getting Started with Docker Compose:
-      - Splunk Requirements: "splunk-requirements.md"
+      - Splunk Requirements: "dockercompose/0-splunk-requirements.md"
       - Install Docker: "dockercompose/1-install-docker.md"
       - Download package: "dockercompose/2-download-package.md"
       - Inventory configuration: "dockercompose/3-inventory-configuration.md"
@@ -58,7 +58,7 @@ nav:
       - Enable IPv6: "dockercompose/10-enable-ipv6.md"
   - Getting Started with Microk8s:
       - Installation:
-        - Splunk Requirements: "splunk-requirements.md"
+        - Splunk Requirements: "microk8s/splunk-requirements.md"
         - Platform Microk8s: "microk8s/mk8s/k8s-microk8s.md"
         - Install Splunk OpenTelemetry Collector for Kubernetes: "microk8s/sck-installation.md"
         - Install SC4SNMP: "microk8s/sc4snmp-installation.md"