From 5cf78c9cb3190ffeb74579620090c4d5355e24e6 Mon Sep 17 00:00:00 2001 From: Steve Gordon Date: Mon, 23 Oct 2023 13:04:01 +0100 Subject: [PATCH 1/3] Update auto intrumentation docs --- docs/setup-auto-instrumentation.asciidoc | 81 ++++++++++++++++++------ 1 file changed, 61 insertions(+), 20 deletions(-) diff --git a/docs/setup-auto-instrumentation.asciidoc b/docs/setup-auto-instrumentation.asciidoc index 9558ebdc2..8d909c307 100644 --- a/docs/setup-auto-instrumentation.asciidoc +++ b/docs/setup-auto-instrumentation.asciidoc @@ -31,10 +31,9 @@ This approach works with the following .NET 5+ |=== -NOTE: The Profiler based agent only supports 64 bit applications. 32 bit applications aren't supported. +NOTE: The Profiler based agent only supports 64-bit applications. 32-bit applications aren't supported. - -It instruments the following assemblies +It instruments the following assemblies: include::integrations.asciidoc[] @@ -60,7 +59,7 @@ See <> for configuration for common deplo . Download the `elastic_apm_profiler_.zip` file from the https://github.com/elastic/apm-agent-dotnet/releases[Releases] page of the .NET APM Agent GitHub repository, where `` is the version number to download. You can find the file under Assets. . Unzip the zip file into a folder on the host that is hosting the application to instrument. -. Configure the following environment variables +. Configure the following environment variables: + .{dot}NET Framework [source,sh] @@ -70,9 +69,14 @@ set COR_PROFILER = "{FA65FE15-F085-4681-9B20-95E04F6C03CC}" set COR_PROFILER_PATH = "\elastic_apm_profiler.dll" <1> set ELASTIC_APM_PROFILER_HOME = "" set ELASTIC_APM_PROFILER_INTEGRATIONS = "\integrations.yml" +set ELASTIC_APM_SERVER_URL = "" <2> +set ELASTIC_APM_SECRET_TOKEN = "" <3> ---- <1> `` is the directory to which the zip file was unzipped in step 2. +<2> The URL of the APM server intake to which traces and metrics should be sent. +<3> The https://www.elastic.co/guide/en/apm/guide/current/secret-token.html[secret token] +used by the APM Agent to authenticate with APM server. + .{dot}NET Core / .NET 5+ on Windows [source,sh] @@ -82,9 +86,14 @@ set CORECLR_PROFILER = "{FA65FE15-F085-4681-9B20-95E04F6C03CC}" set CORECLR_PROFILER_PATH = "\elastic_apm_profiler.dll" <1> set ELASTIC_APM_PROFILER_HOME = "" set ELASTIC_APM_PROFILER_INTEGRATIONS = "\integrations.yml" +set ELASTIC_APM_SERVER_URL = "" <2> +set ELASTIC_APM_SECRET_TOKEN = "" <3> ---- <1> `` is the directory to which the zip file was unzipped in step 2. +<2> The URL of the APM server intake to which traces and metrics should be sent. +<3> The https://www.elastic.co/guide/en/apm/guide/current/secret-token.html[secret token] +used by the APM Agent to authenticate with APM server. + .{dot}NET Core / .NET 5+ on Linux [source,sh] @@ -94,13 +103,16 @@ export CORECLR_PROFILER={FA65FE15-F085-4681-9B20-95E04F6C03CC} export CORECLR_PROFILER_PATH="/libelastic_apm_profiler.so" <1> export ELASTIC_APM_PROFILER_HOME="" export ELASTIC_APM_PROFILER_INTEGRATIONS="/integrations.yml" +export ELASTIC_APM_SERVER_URL = "" <2> +export ELASTIC_APM_SECRET_TOKEN = "" <3> ---- - -NOTE: In most cases you want to specify a server URL and a secret token to connect to an APM Server. For a profiler based setup, every agent configuration can be specified by environment variables. The specific name for an environment variable can be found on the <> page. E.g. you can specify the <> by `ELASTIC_APM_SERVER_URL` and the <> by `ELASTIC_APM_SECRET_TOKEN`. - <1> `` is the directory to which the zip file was unzipped in step 2. -. Start your application in a context where the set environment variables are visible. +<2> The URL of the APM server intake to which traces and metrics should be sent. +<3> The https://www.elastic.co/guide/en/apm/guide/current/secret-token.html[secret token] +used by the APM Agent to authenticate with APM server. + +Ensure you start your application in a context where the set environment variables are visible. With this setup, the .NET runtime loads Elastic's CLR profiler into the .NET process, which loads and instantiates the APM agent early in application startup. The profiler monitors methods of interest and injects code to instrument their execution. @@ -154,6 +166,13 @@ ENV ELASTIC_APM_PROFILER_INTEGRATIONS=/elastic_apm_profiler/integrations.yml ENTRYPOINT ["dotnet", "your-application.dll"] ---- +[IMPORTANT] +-- +You should also consider how to securely provide the the APM server URL and secret token as +environment variables when you run your container. It is not recommended to include the +secret token in the image as it may be accidently exposed. +-- + [float] ==== Windows services @@ -168,7 +187,9 @@ $environment = [string[]]@( "COR_PROFILER={FA65FE15-F085-4681-9B20-95E04F6C03CC}", "COR_PROFILER_PATH=\elastic_apm_profiler.dll", "ELASTIC_APM_PROFILER_HOME=", - "ELASTIC_APM_PROFILER_INTEGRATIONS=\integrations.yml") + "ELASTIC_APM_PROFILER_INTEGRATIONS=\integrations.yml" + "ELASTIC_APM_SERVER_URL=" + "ELASTIC_APM_SECRET_TOKEN=") Set-ItemProperty HKLM:SYSTEM\CurrentControlSet\Services\ -Name Environment -Value $environment ---- @@ -181,13 +202,18 @@ $environment = [string[]]@( "CORECLR_PROFILER={FA65FE15-F085-4681-9B20-95E04F6C03CC}", "CORECLR_PROFILER_PATH=\elastic_apm_profiler.dll", <1> "ELASTIC_APM_PROFILER_HOME=", - "ELASTIC_APM_PROFILER_INTEGRATIONS=\integrations.yml") + "ELASTIC_APM_PROFILER_INTEGRATIONS=\integrations.yml" + "ELASTIC_APM_SERVER_URL=" <2> + "ELASTIC_APM_SECRET_TOKEN=") <3> -Set-ItemProperty HKLM:SYSTEM\CurrentControlSet\Services\ -Name Environment -Value $environment <2> +Set-ItemProperty HKLM:SYSTEM\CurrentControlSet\Services\ -Name Environment -Value $environment <4> ---- <1> `` is the directory to which the zip file -was unzipped -<2> `` is the name of the Windows service. +was unzipped. +<2> The URL of the APM server intake to which traces and metrics should be sent. +<3> The https://www.elastic.co/guide/en/apm/guide/current/secret-token.html[secret token] +used by the APM Agent to authenticate with APM server. +<4> `` is the name of the Windows service. The service must then be restarted for the change to take effect. With PowerShell @@ -218,6 +244,8 @@ $environment = @{ ELASTIC_APM_PROFILER_HOME = "$profilerHomeDir" ELASTIC_APM_PROFILER_INTEGRATIONS = "$profilerHomeDir\integrations.yml" COMPlus_LoaderOptimization = "1" <3> + ELASTIC_APM_SERVER_URL = "" <4> + ELASTIC_APM_SECRET_TOKEN = "" <5> } $environment.Keys | ForEach-Object { @@ -231,6 +259,9 @@ was unzipped where Profiler auto-instrumentation cannot instrument assemblies when they are loaded domain-neutral. This limitation is expected to be removed in future, but for now, can be worked around by setting this environment variable. See the https://docs.microsoft.com/en-us/dotnet/framework/app-domains/application-domains#the-complus_loaderoptimization-environment-variable[Microsoft documentation for further details]. +<4> The URL of the APM server intake to which traces and metrics should be sent. +<5> The https://www.elastic.co/guide/en/apm/guide/current/secret-token.html[secret token] +used by the APM Agent to authenticate with APM server. .{dot}NET Core [source,powershell] @@ -244,15 +275,21 @@ $environment = @{ CORECLR_PROFILER_PATH = "$profilerHomeDir\elastic_apm_profiler.dll" ELASTIC_APM_PROFILER_HOME = "$profilerHomeDir" ELASTIC_APM_PROFILER_INTEGRATIONS = "$profilerHomeDir\integrations.yml" + ELASTIC_APM_SERVER_URL = "" <3> + ELASTIC_APM_SECRET_TOKEN = "" <4> } $environment.Keys | ForEach-Object { & $appcmd set config -section:system.applicationHost/applicationPools /+"[name='$appPool'].environmentVariables.[name='$_',value='$($environment[$_])']" } ---- -<1> `` is the name of the Application Pool your application uses. For example, `IIS APPPOOL\DefaultAppPool` +<1> `` is the name of the Application Pool your application uses. +For example, `IIS APPPOOL\DefaultAppPool`. <2> `` is the full path to the directory in which the zip file -was unzipped +was unzipped. +<3> The URL of the APM server intake to which traces and metrics should be sent. +<4> The https://www.elastic.co/guide/en/apm/guide/current/secret-token.html[secret token] +used by the APM Agent to authenticate with APM server. [IMPORTANT] -- @@ -261,7 +298,7 @@ account under which the Application Pool runs]. -- Once environment variables have been set, stop and start IIS so that applications hosted in -IIS will see the new environment variables +IIS will see the new environment variables. [source,sh] ---- @@ -282,9 +319,14 @@ CORECLR_PROFILER={FA65FE15-F085-4681-9B20-95E04F6C03CC} CORECLR_PROFILER_PATH=//libelastic_apm_profiler.so <1> ELASTIC_APM_PROFILER_HOME=/ ELASTIC_APM_PROFILER_INTEGRATIONS=//integrations.yml +ELASTIC_APM_SERVER_URL=" <2> +ELASTIC_APM_SECRET_TOKEN=" <3> ---- <1> `` is the directory to which the zip file -was unzipped +was unzipped. +<2> The URL of the APM server intake to which traces and metrics should be sent. +<3> The https://www.elastic.co/guide/en/apm/guide/current/secret-token.html[secret token] +used by the APM Agent to authenticate with APM server. Then adding an https://www.freedesktop.org/software/systemd/man/systemd.service.html#Command%20lines[`EnvironmentFile`] entry to the service's configuration file that references the path to the environment.env file @@ -297,7 +339,7 @@ ExecStart= <1> ---- <1> the command that starts your service -After adding the `EnvironmentFile` entry, restart the service +After adding the `EnvironmentFile` entry, restart the service. [source,sh] ---- @@ -312,11 +354,10 @@ The profiler auto instrumentation has its own set of environment variables to ma the instrumentation. These are used in addition to <> through environment variables. - `ELASTIC_APM_PROFILER_HOME`:: The home directory of the profiler auto instrumentation. The home directory typically -contains +contains: * platform specific profiler assemblies * a directory for each compatible target framework, where each directory contains From 8f246a1736eb33fb675f67e647d0b0f1644ace0c Mon Sep 17 00:00:00 2001 From: Steve Gordon Date: Tue, 24 Oct 2023 11:58:49 +0200 Subject: [PATCH 2/3] Update min supported version and fix snippet --- docs/setup-auto-instrumentation.asciidoc | 6 +++--- docs/supported-technologies.asciidoc | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/setup-auto-instrumentation.asciidoc b/docs/setup-auto-instrumentation.asciidoc index 8d909c307..738bebb17 100644 --- a/docs/setup-auto-instrumentation.asciidoc +++ b/docs/setup-auto-instrumentation.asciidoc @@ -20,7 +20,7 @@ This approach works with the following |x64 -|.NET Framework 4.6.1+ +|.NET Framework 4.6.2+ .NET Core 2.1+ @@ -319,8 +319,8 @@ CORECLR_PROFILER={FA65FE15-F085-4681-9B20-95E04F6C03CC} CORECLR_PROFILER_PATH=//libelastic_apm_profiler.so <1> ELASTIC_APM_PROFILER_HOME=/ ELASTIC_APM_PROFILER_INTEGRATIONS=//integrations.yml -ELASTIC_APM_SERVER_URL=" <2> -ELASTIC_APM_SECRET_TOKEN=" <3> +ELASTIC_APM_SERVER_URL= <2> +ELASTIC_APM_SECRET_TOKEN= <3> ---- <1> `` is the directory to which the zip file was unzipped. diff --git a/docs/supported-technologies.asciidoc b/docs/supported-technologies.asciidoc index aadff48b8..52ca9d579 100644 --- a/docs/supported-technologies.asciidoc +++ b/docs/supported-technologies.asciidoc @@ -47,7 +47,7 @@ Automatic instrumentation is supported for the following web frameworks |<> |ASP.NET (.NET Framework) in IIS added[1.1] -|4.6.1+ (IIS 7.0 or newer) +|4.6.2+ (IIS 7.0 or newer) |<> _or_ From 330a3ef7750e15a96cf96d3b5546e826d5ee43dc Mon Sep 17 00:00:00 2001 From: Steve Gordon Date: Tue, 24 Oct 2023 13:39:39 +0200 Subject: [PATCH 3/3] Update supported version --- docs/supported-technologies.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/supported-technologies.asciidoc b/docs/supported-technologies.asciidoc index 52ca9d579..77fabbf70 100644 --- a/docs/supported-technologies.asciidoc +++ b/docs/supported-technologies.asciidoc @@ -28,7 +28,7 @@ the agent will not capture transactions. === .NET versions The agent works on every .NET flavor and version that supports .NET Standard 2.0. -This means .NET Core 2.0 or newer, and .NET Framework 4.6.1 or newer. +This means .NET Core 2.0 or newer, and .NET Framework 4.6.2 or newer. [float] [[supported-web-frameworks]]