Skip to content

Commit

Permalink
Document IIS minimum requirements. (#2194)
Browse files Browse the repository at this point in the history
  • Loading branch information
Mpdreamz committed Oct 19, 2023
1 parent 9a05bd3 commit 05c5b16
Show file tree
Hide file tree
Showing 2 changed files with 56 additions and 0 deletions.
11 changes: 11 additions & 0 deletions docs/setup-asp-dot-net.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
45 changes: 45 additions & 0 deletions docs/troubleshooting.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit 05c5b16

Please sign in to comment.