Add troubleshooting instrumentation to an app for SharePoint

apps for SharePoint

Learn how to add custom and enhanced run-time error monitoring to your apps for SharePoint.

Last modified: March 09, 2015

Applies to: apps for SharePoint | SharePoint Add-ins

Note Note

The name "apps for SharePoint" is changing to "SharePoint Add-ins". During the transition, the documentation and the UI of some SharePoint products and Visual Studio tools might still use the term "apps for SharePoint". For details, see New name for apps for Office and SharePoint.

For a good customer experience, run-time errors in apps for SharePoint must be identified, analyzed, and fixed easily from the customer's environment. Instrumentation makes that possible. You can use the built-in monitoring APIs and user interface (UI) to cover the basics. Especially for provider-hosted apps, strong instrumentation in the app must go beyond logging exception messages. This article describes the built-in support for app monitoring and also describes three open-source packages that help gather and analyze run-time information about your apps.

SharePoint 2013 provides a way for website owners to see run-time errors from your app, which they can forward to you. The user takes the following steps.

  1. On the Site Contents page, highlight the app.

  2. Choose the callout link () that appears next to the app name.

  3. Choose DETAILS in the callout. This opens the Details page for the app. Figure 1 shows the part of the page where error information is reported. The total number of installation errors, upgrade errors, and run-time errors is reported. Each of these numbers is a link that opens a callout with details about the errors. The user can send this information to you, possibly as a screen shot.

    Figure 1. App details page

    The details page for an app for SharePoint

    Installation and upgrade errors are available in their respective callouts almost immediately after they occur. Run-time errors may take 5 to 10 minutes. The number of errors of each category that appears on the Details page may take much longer to update.

The SharePoint 2013 infrastructure reports many kinds of errors. You can also design your apps to report custom errors to the same UI. For more information, see the next section.

The client object model of SharePoint 2013 includes a Utility class with two static methods for reporting custom errors to the Details page of your app:

  • LogCustomAppError    Reports errors from SharePoint-hosted components. This method is always called from JavaScript in (or referenced in) a SharePoint-hosted page.

  • LogCustomRemoteAppError    Reports errors from remote components of cloud-hosted apps.

The following is a simple example of calling the LogCustomAppError method:

var context = SP.ClientContext.get_current();
SP.Utilities.Utility.logCustomAppError(context, "My custom error message.");

Typically, you call one of these methods in a catch block. The following is an example of the LogCustomRemoteAppError used in the code behind for a button in a remote web application. Note that clientContext is a ClientContext object, and product_GUID is the product ID of the app.

void OKButton_Click(Object sender, EventArgs e)
        // Your logic is here.
    catch (Exception e)
        // Log a message in SharePoint.
        Utility.LogCustomRemoteAppError(clientContext, product_GUID, "My custom error message.");

Consider giving your users a way to turn on tracing for the IIS-ASP.NET integrated pipeline. When tracing is turned on, all HTTP requests are traced and Trace.Write messages are written to a log that can be accessed through trace.axd. Because tracing collects information about every request, it can have a significant impact on performance of the app, so it should not be on by default.

Tracing works best with ASP.NET form applications because it will automatically log timing for various parts of the page life cycle. You can also add your own custom Trace.Write messages to your code.

One way to include a tracing option to your app is to add a diagnostics page to the app with a function on it to turn on tracing. The following are the major steps for doing this.

  1. Add a trace element to the system.web section of the web.config file of the remote web application. The following is an example.

    <trace enabled="false" pageOutput="false" requestLimit="100" localOnly="false" 
        traceMode="SortByTime" mostRecent="true" writeToDiagnosticsTrace="true" />
  2. Add a diagnostics.aspx page to the web application project. Add to the page a button whose Click event handler changes the enabled attribute of the trace element to true. The following is an example.

    Configuration configuration = WebConfigurationManager.OpenWebConfiguration("~");
    TraceSection section = (TraceSection)configuration.GetSection("system.web/trace");
    section.Enabled = true;
  3. Add a second button to turn off the tracing (or make the logic of the previous button toggle tracing on and off).

  4. Add a link to the trace.axd file, which is the trace log, to the diagnostics page. The following is an example.

    <h2>App Diagnostics</h2>
    <p><a href="~/trace.axd">ASP.NET Trace</a></p>
  5. When a user encounters an error, give the user the URL of the diagnostics page. Have the user turn on tracing and rerun the app. Then you can have the user go to the diagnostics page and, from there, to the trace log where the user can copy the trace information and send it to you. Be sure to have the user turn off tracing.

As an alternative to having the user navigate to the trace.axd log, you can have your button's logic set the pageOutput attribute to true. This causes tracing information to be appended to the bottom of each page that triggered the error.

To minimize the impact of tracing on the performance of the app, ensure that tracing is enabled only for short amounts of time. In general, it should be enabled only long enough for the user to reproduce an error. To avoid having the end users return to the diagnostics page and disable tracing, you may want to consider a timeout for the trace setting. For example, automatically turn it off after 30 minutes or on the next app restart. Your Application_Start handler can then turn off tracing if a certain period of time has gone by since it was turned on.

As an alternative to using IIS tracing, you can add to your app any of several third-party error logging and performance profiling packages. Here is some information about three of them.

© 2015 Microsoft