Recommend NuGet packages

Author: pauljwil

gdi/get-data-in/application/otel-dotnet/instrumentation/instrument-dotnet-application.rst

@@ -9,10 +9,92 @@ Instrument your .NET application for Splunk Observability Cloud (OpenTelemetry)
 
 The Splunk Distribution of OpenTelemetry .NET automatically instruments .NET applications, Windows services running .NET applications, and ASP.NET applications deployed on IIS.
 
-To get started, use the guided setup, follow the instructions manually, or automatically instrument your application. See :ref:`discovery_mode` for more information.
+You can install the .NET instrumentation using the NuGet packages, a guided setup, or manual instructions. The NuGet packages are the best method for avoiding dependency version conflicts, but are not well-suited for instrumenting multiple applications running on the same machine. Review the various installation methods on this page to identify the best method for your application environment.
+
+To learn about automatic discovery, see :ref:`discovery_mode`.
+
+.. _otel-dotnet-nuget-pkg:
+
+Install the OpenTelemetry .NET instrumentation using the NuGet packages
+=======================================================================
+
+You can deploy the Splunk Distribution of OpenTelemetry .NET instrumentation automatically through the official NuGet packages. Your instrumented application project must support NuGet packages.
+
+The following scenarios are ideal for using the NuGet packages:
+
+* You control the application build but not the machine or container where the application is running.
+* You're instrumenting a self-contained application. See :new-page:`Publish self-contained <https://learn.microsoft.com/en-us/dotnet/core/deploying/#publish-self-contained>` in the .NET documentation.
+* You want to facilitate developer experimentation with automatic instrumentation through NuGet packages.
+* You need to solve version conflicts between the dependencies used by the application and the automatic instrumentation.
+
+However, you shouldn't use the NuGet packages if any of the following apply to your scenario:
+
+* You're unable to add the NuGet packages to the application project. This can be the case when instrumenting a third-party application.
+* You can't accommodate the increased disk use required by installing the NuGet packages separately for each instrumented application running on the same machine. 
+* You need to instrument a legacy application that can't be migrated to the SDK-style project. To verify whether your project is SDK style, see `Identify the project format <https://learn.microsoft.com/en-us/nuget/resources/check-project-format>`__ in the NuGet documentation.
+
+.. note::
+
+   For advanced configuration of the .NET automatic instrumentation, such as changing trace propagation formats or changing the endpoint URLs, see :ref:`advanced-dotnet-otel-configuration`.
+
+Instrument your application using the NuGet packages
+----------------------------------------------------
+
+To automatically instrument your application using the NuGet packages, add the ``Splunk.OpenTelemetry.AutoInstrumentation`` package to your project.
+
+#. In a terminal, navigate to the root directory of your .NET application.
+
+#. Add the NuGet packages using the following command, replacing ``<project>`` with the ``.csproj`` file name:
+
+   .. code-block:: powershell
+
+      dotnet add <project> package Splunk.OpenTelemetry.AutoInstrumentation --prerelease
+
+If the build fails and prompts you to add missing instrumentation packages, add the instrumentation package or skip the instrumentation of the listed package by adding it to the ``SkippedInstrumentation`` property. For example:
+
+.. code-block:: xml
+
+   <PropertyGroup>
+      <SkippedInstrumentations>MongoDB.Driver.Core;StackExchange.Redis</SkippedInstrumentations>
+   </PropertyGroup>
+
+Alternatively, you can set the ``SkippedInstrumentation`` property from the terminal. Rewrite the ``;`` separator as ``%3B``. For example:
+
+.. code-block:: powershell
+
+   dotnet build -p:SkippedInstrumentations=StackExchange.Redis%3BMongoDB.Driver.Core
+
+To distribute the appropriate native runtime components with your .NET application, specify a Runtime Identifier (RID) to build the application using ``dotnet build`` or ``dotnet publish``.
+
+Both self-contained and framework-dependent applications are compatible with automatic instrumentation. See :new-page:`.NET application publishing overview <https://learn.microsoft.com/en-us/dotnet/core/deploying/>` in the .NET documentation for more information.
+
+Run the instrumented application
+--------------------------------
+
+The instrumentation procedure in the previous section produces launch scripts in the output folder of the build. The Windows script is ``splunk-launch.cmd`` and the Linux script is ``splunk-launch.sh``. The script passes all the command-line parameters that you provide to the application. Use the following steps to run your instrumented application:
+
+#. Identify the launch script in your build output.
+
+#. Optional. If you want to verify that the instrumentation is working by viewing the telemetry data output in your console, set the following environment variables to ``true``:
+
+   * ``OTEL_DOTNET_AUTO_TRACES_CONSOLE_EXPORTER_ENABLED``
+   * ``OTEL_DOTNET_AUTO_METRICS_CONSOLE_EXPORTER_ENABLED``
+   * ``OTEL_DOTNET_AUTO_LOGS_CONSOLE_EXPORTER_ENABLED``
+
+#. Run the instrumented application using the launch script:
+
+   * Using the executable:
+
+     - Windows: ``splunk-launch.cmd <application_executable>``.
+     - Linux: ``splunk-launch.sh <application_executable>``.
+
+   * Using the ``dotnet`` CLI:
+
+     - Windows: ``splunk-launch.cmd dotnet <application>``.
+     - Linux: ``splunk-launch.sh dotnet <application>``.
 
 Generate customized instructions using the guided setup
-====================================================================
+=======================================================
 
 To generate all the basic installation commands for your environment and application, use the .NET OpenTelemetry guided setup. To access the .NET OpenTelemetry guided setup, follow these steps:
 
@@ -26,7 +108,7 @@ To generate all the basic installation commands for your environment and applica
    #. Select the :guilabel:`.NET (OpenTelemetry)` tile to open the .NET OpenTelemetry guided setup.
 
 Install the Splunk Distribution of OpenTelemetry .NET manually
-==================================================================
+==============================================================
 
 If you don't use the guided setup, follow these instructions to manually install the Splunk Distribution of OpenTelemetry .NET:
 
@@ -38,7 +120,7 @@ To install the distribution using the official NuGet packages, see :ref:`otel-do
 .. _install-dotnet-otel-instrumentation:
 
 Instrument your .NET application
----------------------------------------------
+--------------------------------
 
 Use the following steps to automatically instrument your application.
 
@@ -52,7 +134,7 @@ Use the following steps to automatically instrument your application.
    * ``DOTNET_EnableDiagnostics_Debugger=0``
 
 Windows
-^^^^^^^^^^^^
+^^^^^^^
 
 #. Check that you meet the requirements. See :ref:`dotnet-otel-requirements`.
 
@@ -180,7 +262,7 @@ If no data appears in APM, see :ref:`common-dotnet-otel-troubleshooting`.
 .. note:: If you need to add custom attributes to spans or want to manually generate spans and metrics, instrument your .NET application or service manually. See :ref:`dotnet-otel-manual-instrumentation`.
 
 Linux
-^^^^^^^^^^^^^^^^^
+^^^^^
 
 #. Check that you meet the requirements. See :ref:`dotnet-otel-requirements`.
 
@@ -216,7 +298,7 @@ If no data appears in APM, see :ref:`common-dotnet-otel-troubleshooting`.
 .. _activate-profiling-dotnet-otel:
 
 Activate AlwaysOn Profiling
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 To activate AlwaysOn Profiling, set the ``SPLUNK_PROFILER_ENABLED`` environment variable to ``true``.
 
@@ -238,64 +320,6 @@ Starting from version 1.4.0, the .NET OTel instrumentation collects database que
 
 SQL statements might contain sensitive information. To configure this behavior, see ``OTEL_DOTNET_AUTO_SQLCLIENT_SET_DBSTATEMENT_FOR_TEXT`` and ``OTEL_DOTNET_AUTO_ENTITYFRAMEWORKCORE_SET_DBSTATEMENT_FOR_TEXT`` in :ref:`dotnet-otel-instrumentation-settings`.
 
-
-.. _otel-dotnet-nuget-pkg:
-
-Install the OpenTelemetry .NET instrumentation using the NuGet packages
---------------------------------------------------------------------------
-
-You can deploy the Splunk Distribution of OpenTelemetry .NET instrumentation automatically through the official NuGet packages. The project of your instrumented application must support NuGet packages.
-
-Use the NuGet package in the following scenarios:
-
-1. You control the application build but not the machine or container where the application is running.
-2. You're instrumenting a self-contained application. See :new-page:`Publish self-contained <https://learn.microsoft.com/en-us/dotnet/core/deploying/#publish-self-contained>` in the .NET documentation.
-3. You want to facilitate developer experimentation with automatic instrumentation through NuGet packages.
-4. You need to solve version conflicts between the dependencies used by the application and the automatic instrumentation.
-
-Instrument your application using the NuGet packages
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-To automatically instrument your application using the NuGet packages, add the ``Splunk.OpenTelemetry.AutoInstrumentation`` package to your project. For example:
-
-.. code-block:: powershell
-
-   dotnet add [<PROJECT>] package Splunk.OpenTelemetry.AutoInstrumentation --prerelease
-
-If the build fails and prompts you to add missing instrumentation packages, add the instrumentation package or skip the instrumentation of the listed package by adding it to the ``SkippedInstrumentation`` property. For example:
-
-.. code-block:: xml
-
-   <PropertyGroup>
-      <SkippedInstrumentations>MongoDB.Driver.Core;StackExchange.Redis</SkippedInstrumentations>
-   </PropertyGroup>
-
-You can also set the ``SkippedInstrumentation`` property from the terminal. Rewrite the ``;`` separator as ``%3B``. For example:
-
-.. code-block:: powershell
-
-   dotnet build -p:SkippedInstrumentations=StackExchange.Redis%3BMongoDB.Driver.Core
-
-To distribute the appropriate native runtime components with your .NET application, specify a Runtime Identifier (RID) to build the application using ``dotnet build`` or ``dotnet publish``.
-
-Both self-contained and framework-dependent applications are compatible with automatic instrumentation. See :new-page:`.NET application publishing overview <https://learn.microsoft.com/en-us/dotnet/core/deploying/>` in the .NET documentation for more information.
-
-Run the instrumented application
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Use the script in the output folder of the build to run the application with automatic instrumentation activated.
-
-- On Windows, use ``splunk-launch.cmd <application_executable>``.
-- On Linux, use ``splunk-launch.sh <application_executable>``.
-
-If you run the application using the ``dotnet`` CLI, add ``dotnet`` after the script.
-
-- On Windows, use ``splunk-launch.cmd dotnet <application>``.
-- On Linux, use ``splunk-launch.sh dotnet <application>``.
-
-The script passes all the command-line parameters you provide to the application.
-
-
 .. _docker-install-otel-dotnet:
 
 Instrument an application running within a Docker container