Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update auto intrumentation docs #2208

Merged
merged 3 commits into from
Oct 30, 2023
Merged

Update auto intrumentation docs #2208

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5cf78c9
Update auto intrumentation docs
stevejgordon Oct 23, 2023
8f246a1
Update min supported version and fix snippet
stevejgordon Oct 24, 2023
330a3ef
Update supported version
stevejgordon Oct 24, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
83 changes: 62 additions & 21 deletions docs/setup-auto-instrumentation.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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+

Expand All @@ -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[]

Expand All @@ -60,7 +59,7 @@ See <<instrumenting-containers-and-services>> for configuration for common deplo

. Download the `elastic_apm_profiler_<version>.zip` file from the https://github.com/elastic/apm-agent-dotnet/releases[Releases] page of the .NET APM Agent GitHub repository, where `<version>` 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]
Expand All @@ -70,9 +69,14 @@ set COR_PROFILER = "{FA65FE15-F085-4681-9B20-95E04F6C03CC}"
set COR_PROFILER_PATH = "<unzipped directory>\elastic_apm_profiler.dll" <1>
set ELASTIC_APM_PROFILER_HOME = "<unzipped directory>"
set ELASTIC_APM_PROFILER_INTEGRATIONS = "<unzipped directory>\integrations.yml"
set ELASTIC_APM_SERVER_URL = "<apm server url>" <2>
set ELASTIC_APM_SECRET_TOKEN = "<secret token>" <3>
----
<1> `<unzipped directory>` 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]
Expand All @@ -82,9 +86,14 @@ set CORECLR_PROFILER = "{FA65FE15-F085-4681-9B20-95E04F6C03CC}"
set CORECLR_PROFILER_PATH = "<unzipped directory>\elastic_apm_profiler.dll" <1>
set ELASTIC_APM_PROFILER_HOME = "<unzipped directory>"
set ELASTIC_APM_PROFILER_INTEGRATIONS = "<unzipped directory>\integrations.yml"
set ELASTIC_APM_SERVER_URL = "<apm server url>" <2>
set ELASTIC_APM_SECRET_TOKEN = "<secret token>" <3>
----
<1> `<unzipped directory>` 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]
Expand All @@ -94,13 +103,16 @@ export CORECLR_PROFILER={FA65FE15-F085-4681-9B20-95E04F6C03CC}
export CORECLR_PROFILER_PATH="<unzipped directory>/libelastic_apm_profiler.so" <1>
export ELASTIC_APM_PROFILER_HOME="<unzipped directory>"
export ELASTIC_APM_PROFILER_INTEGRATIONS="<unzipped directory>/integrations.yml"
export ELASTIC_APM_SERVER_URL = "<apm server url>" <2>
export ELASTIC_APM_SECRET_TOKEN = "<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 <<configuration, general configuration>> page. E.g. you can specify the <<config-server-url,server URL>> by `ELASTIC_APM_SERVER_URL` and the <<config-secret-token, secret token>> by `ELASTIC_APM_SECRET_TOKEN`.

<1> `<unzipped directory>` 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.
Expand Down Expand Up @@ -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

Expand All @@ -168,7 +187,9 @@ $environment = [string[]]@(
"COR_PROFILER={FA65FE15-F085-4681-9B20-95E04F6C03CC}",
"COR_PROFILER_PATH=<unzipped directory>\elastic_apm_profiler.dll",
"ELASTIC_APM_PROFILER_HOME=<unzipped directory>",
"ELASTIC_APM_PROFILER_INTEGRATIONS=<unzipped directory>\integrations.yml")
"ELASTIC_APM_PROFILER_INTEGRATIONS=<unzipped directory>\integrations.yml"
"ELASTIC_APM_SERVER_URL=<apm server url>"
"ELASTIC_APM_SECRET_TOKEN=<secret token>")

Set-ItemProperty HKLM:SYSTEM\CurrentControlSet\Services\<service-name> -Name Environment -Value $environment
----
Expand All @@ -181,13 +202,18 @@ $environment = [string[]]@(
"CORECLR_PROFILER={FA65FE15-F085-4681-9B20-95E04F6C03CC}",
"CORECLR_PROFILER_PATH=<unzipped directory>\elastic_apm_profiler.dll", <1>
"ELASTIC_APM_PROFILER_HOME=<unzipped directory>",
"ELASTIC_APM_PROFILER_INTEGRATIONS=<unzipped directory>\integrations.yml")
"ELASTIC_APM_PROFILER_INTEGRATIONS=<unzipped directory>\integrations.yml"
"ELASTIC_APM_SERVER_URL=<apm server url>" <2>
"ELASTIC_APM_SECRET_TOKEN=<secret token>") <3>

Set-ItemProperty HKLM:SYSTEM\CurrentControlSet\Services\<service-name> -Name Environment -Value $environment <2>
Set-ItemProperty HKLM:SYSTEM\CurrentControlSet\Services\<service-name> -Name Environment -Value $environment <4>
----
<1> `<unzipped directory>` is the directory to which the zip file
was unzipped
<2> `<service-name>` 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> `<service-name>` is the name of the Windows service.

The service must then be restarted for the change to take effect. With PowerShell

Expand Down Expand Up @@ -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 = "<apm server url>" <4>
ELASTIC_APM_SECRET_TOKEN = "<secret token>" <5>
}

$environment.Keys | ForEach-Object {
Expand All @@ -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]
Expand All @@ -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 = "<apm server url>" <3>
ELASTIC_APM_SECRET_TOKEN = "<secret token>" <4>
}

$environment.Keys | ForEach-Object {
& $appcmd set config -section:system.applicationHost/applicationPools /+"[name='$appPool'].environmentVariables.[name='$_',value='$($environment[$_])']"
}
----
<1> `<application-pool>` is the name of the Application Pool your application uses. For example, `IIS APPPOOL\DefaultAppPool`
<1> `<application-pool>` is the name of the Application Pool your application uses.
For example, `IIS APPPOOL\DefaultAppPool`.
<2> `<unzipped directory>` 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]
--
Expand All @@ -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]
----
Expand All @@ -282,9 +319,14 @@ CORECLR_PROFILER={FA65FE15-F085-4681-9B20-95E04F6C03CC}
CORECLR_PROFILER_PATH=/<unzipped directory>/libelastic_apm_profiler.so <1>
ELASTIC_APM_PROFILER_HOME=/<unzipped directory>
ELASTIC_APM_PROFILER_INTEGRATIONS=/<unzipped directory>/integrations.yml
ELASTIC_APM_SERVER_URL=<apm server url> <2>
ELASTIC_APM_SECRET_TOKEN=<secret token> <3>
----
<1> `<unzipped directory>` 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
Expand All @@ -297,7 +339,7 @@ ExecStart=<command> <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]
----
Expand All @@ -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 <<configuration, agent configuration>>
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
Expand Down
4 changes: 2 additions & 2 deletions docs/supported-technologies.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]]
Expand All @@ -47,7 +47,7 @@ Automatic instrumentation is supported for the following web frameworks
|<<setup-asp-net-core, NuGet package>>

|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)
|<<setup-auto-instrumentation, Profiler auto instrumentation>>

_or_
Expand Down