Update tutorial scenario - App is experiencing intermittent exceptions (#3550)

diff --git a/documentation/tutorial/README.md b/documentation/tutorial/README.md
index d350000f129a99167330d63d9d3b0ecc7d9e50bd..ef40afa846c133a1428af60934da48e2ea0e3c15 100644 (file)
--- a/documentation/tutorial/README.md
+++ b/documentation/tutorial/README.md
@@ -1,8 +1,8 @@
 # .NET Core Diagnostics Overview
 
-With .NET Full running on Windows we have grown accustomed to a plethora of great diagnostics tools ranging from dump generation and manual analysis to more sophisticated collection engines such as DebugDiag. As .NET core is picking up (cross platform) steam  what types of diagnostics capabilities are available to us when we need to do production diagnostics? It turns out that a lot of work has been done in this area and specifically .net core 3 promises to bring a wide range of diagnostics capabilities. 
+With .NET Full running on Windows we have grown accustomed to a plethora of great diagnostics tools ranging from dump generation and manual analysis to more sophisticated collection engines such as DebugDiag. As .NET core is picking up (cross platform) steam  what types of diagnostics capabilities are available to us when we need to do production diagnostics? It turns out that a lot of work has been done in this area and specifically .net core 3 promises to bring a wide range of diagnostics capabilities.
 
-To learn more about production diagnostics in .net core 3, we'll be running through a set of diagnostics scenarios using the built in runtime/sdk tools. The walkthroughs are all run on Ubuntu 16.04 and use the latest .net core preview bits. 
+To learn more about production diagnostics in .net core 3, we'll be running through a set of diagnostics scenarios using the built in runtime/sdk tools. The walkthroughs are all run on Ubuntu 16.04 and use the latest .net core preview bits.
 
 Before we jump in head first, let's take a look at some basic methodologies as it relates to production diagnostics. When an outage occurs in production, typically the first and foremost goal is mitigation. Mitigation typically involves getting the app back up and running as quickly as possible. Common mitigation techniques involve restarting the app or sometimes one or more nodes/servers. While restarting is a quick and effective mitigation technique, root cause of the failure is still expected to be understood and appropriate fix(es) made to avoid future downtime. In order to get to root cause, we need to collect as much diagnostics data as we can prior to executing the mitigation strategy. The diagnostics data collected can then be analyzed postmortem to determine root cause and possible fixes. Each of the scenarios we will explore here will outline what capabilities .net core 3 has in terms of diagnostics data collection and analysis.
 
@@ -30,4 +30,4 @@ Please note that you have to be using at least preview 5 for most of the capabil
 
 ### [Scenario - App is not responding](hung_app.md)
 
-### Scenario - App is experiencing intermittent exceptions
+### [Scenario - App is experiencing intermittent exceptions](intermittent_exceptions.md)

diff --git a/documentation/tutorial/intermittent_exceptions.md b/documentation/tutorial/intermittent_exceptions.md
new file mode 100644 (file)
index 0000000..8ee6623
--- /dev/null
+++ b/documentation/tutorial/intermittent_exceptions.md
@@ -0,0 +1,24 @@
+# App is experiencing intermittent exceptions
+
+In this scenario, an ASP.NET application throws intermittent and sporadic exceptions making it challenging to use on demand dump generation tools to capture a dump precisely at the point of the exception being thrown. .NET has the capability to automatically generate dumps when an application exits as a result of an unhandled exception. However, in the case of ASP.NET the ASP.NET runtime catches all exceptions thrown to avoid the application exiting and as such we can't rely on the automatic core dump generation since an exception thrown never becomes unhandled. Fortunately, the Sysinternals ProcDump (v1.4+) for Linux allows you to generate dumps when the application throws any 1st chance exception.
+ProcDump for Linux download/installation instructions can be found here - [ProcDump for Linux](https://github.com/Sysinternals/ProcDump-for-Linux)
+
+
+For example, if we wanted to generate a core dump when an application throws a 1st chance exception, we can use the following:
+
+> ```bash
+> sudo procdump -e MyApp
+> ```
+
+If we wanted to specify which specific exception to generate a core dump on we can use the -f (filter) switch:
+
+> ```bash
+> sudo procdump -e -f System.InvalidOperationException MyApp
+> ```
+
+We can comma separate the list of exceptions in the exception filter.
+
+
+### Performance considerations
+
+ProcDump for Linux implements exception monitoring by using the profiler API. It attaches the profiler to the target process and waits for the exception notifications to arrive and if the filter is satisfied uses the .NET diagnostics pipe to instruct the runtime to generate a dump. Having a profiler attached to a process represents some amount of overhead but unless the application throws a large number of exceptions the overhead should be minimal.
\ No newline at end of file