Wiki

Clone wiki

ElmahR / Setup

Configuring ElmahR

ElmahR is an ASP.NET web application which can be configured to receive error notifications from monitored applications. Although there's virtually no limitations for the platforms the monitored applications have to be built on top of, the most common case (and the only one fully developed and tested so far) is when the monitored applications are ASP.NET web applications too, and when they already use ELMAH as their unhandled exceptions logger. This document will explain in details how to configure multiple ASP.NET web applications to be monitored by a single dashboard instance.

A dashboard should be a separate applications from the monitored ones, you should not have the dashboard page directly inside an existing web application, although it is technically possible and not difficult. That's to keep things cleaner and safer. Of course you will not need to install one dashboard for each monitored applications though, a single dashboard can aggregate more than one source.

Scenario

Let's suppose we want to monitor 2 ASP.NET web applications, which will be sources of errors. Let's call those S1 and S2. Let's also suppose that we want to aggregate them under the same dashboard, which will be an ASP.NET web application on its own, let's call it D.

Preparing the dashboard

Let's start with the dashboard. In order to install D we need the ElmahR bits, which can be found in this repository, and compile them. So far there's no setup ready, but you may want to check the Downloads section to get the latest packaged distribution ready. New ones will be published every now and then to help figuring out how to set up a dashboard, but it's also possible that those will not always be 100% up to date.

If you have a chance to build a web application from scratch it will be very easy to build a dashboard using the available Nuget packages. Please refer to this section of the docs to dig more about it.

With the bits ready in a folder, you will create a web site or a virtual directory pointing at it, and configure it under an ASP.NET 4.0 app pool with integrated pipeline (you could also use IIS Express, especially when testing things).

You will then need to prepare D to receive error notifications from the sources, and you will do that through configuration. You can see a minimal web.config sample file here. There are 3 important pieces there:

  • the declaration of the elmahr config section
  • the PostError.axd HTTP POST handler declaration
  • the actual elmahr section

The 2 declarations are straightforward an they do not need any modification, while the actual elmahr section is the truly relevant piece:

  <elmahr>
    <!-- Monitored applications list -->
    <application name="Source application 1 (S1)" sourceId="S1"/>
  </elmahr>

Here you will add one application key for each application you want to monitor. The name attribute is the title you will see in the dashboard for info related to this source, while the sourceId is a unique key used to identify the source application. Whatever unique key will do. In the sample above we can see how we added a key for S1.

Adding the first source

Now that D is in place and configured to receive errors from S1, let's work on S1 to connect it to ElmahR. S1 is a random existing application, which already has its own web.config, and which is already using ELMAH. I will not go into details about this, if you need help with this part please refer to ELMAH documentation, you can find a lot about it starting from here.

What we need to do is to enhance ELMAH with an additional module which allows it to post errors to the dashboard. As soon as the ElmahR.Elmah assembly and its dependencies have been added to the bin folder of your app, you will have to proceed with configuration. You can see a minimal web.config sample implementing the connection to ElmahR here. The important piece here is related to the errorPost section, which enables the ErrorPostModule.

ErrorPostModule is not available from a normal ELMAH distribution because it's an additional module available in the context of ElmahR project inside the ElmahR.Elmah assembly. It is easily available thanks to a Nuget package, please refer to the corresponding docs section for more details.

The errorPost module is an additional piece you can add to your already existent ELMAH configuration, so you don't have to worry about your current setup, you will not loose any of the service you are already receiving from ELMAH. To add it you need the 3 following pieces:

  • This first block simply declares the configuration section and it's a no-brainer:
  <configSections>
    <sectionGroup name="elmah">
      ...
      <!-- errorPost module is where the source app will get hooked to ElmahR -->
      <section name="errorPost" requirePermission="false" type="Elmah.ErrorLogSectionHandler, Elmah" />
      ...
    </sectionGroup>
  </configSections>
  • The following piece of configuration adds an ASP.NET HTTP module for the ErrorPostModule:
  <system.webServer>
    <modules runAllManagedModulesForAllRequests="true">
      ...
      <!-- the ErroPostModule implementation is inside ElmahR.Elmah -->
      <add name="ErrorPost" type="ElmahR.Elmah.ErrorPostModule, ElmahR.Elmah"/>
      ...
    </modules>
    ...
  </system.webServer>

Again there's nothing much to say about it, you just have to put in in the right place and ensure that ElmahR.Elmah is in your bin directory. This sample is from a web application running with an integrated pipeline, it's pretty easy to convert it to the classic pipeline in case you have that kind of setting (hopefully you won't have to).

  • The following one is the most important block of configuration, where we actually say which dashboard we want to connect to:
  <elmah>
    ...
    <!-- hooking to ElmahR -->
    <errorPost targetUrl="http://localhost/D/posterror.axd" sourceId="S1" />
    ...
  </elmah>
  ...

Every dashboard has an endpoint which is represented by the PostError.axd handler, that's the url the ErrorPostModule has to target through the targetUrl attribute. The sourceId attribute is the key that will be used to sign the messages from the source to the dashboard, and it has to match one of the applications listed in ElmahR's configuration through the corresponding sourceId attribute value.

How to monitor more than one application

So far we installed our dashboard (D), and configured S1 to send errors to D. What if we need more apps to be aggregated to the same dashboard? It's easy, we just need to do 2 things:

  • for each new application to be monitored, list it in the elmahr section of D
  <elmahr>
    <!-- Monitored applications list -->
    <application name="Source application 1 (S1)" sourceId="S1"/>
    <application name="Source application 2 (S2)" sourceId="S2"/>
    ...
  </elmahr>
  • in each new application to be monitored, add the errorPost pieces and have them point to D, making sure that the sourceId matched the sourceId of its counterpart in D's configuration.

Advanced configuration options

ElmahR has some advanced features which can be controlled through its configuration, let's have a look at them:

General dashboard options

You can decorate the elmahr configuration section with these additional attributes:

  • persistorType: errors are persisted using a default in memory persistor, but we already learned here that it can be replaced by different modules for durable support. As long as you deploy just one persistence module, it will be loaded automatically, but during development or testing you may want to deploy more that one module and then choose the right one case by case. This is where persistorType becomes handy, just specify the full name of the type of persistor you want to load and ElmahR will take care of it.
  • ysod: the real-time dashboard is able to reproduce a yellow screen of death (ysod) as it appeared to the user (or as it would if customErrors where disabled, which does not happen to you, does it?), and to do that it needs a specific http handler, definition which is normally added by the ElmahR.Core Nuget package and can be seen here. The code assumes that the handler is called YellowScreenOfDeath.axd, but if you want to change it you are free to as long as you set the same name as a value of the ysod attribute.
  • useCdn: on a release build Javascript files from ElmahR modules are by default bundled and minified, including dependencies on libraries like jQuery or Knockout; nevertheless, for most of those libraries the bundles definitions specify an alternate CDN path, if you want to enable those positions you just have to set useCdn to true and bundles will let these libraries come from the CDNs. Of course, CDN paths might change in future, but you will still be able to deal with it customizing the startup call to ElmahR.Core.Modules.Bootstrapper.Bootstrap() specifying a function taking care of fixing obsolete paths with new ones.

More options

  • disableEntityFrameworkMigrations: available with ElmahR.Persistence.EntityFramework module, this option lets you disable the automatic handling of database schema.

Application options

  • testExceptionUrl: ElmahR lets you specify the URL where the ELMAH test exception endpoint (usually at elmah.axd/test) can be reached, if you do that modules like ElmahR.Modules.Dashboard can build links (the skull) which you can hit to raise test exception on your monitored applications, allowing you to verify things have been configured appropriately.
  • secret: error info is normally POSTed from source to dashboard in clear text, in case this is a major concern you can encrypt it specifying an encryption key using the secret attribute. You will have to specify the same secret attribute, with the same value, on the errorPost configuration section in your monitored application.

More options

  • boxClass: ElmahR.Modules.Dashboard module allows you to specify a boxClass attribute on each application definition in your web.config, this class will be added to the corresponding box on the dashboard page, allowing you to customize its visual appearance.

Deploy issues

  • Deployement under IIS should be easy, but there is one case that needs special handling. Because of certain cryptographic features from SignalR, deploying ElmahR under IIS 7.5 (probably on higher versions also, but I could not test it yet) with Identity=ApplicationPoolIdentity configured requires to activate the "Load User Profile" setting. Without it you will receive an error 500 from SignalR negotiation and the dashboard page will stay in "loading" status. This step is not necessary when using other standard identities, but it is likely to happen with other forms of impersonation.

Conclusions

The web.config files that you can check here in the wiki section of the repository are there for reference and they have been cleaned up from other stuff which was not strictly related to ElmahR, you should remember about this when configuring your systems and keep you stuff around while mixing it with ElmahR related bits.

See also: Nuget packages

Updated