Gnomon Manual

Firstly, download the current gnomon installer package. When installing, be sure to install the samples. All being well then gnomon will add a document mapping for .acds pages to itself and create a virtual directory under the chosen (or default website) called /gnomon. If this process fails then try checking the steps listed in the manual installation chapter.

To upgrade gnomon from a previous release, first stop any web services and close any instances of perfmon. This step saves having to reboot the server to complete installation by releasing any in use gnomon files. Then simply run the installer package as described in the quick start section.

If you are using the gnomon COM+ package for session, gnomonASP handling, or other code you will need to recreate this package when upgrading. To do this, delete the existing gnomon COM+ package using the Component Services applet in Control Panel/Administrative tools, and then run the gnomon COM+ setup program. You can either do this before install, when you are offered the option of creating the package, or after install by using the link installed in the start menu.

You should be able to view the first sample after installation. Essentially, what this demonstrates is the default operation of gnomon, which is:

Stylesheets are always cached by gnomon. The same compiled stylesheet is used for any subsequent transforms. To ease development, gnomon tracks changes in stylesheets and dependencies, and automatically recompiles the stylesheet when it changes.

The second sample demonstrates the use of some gnomon extension functions by dumping out the query-string, form, server-variables and cookies collections. These functions are installed in the namespace http://www.npsl.co.uk/gnomon and are described in detail in the chapter on gnomon built-in functions.

The third sample demonstrates dynamically generating XML from an ASP page. The page simply writes out the current time, but the principal can be expanded to dynamically generate any valid XML page (perhaps including content from a database).

The gnomon configuration file allows you to tailor the behaviour of gnomon as desired. Gnomon's configuration is hierarchical; most settings are inherited from the parent configuration file (as detailed below). There is an inbuilt default configuration, which represents the root of the hierarchy, this is used if no other configuration is present. Directories represent the levels of the hierachy, you can provide a separate gnomon.config in each directory. If no configuration file is preseent, then all settings are inherited from the previous level. The first possible provided configuration file is at the root of each website (this represents the second level of the configuration hierarchy, the first is the default configuration). It is possible to have multiple sites each with different configuration files, this is handled transparently.

A complete sample configuration is listed below. Each element of the configuration file is described in detail in the following sections.

	<config>
		<!-- 
			Limit the amount of POST data that gnomon will handle.
			0 is unlimited (not recommended!)
		 -->
		<post-limit size="1048576"/>

		<!--
			Define custom error handlers for errors that may be produced
			during processing.  This allows you to show users a generic
			error page, and possibly have code that logs or alerts
			based on the errors.
			
			The warnings-as-errors attribute allows you to force gnomon
			to report warnings encountered during XSLT processing.
			By default, they are ignored.
		 -->
		<errors override-parents="yes" warnings-as-errors="1">
			<!-- 
				Generic ASP error handling page, for all errors 
				except SERVER_TOO_BUSY (which only supports the redirect 
				and file methods)
			-->
			<handler code="*">
				<uri method="POST">/errors/gnomon_error.asp</uri>
			</handler>
			<!--
				A straightforward error message to display if the
				server is currently too busy to handle the load
			 -->
			<handler code="SERVER_TOO_BUSY">
				<file>c:\inetpub\wwwroot\gnomon\gnomon_too_busy.html</file>
			</handler>
		</errors>

		<cache>
			<!--
				Find the cachable HTTP methods for the XML files (templates) using this xpath expression 
			   	Override the parent's setting to no-cache by setting this empty.
			 -->
			<select-cache-methods xpath="/document/@cache-methods"/>
			-->
		</cache>
	
		<stylesheets>
			<!--
				How to get stylesheets.  http or file are supported.
				file is the default (maps the URI to a file and reads it in),
				as it is faster and typically stylesheets are not
				generated dynamically.
			 -->
			<fetch-method>file</fetch-method>
			<!-- 
				Use processing instructions.  These are less flexible than the select-stylesheets
				method as they give no opportunity to override default stylesheets.
			  -->
			<use-processing-instruction value = "1"/>
			<!-- 
				Find the stylesheets from the document using this xpath expression.
				Note that use-processing-instruction overrides this.
			 -->
			<select-stylesheets xpath="/document/stylesheets">
			<!--
				List any default stylesheets to apply before/after those listed by the
				individual document
			 -->
			<default-stylesheets override-parents="first,last">
				<first>
					<stylesheet href="/styles/some-first-sheet.xsl"/>
				</first>
				<last>
					<stylesheet href="/styles/some-last-sheet.xsl"/>
				</last>
			</default-stylesheets>
		</stylesheets>
	
		<!-- The codepage to use when parsing GET/POST data -->	
		<uri-codepage>utf-8</uri-codepage>
		
		<!-- 
			Used for redirecting URIs, basically for making loopback requests rather than external ones.
			e.g. where www.npsl.co.uk resolves to an external load balanced IP, we actually want
			to fetch the URI from localhost.
			override-parents will clear any inherited rewrites.
			All rewrites are applied in order.  Use conditionals in the format to prevent inadvertent rewrites.
			(This may change in future if it proves to be sufficiently inflexible)
		 -->
		<uri-rewrites override-parents="yes">
			<!-- Lazy all hosts match -->
			<uri match="(https?://)([^:/]*)(:[^/]*)?(/)?([^?]*)\.acds(\?[^#?]*)?" format="?1http\://localhost$3/$5.xml$6:$0" case-sensitive="no" />
		</uri-rewrites>

		<!--
			Settings for the http request engine
		 -->		
		<http-request>
			<!-- 
				Sets the send/recv timeout in seconds.  The default
				is 0 (infinite), which is fine if you are not accessing
				external resources, as IIS's default handling will ensure
				that loopback requests complete one way or another...
			 -->
			<timeout>120</timeout>
		</http-request>
		
		<!--
			Extension function DLLs.
			These are cached, but are installed per configuration file (with inheritance and override-parents).
			There are no default extensions.
		 -->
		 <extensions override-parents="yes">
			<extension path="C:\Program Files\gnomon\bin\gnomonSessionExtension.dll"/>
			<extension path="C:\Program Files\gnomon\bin\gnomonSQLExtension.dll"/>
			<extension path="C:\Program Files\gnomon\bin\gnomonTidyExtension.dll"/>
		</extensions>
	</config>
	

<config> is the root node of the configuration file and contains all other elements.

This element contains the maximum number of bytes of POST data that gnomon is prepared to deal with. By default, the limit is 5Mb. If you want to disable POST data limiting you can indicate this explicitly with a value of 0). This may be applicable if you are using, e.g. Microsoft's URLScan to limit POST data at an earlier stage, but the double protection doesn't hurt.

If the maximum size of the POST data is exceeded, then gnomon will attempt to output an error message and will cease to read POST data. Unfortunately by this stage, IIS will have replied to the POST request with a '100 Continue' response (where applicable, basically all browsers these days). Now RFC2616 states:

8.2.2 Monitoring Connections for Error Status Messages

An HTTP/1.1 (or later) client sending a message-body SHOULD monitor the network connection for an error status while it is transmitting the request. If the client sees an error status, it SHOULD immediately cease transmitting the body.

However, it seems most clients DO NOT follow this sage advice, and will instead simply report that the server closed the connection. If this is a problem to you, then you will need something like Microsoft's URLScan ISAPI filter which is able to enforce the limit at an earlier stage in the process.

On a final note, if you are using ASP to handle large forms, then you should be aware of Q273482, PRB: "Request object, ASP 0107 (0x80004005)" Error When You Post a Form. In short "The size limit of each form field is exactly 102,399 bytes". If you really want to handle large forms from ASP, there are some 3rd party objects that will do this for you, or you can use Request.BinaryRead and handle the data yourself.

This node encapsulates the configuration for gnomon error handling.

The attribute warnings-as-errors enables you to report the XSLT warning stream from Xalan. By default,this stream is suppressed unless an error occurs in the page. Viewing warnings may help with debugging your XSLT.

The rest of this node is concerned with the custom error handling functionality that gnomon provides. This is modelled on the custom error documents built in to IIS. For each type of gnomon error that occurs, you may specify how the error document finally presented to the user is generated.

By default, error handling mechanisms are inherited from the parent configuration file. To clear all inherited error handling mechanisms (resetting them to the default pages generated by gnomon), then you can set the "override-parents" attribute to "yes". It is not generally necessary to do this, as any custom error handlers specified in a child configuration file will automatically override the value for that error handler that was specified in the parent configuration file.

			<handler code="TRANSFORM_FAILURE">
				<default/>
			</handler>
	

			<handler code="SERVER_TOO_BUSY">
				<file>c:\inetpub\wwwroot\gnomon\gnomon_too_busy.html</file>
			</handler>
	

			<handler code="STYLESHEET_COMPILE_FAILURE">
				<uri method="REDIRECT">http://www.myserver.com/compile_failure.html</uri>
			</handler>
	

			<handler code="STYLESHEET_COMPILE_FAILURE">
				<uri method="GET">/errors/gnomon_compile_failure.asp</uri>
			</handler>
	

			<handler code="TRANSFORM_FAILURE">
				<uri method="GET">/errors/gnomon_transform_failure.asp</uri>
			</handler>
	

					<errors>
						<error code="TRANSFORM_FAILURE">
							<source>xml-parser</source>
							<description>One of my nodes dropped off!</description>
							<uri>http://localhost/test.xml</uri>
							<line>23</line>
							<column>9</column>
						</error>
						<warning code="TRANSFORM_FAILURE">
							<source>xsl-processor</source>
							<description>A warning</description>
						</warning>
						<message code="TRANSFORM_FAILURE">
							<source>xsl-processor</source>
							<description>An interesting message</description>
						</message>
					</errors>
	

<cache> acts as a container for configuration settings describing how gnomon should cache included source documents.

The xpath expression attribute is used to select an attribute in XML documents which contains a list of HTTP methods to cache the document for. It is of interest to cache source documents for the transform when the XSLT is made dynamic via reference to a database or request state. Within the attribute (or node), the HTTP methods are provided in a comma separated list, e.g.:

<select-cache-methods xpath="/document/config/@cache-methods">

and in the source document:

<document> <config cache-methods="get,post"> </document>

The currently support methods are get and post.

This node encapsulates configuration for the stylesheets that are applied to XML documents. The basic mode of operation is to use any xml-stylesheet processing instructions encountered. Multiple occurences of these directives are allowed, but not well defined -- here gnomon applies all of the stylesheets as listed, in order. For multiple transforms, the resultant document of each intermediate transform must be a valid XML document.

This node tells gnomon how to fetch stylesheets. In the default mode of operation, then the stylesheet URI is mapped to a physical path first, and the stylesheet is read from disk. If your stylesheets reside on another server, then you can also get them with HTTP. This mode of operation was introduced with gnomon 1.1 -- previous versions always used HTTP to fetch stylesheets. The file method is substantially better performing than the HTTP method, even for a single server.

This directive, defaulting to 1, directs gnomon to look for and use any xml-stylesheet processing instructions that occur in the source document. Any xml-stylesheet instructions with a type that is not of text/xsl or application/xslt+xml is ignored.

This node provides an alternative (and more flexlible) method of determining which stylesheets to apply to the source document. This node is of lower precedence than the >use-processing-instruction>&. The xpath expression (e.g. xpath="/document/stylesheets") should select a node something like: <stylesheets override-parents="first,last"> <stylesheet href="some-stylesheet"/> <stylesheets> The override-parents attribute allows preventing application of the listed first, last or both default stylesheets (see below). Each stylesheet is applied in order, as for the xml-stylesheet processing instructions.

This node is a container for specifying any default stylesheets to be applied. Stylesheets are inserted before or after the list specified in the document, depending on whether they occur in the first or last container. It is not possible to override these stylesheets with processing instructions. Any stylesheets inherited from parents are inserted before any <first> stylesheets at this configuration level, and likewise any inherited stylesheets in the <last> container are inserted after any after any stylesheets at this configuration level. override-parents will clear any stylesheets from all parents, for those which appear in the first or last containers as specified in the attributes.

This container specifies stylesheets to insert before the stylesheets listed for the current document, using either processing instructions or the select-stylesheets instruction.

This container specifies stylesheets to insert after the stylesheets listed for the current document, using either processing instructions or the select-stylesheets instruction.

This node is listed under the first or last containers to give the location for a stylesheet.

This specifies the code page to use when interpreting post and query string data. For i18n, the most reasonable choice is some form of unicode, and for web pages, this usually means utf-8. Note that ASP usually interprets this data in the local codepage, to make ASP behave consistently with non-ASCII data, you should set the codepage explicitly. There are two ways of doing this, the first is with Session.CodePage (=65001 for utf-8), or better, with the metabase W3SVC/ASPCodepage property.

This section tells gnomon how to rewrite URIs that it needs to fetch. This is typically used for redirecting requests for the initial page to either a static resource, or a dynamic page produced by ASP or ASP.NET.

The rewrites use the boost::regex_merge algorithm, and are all applied in order. The default match rule rewrites all incoming requests for .acds pages to point to .xml pages stored on the local server. (These resources could come from an external server if required). It is:

<uri match="(https?://)([^:/]*)(:[^/]*)?(/)?([^?]*)\.acds(\?[^#?]*)?" format="?1http\://localhost$3/$5.xml$6:$0" case-sensitive="no" /gt;

The first portion (the match) approximately follows extended POSIX regular expression syntax. The format string directs how to rewrite the URI based on the match. The ?: construction is a conditional which operates as for the ?: operator in the C language. ?1 tests for the first subexpression of the match being non-empty. If it is true, then the URI is rewritten as indicated (part up to the :), otherwise the expression is left untouch ($0 contains the original input to the match).

The case-sensitive attribute (defaults to no) allows URIs to be matched regardless of case.

This section configures settings for the http requests made by gnomon. At present, only the send/recv timeouts can be set. The timeout values is in seconds, and must be contained within a timeout node, e.g. <timeout;>60</timeout;>. If the request times out then a URI_FETCH_ERROR is reported.

This section allows the use of gnomon extension DLLs. These are objects that can add additional extension functions into gnomon -- they allow it to be extended at run time. For more information on how to write extension dlls, see the gnomon extensions chapter By default there are no extension DLLs, and any extension DLLs are inherited from the parent level of the configuration hierarchy. You can prevent this behaviour by setting the override-parents attribute to the appropriate value.

Gnomon caches extension DLLs globally for speed purposes, but makes them available only at the configured scope.

Gnomon provides a number of built-in functions that allow accessing the HTTP request state and modifying the response state. These functions cover reading HTTP headers, query string and POST data, and cookies.

The namespace for the builtin extension functions is http://www.npsl.co.uk/gnomon. To use them, map this namespace to a prefix in your stylesheet and then call the function via its qualified name, for example:

	<?xml version="1.0"?>
	
	<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"
		xmlns:gnomon="http://www.npsl.co.uk/gnomon"
		xmlns:exsl="http://exslt.org/common"
		extension-element-prefixes="exsl gnomon">
	
		<xsl:output method="html" indent="yes" version="4.0" encoding="utf-8" media-type="text/html />
	
		<xsl:template match="/">
			<html>
				<head><title>Cookie test</title></head>
				<body>
				<p>The single value of the foo cookie is: <xsl:value-of select="gnomon:read-cookies('foo','')"/></p>
				</body>
			</html>
		</xsl:template>
	</xsl:stylesheet>

Gnomon's cookie handling is modelled on that of ASP (so that cookies can be accessed in the same way from ASP and ASP.NET pages). This means that cookies can have either a single value, or be considered as a key/value dictionary. These uses are mutually exclusive; setting a key/value pair will destroy any existing single value and vice versa.

ASP also limits itself to the ASCII character set, any characters with values outside the range 1-127 are silently discarded. Gnomon follows this model for compatibility. (Strictly speaking, cookies are opaque -- hence we could store any data, especially if it is URIEncoded to save confusing clients).

Gnomon also supports only the cookie attributes that ASP does. These are:

The cookies collection is updated in linear processing order. If a cookie is added or modified, then the new or modified cookie will be available to any included templates (even if they are generated from ASP or ASP.NET pages). This gives a consistent view on cookies.

read-cookies()

This function returns a nodeset representing all cookies in the request. A sample nodeset is:

	<cookies>
		<cookie name="foo" secure="0" path="/" value="single-value"/>
		<cookie name="foo2">
			<value name="key1" value="value1"/>
			<value name="key2" value="value2"/>
		</cookie>

read-cookies(cookie-name)

This function returns a nodeset representing a single cookie. The nodeset consists of a cookie node as shown above, or is empty if the cookie is not found.

read-cookies(cookie-name, key-name)

This function returns a string representing the named key from the cookie. If the key name is '' (empty string) then the single value of the cookie is returned. If the named key is not present, and empty string is returned.

read-cookies(cookie-name, attribute-or-key-name, attribute-flag)

This function allows the Expires, Domain, Path and Secure attributes to be read from the cookie. Note that if the cookie is sent by the client, typically these attributes are not reported -- you can read the back if they have been written by an earlier call to write-cookies or via a call to an ASP page. If the attribute-flag is zero, this function behaves exactly as for the two argument version above. If the attribute-flag is non-zero, this function will interpret the attribute-or-key-name parameter as an attribute name. The returned value is a string for Expires, Domain and Path or a number for Secure.

write-cookies(cookie-name, value)

This function sets the single value of the given cookie. If the cookie does not exist, a new cookie is created. This will destroy any dictionary values of the cookie.

write-cookies(cookie-name, key-name, vakue)

This function sets a key of the cookie to the specified value. This will destroy any single value previously set.

write-cookies(cookie-name, key-or-attribute-name, value, attribute-flag)

This function allows write access to the attributes of the cookie. If attribute-flag is 0, then this function behaves exactly as the three argument version above.

Gnomon allows full access to the GET (query string) and POST (form) data of a request. Currently only POST data in application/x-www-form-urlencoded is processed; that is multipart form encodings are not yet handled. (However, generally these are used for file uploads, so you would not want to process these in gnomon).

For non-ASCII data, handling of GET and POST data can require some care. There is little agreement about the codepage that such data should be sent in. The typical action of a web browser is to send data in the original encoding of the page. By default, ASP interprets such data in the local code page of the server (as can be seen, this is generally wrong). The preferred solution that I adopt is to send all pages in UTF-8, set the codepage for ASP to UTF-8, and configure gnomon to interpret URIEncoded data as UTF-8. You can pick a different codepage if you like; but the key to good inter-operation is a consistent choice! See the note on configuring ASP and gnomon's URI codepage for more information.

Gnomon gives a single overview on request data. That is query-string, post and template collections. POST data can be split per form to POST appropriate data back to different templates. For more information on gnomon templates, see the templates chapter. The request function can be limited to return data from individual templates and collections. Templates are identified by template-id (which, as discussed, is always avaialble as a parameter), and the collection by a letter:

The collections are searched and returned in the order specified in the search string (e.g. qfp). The search string is case-sensitive, and the request function will raise an error if any other value is specified. It is permissble, though pointless, to search a particular collection more than once.

Each item in a collection can have more than one value. (This can occur in real data for example in the case of multiple select lists). The values are considered as a vector, and can be accessed by index. Indexes start at zero.

request(search-string)

This function returns values for all templates from the given collections. The returned value is an XML fragment, which typically looks like:

	<request>
		<collection id="0">
			<query-string>
				<item name="foo" value="value1,value2">
					<value index="0">value1</value>
					<value index="1">value2</value>
				</item>
				<item name="bar" value="single-value">
					<value index="0">single-value</value>
				</item>
			</query-string>
		</collection>
	</request>

request(search-string, template-id)

This function returns values for the specified template from any given collections. The returned value is an XML fragment, which is as detailed above apart from the fact that the "collection" node is the root of the fragment.

request(search-string, template-id, key-name)

This function returns a string which is the value associated with the given key. For example, if the URI of a document is http://localhost/test.acds?foo=value&bar=value1&bar=value2 then request('q', 0, 'foo') returns 'value'. If multiple values are present for a given key, then they are returned as a comma separated list. Commas within values are not quoted, so you should use one of the other forms of this function (particularly the next one) if multiple values are of interest. For example, request('q', '0', 'bar') would return 'value1,value2'. If the key does not exist, an empty string is returned.

request(search-string, template-id, key-name, value-index)

This function returns the value with index value-index associated with key-name. This allows you to return individual items that are associated with the same key. If the key or index are not found, then an empty string is returned. As in the above example, request('q', 0, 'bar', 0) returns 'value1' and request('q', 0, 'bar', 1) returns 'value2'.

Gnomon provides access to CGI variables. See the documentation for the ASP.ServerVariables collection for more details on which variables exist. Note that all headers sent in the request in the server variables collection, and are renamed to HTTP_header, e.g. server-variables('HTTP_HOST') will return the the Host: header. (This is normal for CGI applications).

server-variables()

This function returns a nodeset containing all of the known CGI variables. A sample nodeset is:

	<server-variables>
		<variable name="APPL_MD_PATH" value="/LM/W3SVC/1/Root"/>
	</server-variables>

server-variables(variable-name)

This function returns the value of a single server variable. If the variable is not found then an empty string is returned.

parse-xml(xml-string)

This extension function parses an XML fragment and returns a nodeset containing the parsed XML. This allows you further process XML that is stored in strings using normal XSLT. This can be very useful if the XML has been retrieved by a database query. For example:

	<xsl:variable name="frag">
		<some-xml>
			<node/>
		</some-xml>
	</xsl:variable>
	<xsl:apply-templates select="gnomon:parse-xml($frag)"/>

parse-xml(xml-string, ignore-errors)

This function behaves exactly for the single argument form if ignore errors is not 1. Otherwise, rather than reporting any errors that arise during xml parsing, an empty nodeset is returned.

Gnomon provides a single global dictionary that can be used to store any XSL object. This violates the functional programming style of XSLT (as it could be argued does write-cookies) Since Xalan processes XSLT linearly, this works, and using dictionaries (and counters -- see below), you can make XSLT behave as a standard linear programming language. You can consider this a hack, but nonetheless, it's very useful.

dictionary()

This returns the entire contents of the dictionary as a nodeset.

dictionary(key)

This returns the object associated with key. This object may be any valid XSL object -- nodeset, boolean, result tree fragment, number or string.

dictionary(key, value)>

This associates the value with the key. As above the object may be any valid XSL object. For example:

	<xsl:variable name="dummy" select="gnomon:dictionary('foo',bar')"/>
	<xsl:variable name="foo" select="gnomon:dictionary('foo')"/>

This would store the value 'bar' in the variable 'foo'.

Gnomon provides a dictionary of named counters. Each counter has an initial value of zero. Counters, like dictionaries, allow linear programming in XSL, and can be considered simply as a useful hack. Counters are 32 bit signed integers, and may become negative.

counter(counter-name)

This returns the value of the named counter. All counters exist, and have an initial value of zero.

counter(counter-name,action ('inc'|'dec'))

This increments or decrements the named counter according to the specified action. The return value is the new value of the counter. If action is not inc or dec then an error is raised.

counter(counter-name,action ('inc','dec','set'),value)

This increments, decrements or sets the named counter. If the action is set, then the counter is given the specified value. If the action is inc or dec, then the counter is incremented or decremented by the given value. The function returns the new value of the counter. If the action is not inc or dec then an error is raised.

Gnomon provides a function for including XML documents that is similar to the XSL document() function, save for the fact that parameters can be passed to the included document. These parameters are accessible through the request function described earlier in this chapter. The included XML documents are gnomon as templates, this is described in detail in the chapter on templates.

include-xml(document-href, parameters)

The document-href specifies the URI of the included document. If this is a relative path then it is resolved relative to the parent document. The parameters specifies a nodeset containing a list of parameter nodes. The name attribute of these nodes identifies the name of the parameter, and the contents are its value. For example:

	<xsl:variable name="params">
		<parameter name="foo">bar</parameter>
	</xsl:variable>
	<xsl:variable name="dummy" select="gnomon:include-xml('../some-include.xml', $params)"/>

Gnomon has a number of settings that can be tuned to maximize performance. Whilst the default configuration works well, specific tuning for your application can provide significant benefits.

The settings that can be tuned are contained in the registry, and are read once at startup time. These settings cannot be modified whilst gnomon is running -- you will need to restart the web service in order to do this. Also note that by default these settings do not exist.

In order to understand how to best tune gnomon, you will need to understand a little of how it works internally. There are two basic concepts:

Note that there is not necessarily a 1-1 mapping between threads and requests. It is entirely possible to have more requests executing than threads: this is because the requests are processed asynchronously. When a request is not assigned to a thread, it is effectively dormant (generally waiting on network I/O).

Technical detail (not required to follow the rest of this section): since Xalan operates in a mode in which it cannot be interrupted to perform network I/O the request code is run in a separate fiber. Fibers are self scheduled threads, with lightweight context switches. When Xalan requests a document, we save the request state by switching fiber, start network I/O and return the thread that was executing the transformation to the pool. When the network I/O completes, then we switch the fiber back in and carry on where we left off.

By default, gnomon creates 8 worker threads per processor, and allows 64 concurrent requests. Thus, on a single CPU machine, 8 requests can be concurrently performing CPU work, with the other 56 blocked on network I/O or waiting for a pooled thread to become available to handle them.

Note that these settings are per instance of gnomon. It is possible to have multiple instances of gnomon if you have websites or virtual directories set to run in different processes. For example, if you have two high (isolated) applications you will be running two instances of gnomon, or if you have two websites with two different protection levels -- perhaps one low (IIS process) and one medium (pooled). You should bear this in mind when performance tuning and consider also setting the application protection levels differently.

To decide on the number of worker threads, you should take the following factors into account:

To decide on the number of concurrent requests, consider the following:

Here you can see that increasing the number of concurrent requests increases memory pressure on the server, which if pushed too far will lead to swapping to disk. This will considerably slow things down. However, you want enough concurrent requests to be executing so that the CPU is kept busy with work -- i.e. gnomon is not waiting on network I/O. Tuning this depends entirely on your application, i.e. the properties of the code generating the source XML.

Also note that increasing the number of worker threads beyond the number of concurrent requests will mean that there will always be idle threads in the pool.

Any requests that can't be handled immediately are placed into a queue. This is the case if the number of concurrently executing requests exceeds the configured maximum. If the backlog queue is exceeded, then a server SERVER_TOO_BUSY error is generated (and is handled by the error handling mechanism specified in the configuration file).

The goal when tuning the backlog queue length is to ensure that people do not have to wait too long for a server too busy message (say 10-15 seconds), but that outstanding requests are not rejected too early. The length of queue that you will want depends roughly on the average page generation time for your application. If the page generation time is very small, then you will want a longer backlog queue. If the page generation time is very larger, then you will want a shorter one. The best way to decide how long to make the backlog queue is to stress test your application with a large queue length, determine the average response time, and then set the queue length based on (Concurrent Requests * Desired Maximum Queuing Time) / Average Response Time.

As a point of interest, there was some experimentation to try to get gnomon to do this automatically; but it seemed that measurements of the current average response time was subject too much variation.

The configurable registry entires are stored under the registry key

HKEY_LOCAL_MACHINE\Software\NPSL\gnomon

This key will be created by default by the gnomon installer, or you can create it manually if it doesn't exist. Gnomon will start without this registry key using default settings.

Gnomon provides performance counters that can be used to give an overview of what it is doing at any one time. These performance counters are made available to Window's Performance Monitor as for any other performance counter. Note that until gnomon has started, these counters will not be visible. IIS does not start ISAPI extensions until at least one request has made, so if you are having trouble seeing the counters, make a page request first.

To view performance counters, start Performance Monitor (from Control Panel/Administrative Tools/Performance), request a page to ensure that gnomon is running, then click the '+' icon. The performance object is called 'gnomon XSLT processor' and should be visible in the list. Each performance counter provides detailed help. Click on the Explain... for a description. In addition, the available counters and their meanings are outlined below.

Note that if multiple instances of gnomon are running then the performance counters will be the aggregate of those used on all instances of gnomon. Also note that the average transformation time and last transformation time counters do not lock between instances of gnomon (and both are 64-bit), so in rare circumstances they may become corrupted and an erroneous value may be displayed temporarily. (This is not dangerous, merely cosmetic). Multiple instances of gnomon may be running if you have websites set to run in different processes, e.g. two high (isolated) sites or one low (IIS process) and one medium (pooled).

Bearing in mind the details outlined in the sections above, here is one way of approaching performance tuning.

Firstly, get hold of a copy of the freely available Microsoft Web Application Stress Tool. This is an excellent tool to help you stress test load your website and is useful in both eliciting problems and in load planning. Next, create an appropriate script in WAST to stress your site. Once you have this script setup and working, then you will want to decide what kind of load to tune for. Excellent resources for this are existing web and traffic logs. Also estimate the growth of this traffic with time to ensure that you have enough hardware to scale upwards.

When these numbers are determined, the stress level in WAST can be set according to the expected maximum load. Whilst the script is running, monitor the following gnomon performance counteres:

The goal of tuning is to maximise the Requests succeeded/sec figure whilst keeping the errors and too busy replies to a minimum. To tune the loopback request errors to be as low as possible, ensure that IIS itself is configured to handle the load that you are generating. See IIS documentation and MSDN for performance tuning IIS.

To tune concurrent requests and worker threads, take the factors outlined above into account to decide on some reasonable initial values. Start by using more concurrent requests than you think you will need, in order to tune the number of worker threads (bear in mind that these create additional memory pressures so do not increase the value too much). (Having more concurrent requests than are needed will prevent blocking on network I/O from affecting the test results).

Then, gradually decrease the number of threads (with at least one per processor) and the Requests succeded/sec figure should increase. This will also increase the variability of the response times, so you should decide on what balance of fairness and performance is acceptable. If you are using the session or sql extension, keep an eye on the CPU load here - if it begins to drop below 100% then you will need more threads as threads will be waiting for the database.

To tune concurrent requests, decrease the number of concurrent requests until the CPU load starts to decrease. When this occurs then requests are blocking on network I/O so you should increase the number again to just above this point. Using the minimum number of concurrent requests leaves the maximum available memory for the rest of the server.

To tune the too busy replies, you should use WAST to measure the average response time when gnomon is under load. To do this first ensure that there are no too busy replies by increasing the backlog queue to a sufficiently large number. The backlog queue takes memory, so don't increase it too far otherwise the artificial memory pressure on the server will affect the results. Then having measured this response time then you can use the formula (Concurrent Requests * Desired Maximum Queuing Time) / Average Response Time to set the backlog queue to be length to be equivalent to the desired maximum queueing time on average. Any request that would take longer than that time will be rejected with a "503 Service Unavailable" response.