Microsoft.SystemCenter.WebApplication.UrlProbe

The Microsoft.SystemCenter.WebApplication.UrlProbe probe module connects to one or more URLs and returns Microsoft.SystemCenter.WebApplication.WebApplicationData. This data can then be used with other modules from the Microsoft.SystemCenter.WebApplication.Library to evaluate the health state of various aspects of the target web site.

Usage

The primary function of Microsoft.SystemCenter.WebApplication.UrlProbe is to send a request to one or more URLs and report on the results. The format of the request is a complex type, and is used with other modules to evaluate the health state of the target URL. Because large numbers of requests can be made with a single probe, and because the results of the request can contain a large amount of data, the probe itself carries out some evaluation of the request before producing the output. For example, instead of just providing the status code from the queried URL as output, the module compares the status code against a specified range, and provides a success or failure code as output. The module can also match the content of the HTML that is returned by the request, for example, matching the word “error” to determine if an error page was returned. This evaluation performed by the module removes the need for complex expression matching logic in your rule or monitor.

This module is often commonly triggered using Microsoft.SystemCenter.WebApplication.PerProbe.Scheduler.

The Microsoft.SystemCenter.WebApplication.UrlProbe module is commonly used with a number of condition detection modules which are intended to evaluate its output. The module evaluates different aspects of the health of the URL based on parameters defined in the request and returns appropriate output for each.

Some of those parameters evaluate directly to a health state. For these parameters, you would use three condition detection modules, each of which matches a specific integer output from the probe indicating a particular health state, as shown in the following table:

Other parameters return a binary status. For those cases, two condition detection modules are used, each of which matches a Boolean type from the probe as shown in the following table:

Finally, some raw values are returned, which you can either collect for analysis and reporting or use with expression filter condition detection modules.

Type Definition

<ProbeActionModuleType ID="Microsoft.SystemCenter.WebApplication.UrlProbe" Accessibility="Public" Batching="false" PassThrough="false">
   <Configuration>
      <IncludeSchemaTypes>
         <SchemaType>Microsoft.SystemCenter.WebApplication.WebModulesSchema</SchemaType>
      </IncludeSchemaTypes>
      <xsd:element name="Proxy" type="xsd:string" xmlns:xsd="http://www.w3.org/2001/XMLSchema" />
      <xsd:element name="ProxyUserName" type="xsd:string" xmlns:xsd="http://www.w3.org/2001/XMLSchema" />
      <xsd:element name="ProxyPassword" type="xsd:string" xmlns:xsd="http://www.w3.org/2001/XMLSchema" />
      <xsd:element name="ProxyAuthenticationScheme" type="AuthenticationSchemeType" xmlns:xsd="http://www.w3.org/2001/XMLSchema" />
      <xsd:element name="CredentialUserName" type="xsd:string" xmlns:xsd="http://www.w3.org/2001/XMLSchema" />
      <xsd:element name="CredentialPassword" type="xsd:string" xmlns:xsd="http://www.w3.org/2001/XMLSchema" />
      <xsd:element name="AuthenticationScheme" type="AuthenticationSchemeType" xmlns:xsd="http://www.w3.org/2001/XMLSchema" />
      <xsd:element name="FollowRedirects" type="xsd:boolean" xmlns:xsd="http://www.w3.org/2001/XMLSchema" />
      <xsd:element name="RetryCount" type="xsd:unsignedInt" xmlns:xsd="http://www.w3.org/2001/XMLSchema" />
      <xsd:element name="RequestTimeout" type="xsd:unsignedInt" xmlns:xsd="http://www.w3.org/2001/XMLSchema" />
      <xsd:element name="Requests" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
         <xsd:complexType>
            <xsd:sequence>
               <xsd:element name="Request" type="RequestType" minOccurs="0" maxOccurs="unbounded" />
            </xsd:sequence>
         </xsd:complexType>
      </xsd:element>
      <xsd:element name="TransactionResponseTimeWarningCriteria" type="RequestEvaluationNumericCriteriaType" minOccurs="0" maxOccurs="1" xmlns:xsd="http://www.w3.org/2001/XMLSchema" />
      <xsd:element name="TransactionResponseTimeErrorCriteria" type="RequestEvaluationNumericCriteriaType" minOccurs="0" maxOccurs="1" xmlns:xsd="http://www.w3.org/2001/XMLSchema" />
      <xsd:element name="PerformanceCollectionFrequencyInCycles" type="xsd:unsignedInt" minOccurs="0" maxOccurs="1" default="1" xmlns:xsd="http://www.w3.org/2001/XMLSchema" />
   </Configuration>
   <OverrideableParameters>
      <OverrideableParameter ID="Proxy" Selector="$Config/Proxy$" ParameterType="string" />
      <OverrideableParameter ID="ProxyUserName" Selector="$Config/ProxyUserName$" ParameterType="string" />
      <OverrideableParameter ID="ProxyPassword" Selector="$Config/ProxyPassword$" ParameterType="string" />
      <OverrideableParameter ID="ProxyAuthenticationScheme" Selector="$Config/ProxyAuthenticationScheme$" ParameterType="string" />
      <OverrideableParameter ID="CredentialUserName" Selector="$Config/CredentialUserName$" ParameterType="string" />
      <OverrideableParameter ID="CredentialPassword" Selector="$Config/CredentialPassword$" ParameterType="string" />
      <OverrideableParameter ID="AuthenticationScheme" Selector="$Config/AuthenticationScheme$" ParameterType="string" />
      <OverrideableParameter ID="FollowRedirects" Selector="$Config/FollowRedirects$" ParameterType="bool" />
      <OverrideableParameter ID="RetryCount" Selector="$Config/RetryCount$" ParameterType="int" />
      <OverrideableParameter ID="RequestTimeout" Selector="$Config/RequestTimeout$" ParameterType="int" />
   </OverrideableParameters>
   <ModuleImplementation Isolation="Any">
      <Native>
         <ClassID>92C599FD-6639-4A9F-90DA-E1350162A318</ClassID>
      </Native>
   </ModuleImplementation>
   <OutputType>Microsoft.SystemCenter.WebApplication.WebApplicationData</OutputType>
   <TriggerOnly>true</TriggerOnly>
</ProbeActionModuleType>

Parameters

The Microsoft.SystemCenter.WebApplication.UrlProbe module supports the configuration parameters described in the following table.

Request Element

The Requests element is a collection of one or more Request elements. Each Request element has a RequestID subelement which uniquely identifies the request within that set of Requests. Requests are processed in order, according to their RequestID. The Request element consists of the following elements:

RequestEvaluationCriteria Element

The RequestEvaluationCriteria element provides the ability to evaluate the data returned by the request and determine the health of the URL. Each element is a complex type, which contains criteria that can be matched in one of three ways:

• Numeric criteria. This is the most common and is used to evaluate a measurable value, such as a returned status code or response time.

• Content match criteria. This is used to evaluate the content of the returned HTML to determine whether it contains a particular string of text.

• Custom criteria. This is an expression that matches on a variety of different available parameters defined by the user.

Any number of numeric criteria or custom criteria can be used, but only one content match criterion is allowed. The RequestEvaluationCriteriaType consists of the following elements:

The most common type of evaluation is numeric, in which an item of returned data, such as a resolution time, is compared against a configured threshold. NumericCriteriaExpression is of type RequestEvaluationNumericCriteriaType, which has three elements: NumericRequestMetric, Operator, and Value.

NumericRequestMetric is of type NumericRequestMetricType, which is an enumeration that can consist one of a number of metrics. Each metric is associated with a specific evaluation criterion, as follows:

The Operator element is of type CriteriaCompareType, which consists of one of the following: Equal, NotEqual, Greater, Less, GreaterEqual, or LessEqual.

The Value element is of type double, and specifies the type of the value being compared.

If the returned data item you wish to evaluate is not numeric, such as a content evaluation, you will need to compare against a string. ContentMatchCriteria is of type RequestEvaluationStringCriteriaType, which has two subelements: Operator and Value. Operator can be one of two types:

• SimpleStringOperator, which is of type CriteriaCompareType, which is an enumeration consisting of Equal, NotEqual, Greater, Less, or GreaterEqual.

• RegExOperator, which is of type RegExCompareType, which is an enumeration type consisting of ContainsSubstring, MatchesWildcard, MatchesRegularExpression, MatchesMOM2005RegularExpression, MatchesMOM2005BooleanRegularExpression, DoesNotContainSubstring, DoesNotMatchWildcard, DoesNotMatchRegularEspression, DoesNotMatchMOM2005RegularExpression, or DoesNotMatchMOM2005BooleanRegularExpression

The other element of RequestEvaluationStringCriteriaType is Value, which is a string to be compared.

The CustomCriteria element is of type ExpressionType.

The StatusCodeCriteria element found in LinksEvaluationCriteria and ResourcesEvaluationCriteria is of type ListNumericRequestCriteriaType. ListNumericRequestCriteriaType consists of a sequence of three elements: ListNumericRequestMetric, which can only be the string “StatusCode”, Operator, which is of CriteriaCompareType, covered earlier, and a Value, which must be of type double.

The key to creating a useful URL probe is in the Request element, and usually in the NumericRequestMetric. If you know what part of the web page you’re trying to evaluate, you can choose the correct metric from the enumeration. However, be sure to select the correct category of metric. The metrics for link data, resource data, and total data are all aggregates, and are available for all three categories, so be sure to specify the correct category and ask for it in the correct part of the Request element.

If you only want to evaluate the status code for a particular part of the page (base page, links), use the StatusCodeCriteria element, which would look like this:

<StatusCodeCriteria>
  <ListNumericRequestMetric>StatusCode</ListNumericRequestMetric>
  <Operator>GreaterEqual</Operator>
  <Value>400</Value>
</StatusCodeCriteria>

This StatusCodeCriteria section checks for a success response from the probe (Status code greater than or equal to 400).

Composition

The Microsoft.SystemCenter.WebApplication.UrlProbe module is a native module.

Related Modules

External Module References

Sample

The following example carries out a simple URL probe against the URL https://www.microsoft.com. The data source evaluates the status code returned for the base page, and returns a value of 3 if the status code is greater than 400, indicating an error state. It also evaluates the status code returned for the resources, and links, and returns a value of 2 if the status code is greater than 400, indicating a warning state.

  <TypeDefinitions>
    <ModuleTypes>
      <DataSourceModuleType ID="MPAuthor.WebApplications.UrlDataSource" Accessibility="Public" Batching="false">
        <Configuration />
        <ModuleImplementation Isolation="Any">
          <Composite>
            <MemberModules>
              <DataSource ID="Scheduler" TypeID="MicrosoftSystemCenterWebApplicationLibrary!Microsoft.SystemCenter.WebApplication.PerProbe.Scheduler">
                <Scheduler>
                  <SimpleReccuringSchedule>
                    <Interval Unit="Seconds">120</Interval>
                    <SpreadInitializationOverInterval Unit="Seconds">120</SpreadInitializationOverInterval>
                  </SimpleReccuringSchedule>
                  <ExcludeDates />
                </Scheduler>
                <UniquenessKey>$Target/Id$</UniquenessKey>
              </DataSource>
              <ProbeAction ID="Probe" TypeID="MicrosoftSystemCenterWebApplicationLibrary!Microsoft.SystemCenter.WebApplication.UrlProbe">
                <Proxy />
                <ProxyUserName />
                <ProxyPassword />
                <ProxyAuthenticationScheme>None</ProxyAuthenticationScheme>
                <CredentialUserName />
                <CredentialPassword />
                <AuthenticationScheme>None</AuthenticationScheme>
                <FollowRedirects>true</FollowRedirects>
                <RetryCount>0</RetryCount>
                <RequestTimeout>0</RequestTimeout>
                <Requests>
                  <Request>
                    <RequestID>1</RequestID>
                    <URL>https://www.microsoft.com</URL>
                    <Verb>GET</Verb>
                    <Version>HTTP/1.1</Version>
                    <HttpHeaders>
                      <HttpHeader>
                        <Name>User-Agent</Name>
                        <Value>Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1)</Value>
                      </HttpHeader>
                    </HttpHeaders>
                    <Body />
                    <CheckContentChange>false</CheckContentChange>
                    <ContentHash>00000000-0000-0000-0000-000000000000</ContentHash>
                    <Depth>0</Depth>
                    <ThinkTime>0</ThinkTime>
                    <CheckInternalLinks>false</CheckInternalLinks>
                    <CheckExternalLinks>false</CheckExternalLinks>
                    <CheckResources>false</CheckResources>
                    <RequestEvaluationCriteria>
                      <StopProcessingIfWarningCriteriaIsMet>false</StopProcessingIfWarningCriteriaIsMet>
                      <StopProcessingIfErrorCriteriaIsMet>false</StopProcessingIfErrorCriteriaIsMet>
                      <BasePageEvaluationCriteria>
                        <WarningCriteria />
                        <ErrorCriteria>
                          <NumericCriteriaExpressions>
                            <NumericCriteriaExpression>
                              <NumericRequestMetric>BasePageData/StatusCode</NumericRequestMetric>
                              <Operator>GreaterEqual</Operator>
                              <Value>400</Value>
                            </NumericCriteriaExpression>
                          </NumericCriteriaExpressions>
                        </ErrorCriteria>
                      </BasePageEvaluationCriteria>
                      <LinksEvaluationCriteria>
                        <WarningCriteria>
                          <StatusCodeCriteria>
                            <ListNumericRequestMetric>StatusCode</ListNumericRequestMetric>
                            <Operator>GreaterEqual</Operator>
                            <Value>400</Value>
                          </StatusCodeCriteria>
                        </WarningCriteria>
                        <ErrorCriteria />
                      </LinksEvaluationCriteria>
                      <ResourcesEvaluationCriteria>
                        <WarningCriteria>
                          <StatusCodeCriteria>
                            <ListNumericRequestMetric>StatusCode</ListNumericRequestMetric>
                            <Operator>GreaterEqual</Operator>
                            <Value>400</Value>
                          </StatusCodeCriteria>
                        </WarningCriteria>
                        <ErrorCriteria />
                      </ResourcesEvaluationCriteria>
                      <WebPageTotalEvaluationCriteria>
                        <WarningCriteria />
                        <ErrorCriteria />
                      </WebPageTotalEvaluationCriteria>
                      <DepthEvaluationCriteria>
                        <WarningCriteria />
                        <ErrorCriteria />
                      </DepthEvaluationCriteria>
                    </RequestEvaluationCriteria>
                    <FormsAuthCredentials />
                    <CollectResponseBody>OnContentMatchCriteria</CollectResponseBody>
                    <CollectLinksHeaders>false</CollectLinksHeaders>
                    <CollectResourcesHeaders>false</CollectResourcesHeaders>
                  </Request>
                </Requests>
              </ProbeAction>
            </MemberModules>
            <Composition>
              <Node ID="Probe">
                <Node ID="Scheduler" />
              </Node>
            </Composition>
          </Composite>
        </ModuleImplementation>
        <OutputType>MicrosoftSystemCenterWebApplicationLibrary!Microsoft.SystemCenter.WebApplication.WebApplicationData</OutputType>
      </DataSourceModuleType>
    </ModuleTypes>
    <MonitorTypes>
      <UnitMonitorType ID="MPAuthor.WebApplications.BasePageErrorCodeMonitor" Accessibility="Internal">
        <MonitorTypeStates>
          <MonitorTypeState ID="ErrorCodeFailure" NoDetection="false" />
          <MonitorTypeState ID="ErrorCodeSuccess" NoDetection="false" />
        </MonitorTypeStates>
        <Configuration>
          <xsd:element minOccurs="1" name="RequestID" type="xsd:integer" />
        </Configuration>
        <MonitorImplementation>
          <MemberModules>
            <DataSource ID="DS1" TypeID="MPAuthor.WebApplications.UrlDataSource" />
            <ConditionDetection ID="CDErrorCodeFailureTrue" TypeID="System!System.ExpressionFilter">
              <Expression>
                <SimpleExpression>
                  <ValueExpression>
                    <XPathQuery>RequestResults/RequestResult[@Id="$Config/RequestID$"]/BasePageData/ErrorCode</XPathQuery>
                  </ValueExpression>
                  <Operator>NotEqual</Operator>
                  <ValueExpression>
                    <XPathQuery>0</XPathQuery>
                  </ValueExpression>
                </SimpleExpression>
              </Expression>
            </ConditionDetection>
            <ConditionDetection ID="CDErrorCodeFailureFalse" TypeID="System!System.ExpressionFilter">
              <Expression>
                <SimpleExpression>
                  <ValueExpression>
                    <XPathQuery>RequestResults/RequestResult[@Id="$Config/RequestID$"]/BasePageData/ErrorCode</XPathQuery>
                  </ValueExpression>
                  <Operator>Equal</Operator>
                  <ValueExpression>
                    <XPathQuery>0</XPathQuery>
                  </ValueExpression>
                </SimpleExpression>
              </Expression>
            </ConditionDetection>
          </MemberModules>
          <RegularDetections>
            <RegularDetection MonitorTypeStateID="ErrorCodeFailure">
              <Node ID="CDErrorCodeFailureTrue">
                <Node ID="DS1" />
              </Node>
            </RegularDetection>
            <RegularDetection MonitorTypeStateID="ErrorCodeSuccess">
              <Node ID="CDErrorCodeFailureFalse">
                <Node ID="DS1" />
              </Node>
            </RegularDetection>
          </RegularDetections>
        </MonitorImplementation>
      </UnitMonitorType>
    </MonitorTypes>
  </TypeDefinitions>

Information