LDSTechForumProjects

Canary Pages

This article is in a draft stage.


Introduction

The goals of Canary page functionality are to make them Standard, Simple, Secure, Integrated and Extensible. Canary pages can be enabled through Web.config:

<Lds.Stack>	
    <canaryPage enabled="true" />
</Lds.Stack>

They can be accessed at http://<your-app-root>/canary.

  • Configuration format matches output format:
Web.config Canary output
. . .
<Lds.Stack>
 <canaryPage>
  <project-information>
   <info name="Product Name">MyApp</info>
   <info name="Product Version">*</info>
   <info name="Build Date">*</info>
   <info name="Build Version">*</info>
  </project-information>
 </canaryPage>
</Lds.Stack>
. . .
<?xml version="1.0" encoding="utf-8"?> 
<canaryPage>
 <title>MyApp Canary Page</title>
 <project-information>
  <info name="Product Name">MyApp</info>
  <info name="Product Version">1.2.0.43</info>
  <info name="Build Date">2012-08-29 10:29</info>
  <info name="Build Version">1.2.0.43</info>
 </project-information>
 <service>
  <name>Application</name>
  <status>OK</status>
  <response-time>1</response-time>
 </service>  
</canaryPage>

Standard and Integrated

  • Consistent across .NET Applications
  • Consistent with Java Stack
  • Must be in standard XML format as defined by the Middleware (ASE-Assist), Monitoring (Nagios) and ITSM/ITIL (UCMDB) teams.

Terminology

To Do: Add some information

Configuration

Project Information

These are the expected default outputs:

  • Current Time on Server
  • Product Name
  • Product Version
  • Build Version
  • Build Date
  • Runtime .NET Framework Version
  • Product .NET Framework Version
  • Server OS Version

Extensible

Resource Information

Resource Types

There are three built-in resource types:

  • HTTP
<HttpResource name="LDS.org" url="http://lds.org" />
  • Database
<DataResource name="MyDb" connection="MyNamedConnection" />
  • LDS Account
<LdsAccountResource name="LDS Account" />

There is also one custom resource type that is checked by the class which implements IResourceChecker.

Secure

Resource Configuration

  • Limit Canary Page requests to local machine
<canaryPage>   
  <security localOnly="true" />
</canaryPage>
  • Limit Canary Page requests by IP address
<canaryPage>   
  <security source-ip="172.16.10.44" />
</canaryPage>
  • Limit information displayed on Canary Page
<canaryPage>  
  <security> 
    <source-ip start="172.16.0.0"
               end="172.16.254.254" />
  </security>
</canaryPage>
  • Future
    • Require authentication
    • Limit by calling application

Simple

Status

There are only three status values:

  • OK - the resource responded to a check as expected and an exception did not occur.
  • WARNING - the resource responded to a check with an unexpected value or threw an exception.
  • CRITICAL - the resource check took longer than the amount of time allotted which is 5 seconds for the main canary page or 28 seconds on individual service pages.

Common Settings

Name Required Default Value Description
name Yes Must be unique across all services.
timeout Number of seconds each response is considered critical if it does not respond.
cache-duration Number of seconds each response is cached before the resource will be checked again.
resource-information name-value pairs Ignored by Nagios but can provide additional data for your application.
comments Ignored by Nagios.
debug-delay
checker

HTTP Resource Settings:

<HttpResource name="LDS.org" url="http://lds.org" />
Name Required Default Value Description
url Yes Can be HTTP or HTTPS.
response-code 200 Expected HTTP resource code. If this response is received, status is OK.

Note: Response body is not parsed. Authentication is not supported.


Database Resource Settings:

<DataResource name="MyDb" connection="MyNamedConnection" />
Name Required Default Value Description
connection Yes Can be named connection string from Web.config, or a full connection string.
provider-name Omit when using a named connection string.
query SELECT 1 The query to execute.

Simply validates that a connection can be made and a command executed using the supplied connection string.

result-type The data type of the expected result:
text (or string): A single string value.
numeric: A single numeric value (double).
recordset: Multiple records. The count of the records will be verified.
expected-result Expected result for a single value.
expected-result-min Expected result for a range of values.
expected-result-max Expected result for a range of values.
show-query Always Options are "Never," "Always" or "OnFailure."
show-result Always Options are "Never," "Always" or "OnFailure."
show-connection Never Options are "Never," "Always" or "OnFailure."

LDS Account Resource Settings:

<LdsAccountResource name="LDS Account" />

By default, this resource is checked using the server and credentials you specified in the Stack Security section of Web.config.

Name Required Default Value Description
userName The credentials to bind to LDS Account.
password The credentials used to bind to LDS Account.
server The LDS Account LDAP server.
distinguished-name
show-server
show-user-name

Custom Resource Settings:

<CustomResource name="LDS Account" 
                type="MyApplication.MyResourceClass, MyApplication"
                checker="MyApplication.MyResourceCheckerClass, MyApplication" />
Name Required Default Value Description
type Qualified type of the custom Resource class. Must inherit from Lds.Stack.Canary.Resource.
checker Qualified type of the custom Resource Checker class. Must implement Lds.Stack.Canary.IResourceChecker.

Other Settings:

Name Required Default Value Description
max-wait-time The maximum amount of time to wait for services to complete before returning the Canary Page. This is independent from timeout; it only controls how long the handler waits before returning something to the user (or caller).
nagios-format true Indicates whether to rename and reformat certain nodes to match the expected format of Nagios monitoring. For example, <resource> nodes are renamed as <service>.
stylesheet XSLT for transforming the Canary Page for presentation. Path is relative to the application root.
This page was last modified on 7 December 2012, at 16:12.

Note: Content found in this wiki may not always reflect official Church information. See Terms of Use.