post-release: doc update 1.25.0

CHANGELOG.asciidoc

@@ -23,6 +23,12 @@ endif::[]
 [[release-notes-1.x]]
 === .NET Agent version 1.x
 
+[[release-notes-1.25.0]]
+==== 1.25.0
+
+===== Features 
+{pull}2196[#2196] Support OnExecuteRequestStep available in new .NET versions for IIS modules.
+
 [[release-notes-1.24.0]]
 ==== 1.24.0
 

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