Refine setup and configuration docs (#2082)

.cspell/dot-net.txt

@@ -32,3 +32,4 @@ ASPNETCORE
 HOSTINGSTARTUPASSEMBLIES
 Bootstrapper
 NETFX
+iisreset

docs/README.md

@@ -118,9 +118,16 @@ and instrument your .NET application using the provided Shell scripts.
 Example usage:
 
 ```sh
+# Download the bash script
 curl -sSfL https://raw.githubusercontent.com/open-telemetry/opentelemetry-dotnet-instrumentation/v0.5.1-beta.3/otel-dotnet-auto-install.sh -O
+
+# Install core files
 sh ./otel-dotnet-auto-install.sh
+
+# Setup the instrumentation for the current shell session
 . $HOME/.otel-dotnet-auto/instrument.sh
+
+# Run your application with instrumentation
 OTEL_SERVICE_NAME=myapp OTEL_RESOURCE_ATTRIBUTES=deployment.environment=staging,service.version=1.0.0 dotnet run
 ```
 
@@ -152,27 +159,27 @@ and instrument your .NET application using the provided PowerShell module.
 Example usage (run as administrator):
 
 ```powershell
-# Download and import the module
+# Download the module
 $module_url = "https://raw.githubusercontent.com/open-telemetry/opentelemetry-dotnet-instrumentation/v0.5.1-beta.3/OpenTelemetry.DotNet.Auto.psm1"
 $download_path = Join-Path $env:temp "OpenTelemetry.DotNet.Auto.psm1"
 Invoke-WebRequest -Uri $module_url -OutFile $download_path
+
+# Import the module to use its functions
 Import-Module $download_path
 
 # Install core files
 Install-OpenTelemetryCore
 
-# Setup IIS instrumentation
-Register-OpenTelemetryForIIS
-
-# Setup your Windows Service instrumentation
-Register-OpenTelemetryForWindowsService -WindowsServiceName "MyServiceName" -OTelServiceName "MyServiceDisplayName"
-
-# Setup environment to start instrumentation from the current PowerShell session
+# Set up the instrumentation for the current PowerShell session
 Register-OpenTelemetryForCurrentSession -OTelServiceName "MyServiceDisplayName"
 
-# Get current installation location
-Get-OpenTelemetryInstallDirectory
+# Run your application with instrumentation
+.\MyNetApp.exe
+```
+
+You can get usage information by calling:
 
+```powershell
 # List all available commands
 Get-Command -Module OpenTelemetry.DotNet.Auto
 
@@ -183,8 +190,6 @@ Get-Help Install-OpenTelemetryCore -Detailed
 ⚠️ The PowerShell module works only on PowerShell 5.1
 which is the one installed by default on Windows.
 
-⚠️ Register for IIS and Windows Service performs a service restart.
-
 ## Instrument a container
 
 You can find our demonstrative example

docs/config.md

@@ -36,6 +36,12 @@ with environment variables taking precedence over `App.config` or `Web.config` f
     </configuration>
     ```
 
+By default we recommend using environment variables for configuration.
+However, if given setting supports it, then:
+
+- use `Web.config` for configuring an ASP.NET application (.NET Framework),
+- use `App.config` for configuring a Windows Service (.NET Framework).
+
 ## Global settings
 
 | Environment variable                 | Description                                                                                                                                                                                                                  | Default value |

docs/iis-instrumentation.md

@@ -1,27 +1,24 @@
 # Instrument an ASP.NET application deployed on IIS
 
-## Set environment variables
+## Setup
 
-You can add the [`<environmentVariables>`](https://docs.microsoft.com/en-us/iis/configuration/system.applicationhost/applicationpools/add/environmentvariables/)
-in `applicationHost.config`
-to set environment variables for given application pools.
+Use the `OpenTelemetry.DotNet.Auto.psm1"` PowerShell module
+to set up automatic instrumentation for IIS:
 
-> For IIS versions older than 10.0, you can consider creating a distinct user,
-  set its environment variables
-  and use it as the application pool user.
+```powershell
+# Import the module
+Import-Module "OpenTelemetry.DotNet.Auto.psm1"
 
-For ASP.NET Core application you can also use
-the [`<environmentVariable>`](https://docs.microsoft.com/en-us/aspnet/core/host-and-deploy/iis/web-config#set-environment-variables)
-elements inside the `<aspNetCore>` block of your `Web.config` file
-to set environment variables.
+# Install core files
+Install-OpenTelemetryCore
 
-You can consider setting common environment variables,
-such us `COR_PROFILER`,
-for all application deployed to IIS
-by setting the environment variables for
-`W3SVC` and `WAS` Windows Services as described in [windows-service-instrumentation.md](windows-service-instrumentation.md).
+# Setup IIS instrumentation
+Register-OpenTelemetryForIIS
+```
 
-## Add TelemetryHttpModule ASP.NET HTTP module
+⚠️ `Register-OpenTelemetryForIIS` performs IIS restart.
+
+### Add TelemetryHttpModule ASP.NET HTTP module
 
 > This is NOT required for ASP.NET Core deployments.
 
@@ -63,7 +60,30 @@ to set it for all ASP.NET application running in Integrated Pipeline Mode:
   </location>
 ```
 
-## Enable ASP.NET instrumentation
+## Configuration
+
+> Remember to restart IIS after making configuration changes.
+> You can do it by executing `iisreset.exe`.
+
+For ASP.NET application you can configure the most common `OTEL_` settings
+(like `OTEL_SERVICE_NAME`) via `appSettings` in `Web.config`.
 
-Make sure to enable the ASP.NET instrumentation by setting
-`OTEL_DOTNET_AUTO_TRACES_ENABLED_INSTRUMENTATIONS=AspNet`.
+For ASP.NET Core application you can use
+the [`<environmentVariable>`](https://docs.microsoft.com/en-us/aspnet/core/host-and-deploy/iis/web-config#set-environment-variables)
+elements inside the `<aspNetCore>` block of your `Web.config` file
+to set configuration via environment variables.
+
+### Advanced configuration
+
+You can add the [`<environmentVariables>`](https://docs.microsoft.com/en-us/iis/configuration/system.applicationhost/applicationpools/add/environmentvariables/)
+in `applicationHost.config`
+to set environment variables for given application pools.
+
+> For IIS versions older than 10.0, you can consider creating a distinct user,
+  set its environment variables
+  and use it as the application pool user.
+
+Consider setting common environment variables,
+for all applications deployed to IIS
+by setting the environment variables for
+`W3SVC` and `WAS` Windows Services as described in [windows-service-instrumentation.md](windows-service-instrumentation.md).

docs/windows-service-instrumentation.md

@@ -1,49 +1,46 @@
 # Instrument a Windows Service running a .NET application
 
-We recommend setting environment variables for a Windows Service
-using the Windows Registry.
+## Setup
 
-> Remember to restart the Windows Service
-  after making changes to its configuration.
+Use the `OpenTelemetry.DotNet.Auto.psm1"` PowerShell module
+to set up automatic instrumentation for a Windows Service:
 
-## Set environment variables for a Windows Service
+```powershell
+# Import the module
+Import-Module "OpenTelemetry.DotNet.Auto.psm1"
+
+# Install core files
+Install-OpenTelemetryCore
+
+# Set up your Windows Service instrumentation
+Register-OpenTelemetryForWindowsService -WindowsServiceName "WindowsServiceName" -OTelServiceName "MyServiceDisplayName"
+```
+
+⚠️ `Register-OpenTelemetryForWindowsService` performs a service restart.
+
+## Configuration
+
+> Remember to restart the Windows Service after making configuration changes.
+> You can do it by executing
+> `Restart-Service -Name $WindowsServiceName -Force` in PowerShell.
+
+For .NET Framework applications you can configure the most common `OTEL_` settings
+(like `OTEL_RESOURCE_ATTRIBUTES`) via `appSettings` in `Web.config`.
+
+The alternative is to set environment variables for the Windows Service
+in the Windows Registry.
 
 The registry key of a given Windows Service (named `$svcName`) is located under:
 
 ```powershell
 HKLM\SYSTEM\CurrentControlSet\Services\$svcName
 ```
 
-The environment variables can be defined
+The environment variables are defined
 in a `REG_MULTI_SZ` (multiline registry value) called `Environment`
 in the following format:
 
 ```env
 Var1=Value1
 Var2=Value2
 ```
-
-Below is an example demonstrating how instrumentation can be configured
-in PowerShell (run as administrator):
-
-```powershell
-$installationLocation = "C:\some\dir" # The path where you put the OTel .NET AutoInstrumentation binaries
-$svcName = "MySrv"    # The name of the Windows Service
-[string[]] $vars = @(
-   "COR_ENABLE_PROFILING=1",
-   "COR_PROFILER={918728DD-259F-4A6A-AC2B-B85E1B658318}",
-   "COR_PROFILER_PATH_64=$installationLocation\win-x64\OpenTelemetry.AutoInstrumentation.Native.dll",
-   "COR_PROFILER_PATH_32=$installationLocation\win-x86\OpenTelemetry.AutoInstrumentation.Native.dll",
-   "CORECLR_ENABLE_PROFILING=1",
-   "CORECLR_PROFILER={918728DD-259F-4A6A-AC2B-B85E1B658318}",
-   "CORECLR_PROFILER_PATH_64=$installationLocation\win-x64\OpenTelemetry.AutoInstrumentation.Native.dll",
-   "CORECLR_PROFILER_PATH_32=$installationLocation\win-x86\OpenTelemetry.AutoInstrumentation.Native.dll",
-   "DOTNET_ADDITIONAL_DEPS=$installationLocation\AdditionalDeps",
-   "DOTNET_SHARED_STORE=$installationLocation\store",
-   "DOTNET_STARTUP_HOOKS=$installationLocation\net\OpenTelemetry.AutoInstrumentation.StartupHook.dll",
-   "OTEL_DOTNET_AUTO_HOME=$installationLocation",
-   "OTEL_DOTNET_AUTO_INTEGRATIONS_FILE=$installationLocation\integrations.json",
-   "OTEL_SERVICE_NAME=my-service-name"
-)
-Set-ItemProperty HKLM:SYSTEM\CurrentControlSet\Services\$svcName -Name Environment -Value $vars
-```