Merge pull request #2305 from splunk/pwilliams-o11ydocs-6467

Add advanced config options for IIS apps

Author: pauljwil

gdi/get-data-in/application/otel-dotnet/get-started.rst

@@ -13,6 +13,7 @@ Instrument .NET applications for Splunk Observability Cloud (OpenTelemetry)
    Requirements <dotnet-requirements>
    Pre-checks <instrumentation/dotnet-pre-checks>
    Instrument your .NET application <instrumentation/instrument-dotnet-application>
+   Advanced configuration for IIS applications <instrumentation/advanced-config-iis-apps>
    Instrument Azure Web Apps <instrumentation/azure-webapps>
    Instrument Azure Web Jobs <instrumentation/azure-webjobs>
    Configure the .NET instrumentation <configuration/advanced-dotnet-configuration>

gdi/get-data-in/application/otel-dotnet/instrumentation/advanced-config-iis-apps.rst

@@ -0,0 +1,61 @@
+.. _advanced-config-iis-apps:
+
+*******************************************
+Advanced configuration for IIS applications
+*******************************************
+
+Follow these advanced configuration steps to make changes to specific application pools.
+
+Set environment variables
+=========================
+
+You can set environment variables for specific application pools in the ``environmentVariables`` block of the :new-page:`applicationHost.config file <https://learn.microsoft.com/en-us/iis/configuration/system.applicationhost/applicationpools/add/environmentvariables/#configuration-sample>`.
+
+For example:
+
+.. code-block:: xml
+
+    <environmentVariables>
+        <add name="OTEL_RESOURCE_ATTRIBUTES" value="deployment.environment=test,service.version=1.0.0" />
+    </environmentVariables>
+
+For all IIS applications, consider setting common environment variables for W3SVC and WAS Windows Services. For more information, see :new-page:`Instrument a Windows Service running a .NET application <https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/blob/main/docs/windows-service-instrumentation.md>` in the OpenTelemetry documentation.
+
+.. note::
+
+   If the same environment variables are set in the ``environmentVariable`` block and in the web.config ``appSettings`` block, the value in the ``environmentVariables`` block takes precedence.
+
+Activate or deactivate instrumentation
+======================================
+
+For .NET Framework applications, use the PowerShell module to activate or deactivate the instrumentation for specific application pools.
+
+#. Import the PowerShell module:
+  
+   .. code-block:: powershell
+
+      Import-Module "OpenTelemetry.DotNet.Auto.psm1"
+
+   .. note::
+
+      The application pool name is case sensitive.
+
+#. Activate or deactivate the application pool.
+
+   * Activate instrumentation for the application pool:
+
+     .. code-block:: powershell
+
+        Enable-OpenTelemetryForIISAppPool -AppPoolName <app-pool>
+
+   * Deactivate instrumentation for the application pool:
+
+     .. code-block:: powershell
+
+        Disable-OpenTelemetryForIISAppPool -AppPoolName <app-pool>
+
+#. Restart the application pool:
+
+   .. code-block:: powershell
+
+      Restart-WebAppPool -Name <app-pool>

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

@@ -238,16 +238,9 @@ Windows
 
             Start-Process "iisreset.exe" -NoNewWindow -Wait
 
-         You can also set the resource attributes for specific application pools in the ``environmentVariables`` block of the :new-page:`applicationHost.config file <https://learn.microsoft.com/en-us/iis/configuration/system.applicationhost/applicationpools/add/environmentvariables/#configuration-sample>`. For example:
-
-         .. code-block:: xml
-
-            <environmentVariables>
-               <add name="OTEL_RESOURCE_ATTRIBUTES" value="deployment.environment=test,service.version=1.0.0" />
-            </environmentVariables>
-
          .. note::
-            If the ``OTEL_SERVICE_NAME`` or ``OTEL_RESOURCE_ATTRIBUTES`` environment variables are set for a process, settings with the same names from ``appSettings`` block of web.config are ignored.
+
+            For advanced IIS application configuration options, see :ref:`advanced-config-iis-apps`.
 
       .. tab:: IIS (ASP.NET Core)
 
@@ -266,6 +259,10 @@ Windows
 
             Start-Process "iisreset.exe" -NoNewWindow -Wait
 
+         .. note::
+
+            For advanced IIS application configuration options, see :ref:`advanced-config-iis-apps`.
+
       .. tab:: Windows service
 
          For .NET Framework applications, you can configure resource attributes in the ``appSettings`` block of the app.config file.