diff --git a/.cspell/dot-net.txt b/.cspell/dot-net.txt index 6970f20a1e..dcdd2541f6 100644 --- a/.cspell/dot-net.txt +++ b/.cspell/dot-net.txt @@ -32,3 +32,4 @@ ASPNETCORE HOSTINGSTARTUPASSEMBLIES Bootstrapper NETFX +iisreset diff --git a/docs/README.md b/docs/README.md index 81af7fa4d7..f25a6b6d2f 100644 --- a/docs/README.md +++ b/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 diff --git a/docs/config.md b/docs/config.md index 59c2988ebc..35c8206acc 100644 --- a/docs/config.md +++ b/docs/config.md @@ -36,6 +36,12 @@ with environment variables taking precedence over `App.config` or `Web.config` f ``` +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 | diff --git a/docs/iis-instrumentation.md b/docs/iis-instrumentation.md index 6689356e57..d09cb8c562 100644 --- a/docs/iis-instrumentation.md +++ b/docs/iis-instrumentation.md @@ -1,27 +1,24 @@ # Instrument an ASP.NET application deployed on IIS -## Set environment variables +## Setup -You can add the [``](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 [``](https://docs.microsoft.com/en-us/aspnet/core/host-and-deploy/iis/web-config#set-environment-variables) -elements inside the `` 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: ``` -## 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 [``](https://docs.microsoft.com/en-us/aspnet/core/host-and-deploy/iis/web-config#set-environment-variables) +elements inside the `` block of your `Web.config` file +to set configuration via environment variables. + +### Advanced configuration + +You can add the [``](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). diff --git a/docs/windows-service-instrumentation.md b/docs/windows-service-instrumentation.md index 2228d12935..fa0b990918 100644 --- a/docs/windows-service-instrumentation.md +++ b/docs/windows-service-instrumentation.md @@ -1,12 +1,34 @@ # 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: @@ -14,7 +36,7 @@ The registry key of a given Windows Service (named `$svcName`) is located under: 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: @@ -22,28 +44,3 @@ in the following format: 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 -```