Merge branch 'main' into feature/windows-profiler-tests

.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

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

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

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]
+----
+<httpRuntime targetFramework="4.5" />
+----
+
+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 "<<legacy-asp-net-sync-context>>" 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 "<<legacy-asp-net-sync-context>>" 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