SOA Service Configuration Files in Windows HPC Server 2008 R2
Updated: February 2011
Applies To: Windows HPC Server 2008 R2
This topic describes common settings that you can configure in the service registration file for SOA services that you install on a Windows® HPC Server 2008 R2 cluster. The service configuration file is an XML file that is used to register a service on the cluster and configure service behavior. For example, broker behavior such as monitoring, message throttling, and load balancing can be defined at the individual service level.
At a minimum, the file must specify the registration information for the service, such as the path to the DLL for the service. The service configuration file must be named servicename.config, where the servicename is the same as that passed into the SessionStartInfo constructor.
Microsoft® HPC Pack 2008 R2 includes a sample service that is named CcpEchoSvc. CcpEchoSvc is a simple, built-in service that can be used with the diagnostics tests to verify SOA functionality on the cluster. You can also use the service configuration file for CcpEchoSvc as an example when you create or modify a configuration file.
.gif) Note |
|---|
| Cluster administrators must have write permissions to the service configuration files to make changes to the service registration and configuration settings. For information about deploying the configuration file to the cluster, see Deploy the SOA Service DLLs to a Windows HPC 2008 R2 Cluster. |
This topic includes the following sections:
Service registration settings
Broker settings
SOA service versioning
Service registration settings
You provide the registration information for a service inside the <microsoft.Hpc.Session.ServiceRegistration> section which contains the <service> element.
For example, the following XML code shows how the service registration settings are defined in the service configuration file for CcpEchoSvc (the built-in sample service in Windows HPC Server 2008 R2).
<microsoft.Hpc.Session.ServiceRegistration>
<service assembly="%CCP_HOME%bin\EchoSvcLib.dll"
contract="EchoSvcLib.IEchoSvc"
type="EchoSvcLib.EchoSvc"
includeExceptionDetailInFaults="true"
maxConcurrentCalls="0"
maxMessageSize="65536"
serviceInitializationTimeout="60000" >
<!--Below is a sample for adding environment variables to the service-->
<environmentVariables>
<add name="myname1" value="myvalue1"/>
<add name="myname2" value="myvalue2"/>
</environmentVariables>
</service>
The following table describes the service registration attributes:
| <service> Attribute | Description | Default value | ||
|---|---|---|---|---|
|
The full path to the service DLL. This can be a path to a shared folder on the cluster, or it can be a local path on each compute node. For example:
Required. |
None |
||
|
The interface of the service (WCF contract). Optional if there is only one interface in the service DLL. |
None |
||
|
The class that implements the WCF contract. Optional if there is only one interface in the service DLL. |
None |
||
|
The architecture on which your WCF service can run. The possible values are x86 and x64 (any other value is ignored, and the default is used). Optional. |
X64 |
||
|
If
For more information, see IncludeExceptionDetailInFaults Property. |
|
||
|
The maximum number of messages actively processing across a service host. A value of 0 indicates that the maximum should be automatically calculated based on the service capacity (number of CPU cores) of each service host. Optional. |
0 |
||
|
The maximum size of the message file, in bytes. For durable sessions, the upper limit for message size is 4MB because of the limitation of MSMQ. Optional. |
65,536 bytes |
||
|
The maximum length of time that the broker attempts to load the service on a service host. If an If the broker cannot connect successfully to the service, the broker adds the node to the excluded nodes list for the job. When the excluded nodes limit is reached, the session fails. Optional. |
60,000 milliseconds |
||
|
Environment variables used by your service. Optional. |
None |
.gif)
WarnungBroker settings
You can customize how the broker interacts with a service by defining the broker monitoring settings in the service configuration file. This allows you to define broker behavior such as monitoring, message throttling, and load balancing at the individual service level.
The <Microsoft.Hpc.Broker> section contains the <monitor> element and the <loadBalancing> element. The attributes in these elements determine how the broker handles sessions for the service. The broker uses the default setting for any attribute that is not specified.
A subset of the broker monitoring settings can also be defined by using the SessionStartInfo.BrokerSettingsInfo class when the client application creates a session. Values provided in the SessionStartInfo.BrokerSettingsInfo class override the values that are specified in the service configuration file.
Monitoring settings
The following XML code shows how the broker monitoring attributes are defined in the service configuration file for CcpEchoSvc.
<monitor messageThrottleStartThreshold="4096"
messageThrottleStopThreshold="3072"
loadSamplingInterval="1000"
allocationAdjustInterval="30000"
clientIdleTimeout="300000"
sessionIdleTimeout="300000"
statusUpdateInterval="15000"
clientBrokerHeartbeatInterval="20000"
clientBrokerHeartbeatRetryCount="3" />
The following table describes the broker monitoring attributes and their default values:
| <monitor> Attribute | Description | Default values |
|---|---|---|
|
The amount of memory that the broker queue requires is (messageThrottleStartThreshold) * (sizeOfRequest). If you have throttling limits set too high and your messages are too big, then the broker node can run out of memory. For example, if you set the limit to 400,000, and you expect 64 KB messages, the broker would require 25.6 GB of memory to hold the request queue. If the throttle settings are too low, nodes can be underutilized due to insufficient message throughput. |
Throttle start: 4,096 Throttle stop: 3,072 |
|
The amount of time between load sampling passes. During a load sampling pass, the broker checks the request queue to update performance counters for a session, including the number of waiting requests. You can increase this number to minimize management overhead. You might want to decrease this number if the service processes very short-running requests. Unit: milliseconds |
1,000 milliseconds (1 second) |
|
The amount of time between allocation adjustment passes. During an adjustment pass, the broker updates job properties and evaluates the Target Resource Count for a session based on the load sampling metrics gathered within the adjust interval. The job scheduler uses the Target Resource Count property to help determine how many service hosts to allocate to the session. Automatic allocation adjustment can help increase cluster utilization. For example, the job scheduler can shrink an idle session to its minimum resources. However, it can take time for the resources to grow when the session becomes active again. To disable allocation adjustment, you can set this property to a value of -1. Unit: milliseconds |
30,000 milliseconds (30 seconds) |
|
After a client application connects to a session, if the client does not have any activity and there are no pending requests for the client within the specified amount of time, the broker closes the connection to the client, but it does not close the session. Unit: milliseconds |
300,000 milliseconds (5 minutes) |
|
When all the clients for the session are idle (timed out), if no more client applications are connected within this timeout period, the broker closes the session. You can extend this period if users want to keep a session open and send several batches of requests within the same session. This avoids the start-up time of creating a new session and receiving new resources. With an HTTP binding, Unit: milliseconds |
300,000 milliseconds (5 minutes) |
|
The timer interval for the broker to publish service statistics to the job. Unit: milliseconds |
15,000 milliseconds (15 seconds) |
|
These setting apply to clients of type The instance of If the broker service does not respond, the client retries up to the number of times specified by the In some cases, the client might try to create a new session (up to the job and task retry counts that are set for the HPC Job Scheduler Service). |
Interval: 20,000 milliseconds (20 seconds) Retry count: 3 |
Load balancing settings
The following XML code shows how the broker load balancing attributes are defined in the service configuration file for CcpEchoSvc.
<loadBalancing messageResendLimit="3"
serviceRequestPrefetchCount="1"
serviceOperationTimeout="86400000"
endpointNotFoundRetryPeriod="300000"/>
The following table describes the broker load balancing attributes and their default values:
| <loadBalancing> Attribute | Description | Default values |
|---|---|---|
|
The number of times that the broker will resend a message. Sessions that are running on Azure Worker Nodes are more likely to reach the message resend limits than sessions that are running on on-premise nodes, especially if the HPC Job Scheduler Service is running in Balanced mode. If you see messages fail on your Azure Worker Nodes, increase the message resend limit. |
3 |
|
The number of requests that can be pending for each service instance. For example, if the prefetch count is set to 1, two requests are sent to each service instance. One request starts processing immediately, and the second ‘prefetched’ request starts processing when the first requests is finished. If the count is too low, nodes will be idle as they wait for incoming requests (for example, 0 or a small number for very short running requests). If the count is too high, then some nodes might become idle while there are unprocessed requests waiting on other nodes. |
1 |
|
The length of time that the broker waits for the service to finish processing the message. |
86,400,000 milliseconds (24 hours) |
|
If an |
30,000 milliseconds (30 seconds) |
SOA service versioning
A SOA service can opt into versioning by appending a version number to the service configuration file name. The expected format is: servicename_major.minor.config. The version must include the major and minor portions of the version identifier and no further sub-versions. For example, the configuration file for version 1.0 of Microsoft.Hpc.Excel.ExcelService service is named Microsoft.Hpc.Excel.ExcelService_1.0.config.
The SOA client application can select which version of a service to use by specifying the SessionStartInfo.ServiceVersion property when creating the session. If the client does not specify a version, the latest installed version is used and returned in the SessionBase.ServiceVersion property after the session is created. If the specified version is not found on the cluster, the cluster returns a session exception error message.
SOA client applications that support multiple versions of a SOA service can use the SessionBase.GetServiceVersions method to check the versions of the service that are available on the HPC cluster before using version-specific features of the service. The client application can programmatically select a version, or present the options to the user.