Merge pull request #2368 from splunk/o11ydocs-6494

Clarify use of automatic discovery and instrumentation in main auto discovery section

Author: aurbiztondo-splunk

_includes/gdi/auto-discovery-intro.rst

@@ -0,0 +1,11 @@
+The Splunk Distribution of the OpenTelemetry Collector can automatically identify data sources and collect metrics and traces to send them to Splunk Observability Cloud. With automatic discovery and zero-code instrumentation you don't need to manually configure the Splunk Distribution of the OpenTelemetry Collector or your applications before deploying them: 
+
+* Automatic discovery detects and collects signal data from third-party services, such as databases and web servers. Through auto discovery the Collector automatically generates a configuration snipet that you can modify and incorporate into your existing configuration to retrieve your services' data. 
+
+* With automatic discovery you can also enable zero-code instrumentation, which allows the Collector to retrieve data from application language runtimes without having to modify the source application code or adding any new installation or configuration steps. With this option you won't have to install and configure your instrumentation agents separately. 
+
+.. caution:: 
+
+   Auto discovery of services is only available for the Collector in Linux and Kubernetes environments.
+
+   Zero-code instrumentation using the Collector's automatic discovery feature is only available for Java, Node.js, and .NET applications. If deployed independently from the Collector, zero-code instrumentation is supported for 8 back-end language runtimes. For more information, see :ref:`get-started-application`.

gdi/opentelemetry/automatic-discovery/discovery-kubernetes.rst

@@ -1,11 +1,11 @@
 .. _discovery-kubernetes:
 
 ************************************************************************
-Automatic discovery and configuration for Kubernetes
+Automatic discovery for Kubernetes
 ************************************************************************
 
 .. meta:: 
-    :description: Get started with automatic discovery and configuration for Kubernetes environments. Deploy automatic discovery to automatically find applications running in your environment and send data from them to Splunk Observability Cloud.
+    :description: Get started with automatic discovery and instrumentation for Kubernetes environments. Deploy automatic discovery and instrumentation to automatically find services and applications running in your environment and send data from them to Splunk Observability Cloud.
 
 .. toctree::
     :hidden:
@@ -15,18 +15,14 @@ Automatic discovery and configuration for Kubernetes
     Advanced customization <k8s/k8s-advanced-config>
     k8s/k8s-java-traces-tutorial/about-k8s-java-traces-tutorial
 
-Automatic discovery and configuration for Kubernetes automatically finds applications running in your Kubernetes environments and captures telemetry data from them. The Splunk Distribution of OpenTelemetry Collector receives this data and sends it to Splunk Observability Cloud.
-
-Using automatic discovery, you don't have to manually instrument or configure your applications before deploying them. 
+.. include:: /_includes/gdi/auto-discovery-intro.rst
 
 .. raw:: html
 
     <h2>Get started</h2>
 
-Automatic discovery for Kubernetes supports both back-end applications (such as Java and Node.js) as well as third-party applications (such as databases and web servers).
-
-To use automatic discovery for back-end applications, see :ref:`k8s-backend-auto-discovery`. 
+To enable the Collector's zero-code instrumentation of back-end applications written in Java, Node.js, and .NET see :ref:`k8s-backend-auto-discovery`. With this option you won't have to install and configure your instrumentation agents separately. 
 
-To use automatic discovery with third-party applications, see :ref:`k8s-third-party`.
+To use the Collector's automatic discovery of third-party applications in Kubernetes environments see :ref:`k8s-third-party`. With this option you'll only have to reuse a config file automatically generated by the Collector. 
 
-For a walkthrough of how to use automatic discovery to instrument an application in a Kubernetees environment, see :ref:`k8s-advanced-auto-discovery-config`.
+For a walkthrough of how to use automatic instrumentation to instrument an application in a Kubernetes environment, see :ref:`k8s-advanced-auto-discovery-config`.

gdi/opentelemetry/automatic-discovery/discovery-linux.rst

@@ -1,11 +1,11 @@
 .. _discovery-linux:
 
 ************************************************************************
-Automatic discovery and configuration for Linux
+Automatic discovery for Linux
 ************************************************************************
 
 .. meta:: 
-    :description: Get started with automatic discovery and configuration for Linux environments. Deploy automatic discovery to automatically find applications running in your Linux environment and send data from them to Splunk Observability Cloud.
+    :description: Get started with automatic discovery and instrumentation for Linux environments. Deploy automatic discovery and instrumentation to automatically find services and applications running in your Linux environment and send data from them to Splunk Observability Cloud.
 
 .. toctree::
     :hidden:
@@ -14,16 +14,12 @@ Automatic discovery and configuration for Linux
     Third-party applications <linux/linux-third-party>
     Advanced customization <linux/linux-advanced-config>
 
-Automatic discovery and configuration for Linux automatically finds applications running in your Linux environment and captures telemetry data from them. The Splunk Distribution of OpenTelemetry Collector receives this data and sends it to Splunk Observability Cloud.
-
-Using automatic discovery, you don't have to manually instrument or configure your applications before deploying them. 
+.. include:: /_includes/gdi/auto-discovery-intro.rst
 
 .. raw:: html
 
     <h2>Get started</h2>
 
-Automatic discovery for Linux supports both back-end applications (such as Java and Node.js) as well as third-party applications (such as databases, web servers, and message queues).
-
-To use automatic discovery for back-end applications, see :ref:`linux-backend-auto-discovery`. 
+To enable the Collector's zero-code instrumentation of back-end applications written in Java, Node.js, and .NET see :ref:`linux-backend-auto-discovery`. With this option you won't have to install and configure your instrumentation agents separately. 
 
-To use automatic discovery with third-party applications, see :ref:`linux-third-party`.
+To use the Collector's automatic discovery and configuration of third-party applications in Linux environments see :ref:`linux-third-party`. With this option you'll only have to reuse a config file automatically generated by the Collector. 

gdi/opentelemetry/automatic-discovery/discovery-windows.rst

@@ -1,25 +1,23 @@
 .. _discovery-windows:
 
 ************************************************************************
-Automatic discovery and configuration for Windows
+Automatic discovery for Windows
 ************************************************************************
 
 .. meta:: 
-    :description: Get started with automatic discovery and configuration for Windows environments. Deploy automatic discovery to automatically find applications running in your Windows environment and send data from them to Splunk Observability Cloud.
+    :description: Get started with automatic instrumentation for Windows environments. Deploy automatic instrumentation to automatically find applications running in your Windows environment and send data from them to Splunk Observability Cloud.
 
 .. toctree::
     :hidden:
 
     Language runtimes <windows/windows-backend>
 
-Automatic discovery and configuration for Windows automatically finds applications running in your Windows environment and captures telemetry data from them. The Splunk Distribution of OpenTelemetry Collector receives this data and sends it to Splunk Observability Cloud.
-
-Using automatic discovery, you don't have to manually instrument or configure your applications before deploying them. 
+.. include:: /_includes/gdi/auto-discovery-intro.rst
 
 .. raw:: html
 
     <h2>Get started</h2>
 
-Automatic discovery for Windows supports .NET language runtimes.
+The Collector for Windows does not support automatic discovery of services.
 
-To use automatic discovery for back-end applications, see :ref:`windows-backend-auto-discovery`.
+To enable the Collector's zero-code instrumentation of back-end applications written in .NET see :ref:`windows-backend-auto-discovery`. With this option you won't have to install and configure your instrumentation agents separately. 

gdi/opentelemetry/automatic-discovery/k8s/k8s-advanced-config.rst

@@ -1,13 +1,13 @@
 .. _k8s-advanced-auto-discovery-config:
 
-***********************************************************************
-Advanced customization for automatic discovery in Kubernetes
-***********************************************************************
+********************************************************************************
+Advanced customization for automatic discovery and instrumtenation in Kubernetes
+********************************************************************************
 
 .. meta:: 
-    :description: Learn how to customize your deployment of automatic discovery in a Kubernetes environment.
+    :description: Learn how to customize your deployment of automatic discovery and instrumentation in a Kubernetes environment.
 
-Learn how to customize Splunk automatic discovery and configuration for advanced scenarios. 
+Learn how to customize Splunk automatic discovery and instrumentation for advanced scenarios. 
 
 Through advanced customization, you can achieve the following tasks:
 
@@ -45,7 +45,7 @@ By default, the Splunk Distribution of OpenTelemetry Collector uses the latest v
               repository: ghcr.io/signalfx/splunk-otel-java/splunk-otel-java
               tag: v1.27.0
 
-#. Reinstall the Splunk OTel Collector Chart with the following command. Replace <CURRENT_VERSION> with the current version of your splunk-otel-collector-chart.
+#. Reinstall the Splunk OTel Collector chart with the following command. Replace <CURRENT_VERSION> with the current version of your splunk-otel-collector-chart.
 
     .. code-block:: bash
 
@@ -94,7 +94,7 @@ Follow these steps to activate Profiling for a language:
               - name: SPLUNK_PROFILER_CALL_STACK_INTERVAL
                 value: 5000
       
-#. Reinstall the Splunk OTel Collector Chart with the following command. Replace <CURRENT_VERSION> with the current version of your splunk-otel-collector-chart.
+#. Reinstall the Splunk OTel Collector chart with the following command. Replace <CURRENT_VERSION> with the current version of your splunk-otel-collector-chart.
 
     .. code-block:: bash
 
@@ -103,7 +103,7 @@ Follow these steps to activate Profiling for a language:
 Activate runtime metrics collection (Java and Node.js only)
 -------------------------------------------------------------
 
-You can activate runtime metrics collection for Java and Node.js applications running in your Kubernetes environment. To learn more about runtime metrics collection, see :
+You can activate runtime metrics collection for Java and Node.js applications running in your Kubernetes environment.
 
 Follow these steps to activate runtime metrics collection:
 
@@ -139,7 +139,7 @@ Follow these steps to activate runtime metrics collection:
           - name: SPLUNK_METRICS_ENDPOINT
             value: http://$(SPLUNK_OTEL_AGENT):9943/v2/datapoint
 
-#. Reinstall the Splunk OTel Collector Chart with the following command. Replace <CURRENT_VERSION> with the current version of your splunk-otel-collector-chart.
+#. Reinstall the Splunk OTel Collector chart with the following command. Replace <CURRENT_VERSION> with the current version of your splunk-otel-collector-chart.
 
     .. code-block:: bash
 
@@ -150,7 +150,7 @@ Follow these steps to activate runtime metrics collection:
 Use automatic discovery with gateway mode
 =======================================================
 
-The Splunk OTel Collector Chart uses the agent mode by default. Activating gateway mode deploys an instance of the OpenTelemetry Collector in a separate container, and this instance collects data from the entire cluster.
+The Splunk OTel Collector chart uses the agent mode by default. Activating gateway mode deploys an instance of the OpenTelemetry Collector in a separate container, and this instance collects data from the entire cluster.
 
 To learn more about the gateway mode, see :ref:`collector-gateway-mode`.
 
@@ -176,7 +176,7 @@ Follow these steps to send data to a gateway endpoint:
             exporter:
               endpoint: <gateway-endpoint>
 
-#. Reinstall the Splunk OTel Collector Chart with the following command. Replace <CURRENT_VERSION> with the current version of your splunk-otel-collector-chart.
+#. Reinstall the Splunk OTel Collector chart with the following command. Replace <CURRENT_VERSION> with the current version of your splunk-otel-collector-chart.
 
     .. code-block:: bash
 
@@ -207,7 +207,7 @@ Using this configuration, automatic discovery automatically sends data to a runn
 Additional settings
 ===================================
 
-There are many other settings you can customize in automatic discovery and configuration.
+There are many other settings you can customize in automatic instrumentation.
 
 For a list of settings that you can change for each language, see the following resources: