From a7c9610da730cf4131ab8352f5201c73006b653a Mon Sep 17 00:00:00 2001 From: Martijn Laarman Date: Tue, 10 Oct 2023 11:27:42 +0200 Subject: [PATCH 1/3] Document IIS minimum requirements. (#2194) --- docs/setup-asp-dot-net.asciidoc | 11 ++++++++ docs/troubleshooting.asciidoc | 45 +++++++++++++++++++++++++++++++++ 2 files changed, 56 insertions(+) diff --git a/docs/setup-asp-dot-net.asciidoc b/docs/setup-asp-dot-net.asciidoc index 31d06571c2..23d7edca94 100644 --- a/docs/setup-asp-dot-net.asciidoc +++ b/docs/setup-asp-dot-net.asciidoc @@ -49,6 +49,17 @@ such as `.aspx` pages, add the `managedHandler` preCondition to your `web.config + NOTE: To learn more about adding modules, see the https://docs.microsoft.com/en-us/iis/configuration/system.webserver/modules/add[Microsoft docs]. +[NOTE] +-- +Our IIS module requires: + +* IIS 7 or later +* Application pool's pipeline mode has to be set to integrated (default for IIS 7 and up) +* The deployed .NET application must NOT run under quirks mode. This makes `LegacyAspNetSynchronizationContext` the async context handler and can break `HttpContext.Items` correctly +restoring when async code introduces a thread switch. +-- + + . Recompile your application and deploy it. + The `ElasticApmModule` instantiates the APM agent on the first initialization. However, there may be some scenarios where diff --git a/docs/troubleshooting.asciidoc b/docs/troubleshooting.asciidoc index c54452b112..1cab69d2b0 100644 --- a/docs/troubleshooting.asciidoc +++ b/docs/troubleshooting.asciidoc @@ -173,6 +173,51 @@ You may use the Public Agent API with the `Elastic.Apm.Agent` class in code that To prevent the `InstanceAlreadyCreatedException` in these scenarios, first use the `Elastic.Apm.Agent.IsConfigured` method to check if the agent is already initialized. After the check, you can safely use other methods in the Public Agent API. This will prevent accidental implicit agent initialization. +[float] +[[legacy-asp-net-sync-context]] +=== ASP.NET is using LegacyAspNetSynchronizationContext and might not behave well for asynchronous code + +If you see this warning being logged it means your classic ASP.NET Application is running under quirks mode and is using a deprecated but backwards compatible asynchronous context. +This may prevent our agent from working correctly when asynchronous code introduces a thread switch since this context does not reliably restore `HttpContext.Items`. + +To break out of quirks mode the runtime must be explicitly specified in web.config: + + +[source,xml] +---- + +---- + +Read more about ASP.NET quirks mode here: https://devblogs.microsoft.com/dotnet/all-about-httpruntime-targetframework + +[float] +[[sql-failed-to-remove-from-processing-spans]] +=== SqlEventListener Failed capturing sql statement (failed to remove from ProcessingSpans). + +We log this warning when our SQL even listener is unable to find the active transaction. +This has been only observed under IIS when the application is running under quirks mode. +See "<>" section for more backfround information and possible fixes. + + +[float] +[[http-no-transaction]] +=== HttpDiagnosticListenerFullFrameworkImpl No current transaction, skip creating span for outgoing HTTP request + +We log this trace warning when our outgoing HTTP listener is not able to get the current transaction. +This has been only observed under IIS when the application is running under quirks mode. +See "<>" section for more backfround information and possible fixes. + + +[float] +[[iis-integrated-pipeline-mode]] +=== Exception: System.PlatformNotSupportedException: This operation requires IIS integrated pipeline mode + +This exception happens if the classic ASP.NET application run under an Application pool that enforces the classic pipeline mode. +This prevents our agent to modify headers and thus will break distributed tracing. + +The agent is only supported on IIS7 and higher where the `Integrated Pipeline Mode` is the default. + + [float] [[startup-hook-failure]] === Startup hooks failure From d3bb7b5c2e00ab588a812e6096538d56904e3b34 Mon Sep 17 00:00:00 2001 From: Steve Gordon Date: Tue, 10 Oct 2023 12:32:09 +0100 Subject: [PATCH 2/3] Add note to profiler logs (#2192) --- docs/setup-auto-instrumentation.asciidoc | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/setup-auto-instrumentation.asciidoc b/docs/setup-auto-instrumentation.asciidoc index 812716df96..9558ebdc29 100644 --- a/docs/setup-auto-instrumentation.asciidoc +++ b/docs/setup-auto-instrumentation.asciidoc @@ -376,6 +376,14 @@ If the default directory cannot be written to for some reason, the profiler will try to write log files to a `logs` directory in the home directory specified by `ELASTIC_APM_PROFILER_HOME` environment variable. +[IMPORTANT] +-- +The user account under which the profiler process runs must have permission to +write to the destination log directory. Specifically, ensure that when running +on IIS, the https://learn.microsoft.com/en-us/iis/manage/configuring-security/application-pool-identities[AppPool identity] +has write permissions in the target directory. +-- + `ELASTIC_APM_PROFILER_LOG_TARGETS` _(optional)_:: A semi-colon separated list of targets for profiler logs. Valid values are From 583f085df59ede90ce64b683de9c9ae67d5262ba Mon Sep 17 00:00:00 2001 From: Victor Martinez Date: Tue, 10 Oct 2023 13:40:23 +0200 Subject: [PATCH 3/3] json-specs: cgroup_parsing has been removed (#2193) --- .ci/updatecli.d/update-json-specs.yml | 12 ++++++------ .../json-specs/container_metadata_discovery.json | 0 2 files changed, 6 insertions(+), 6 deletions(-) create mode 100644 test/Elastic.Apm.Tests.Utilities/TestResources/json-specs/container_metadata_discovery.json diff --git a/.ci/updatecli.d/update-json-specs.yml b/.ci/updatecli.d/update-json-specs.yml index 9191ec4610..2972b191e0 100644 --- a/.ci/updatecli.d/update-json-specs.yml +++ b/.ci/updatecli.d/update-json-specs.yml @@ -24,10 +24,10 @@ sources: - findsubmatch: pattern: "[0-9a-f]{40}" - cgroup_parsing.json: + container_metadata_discovery.json: kind: file spec: - file: https://raw.githubusercontent.com/elastic/apm/main/tests/agents/json-specs/cgroup_parsing.json + file: https://raw.githubusercontent.com/elastic/apm/main/tests/agents/json-specs/container_metadata_discovery.json service_resource_inference.json: kind: file spec: @@ -71,13 +71,13 @@ actions: * https://github.com/elastic/apm/commit/{{ source "sha" }} targets: - cgroup_parsing.json: - name: cgroup_parsing.json + container_metadata_discovery.json: + name: container_metadata_discovery.json scmid: default - sourceid: cgroup_parsing.json + sourceid: container_metadata_discovery.json kind: file spec: - file: test/Elastic.Apm.Tests.Utilities/TestResources/json-specs/cgroup_parsing.json + file: test/Elastic.Apm.Tests.Utilities/TestResources/json-specs/container_metadata_discovery.json service_resource_inference.json: name: service_resource_inference.json scmid: default diff --git a/test/Elastic.Apm.Tests.Utilities/TestResources/json-specs/container_metadata_discovery.json b/test/Elastic.Apm.Tests.Utilities/TestResources/json-specs/container_metadata_discovery.json new file mode 100644 index 0000000000..e69de29bb2