To ensure that requests are distributed to only those origin servers that are available and can receive requests, Oracle Traffic Director monitors the availability and health of origin servers by sending health-check requests to all of the origin servers in a pool.
You can configure health-check parameters for an origin-server pool by using either the administration console or the CLI.
Note:
When you configure health-check settings for an origin-server pool, you are, in effect, modifying a configuration. So for the updated configuration to take effect in the Oracle Traffic Director instances, you should redeploy the configuration as described in Section 4.3, "Deploying a Configuration."
The CLI examples in this section are shown in shell mode (tadm>). For information about invoking the CLI shell, see Section 2.3.1, "Accessing the Command-Line Interface."
When Does Oracle Traffic Director Send Health-Check Requests?
When an Oracle Traffic Director instance starts, it performs an initial health check for all the origin servers in all of the configured origin-server pools.
If the initial health check indicates that an origin server is healthy, Oracle Traffic Director sends further health-check requests to an origin server only in the following situations:
The server has not served any request successfully for the entire duration of the previous health-check interval.
Dynamic discovery is enabled for this origin server pool. For more information, see Section 6.5, "Configuring an Oracle WebLogic Server Cluster as an Origin-Server Pool."
If a health check—either initial or subsequent—indicates that an origin server is not available, Oracle Traffic Director repeats the health check at the specified health-check interval.
Configurable Health-Check Settings
Table 14-1 lists the health-check settings that you can configure for each origin-server pool in a configuration.
Table 14-1 Health-Check Parameters
| Parameter | Default Value |
|---|---|
|
The type of connection—HTTP, TCP, or COMMAND—that Oracle Traffic Director should attempt with the origin server to determine its health.
|
HTTP |
|
The frequency at which health-check requests should be sent. |
30 seconds |
|
The duration after which a health-check request should be timed out if no response is received from the origin server. |
5 seconds |
|
The number of times that Oracle Traffic Director should attempt to connect to an origin server in the pool, before marking it as unavailable. |
5 |
|
The HTTP request method—GET or OPTIONS—that should be sent. |
OPTIONS |
|
The URI that should be sent for HTTP requests. |
/ |
|
For external connections, the path to the external executable to run. |
|
|
The HTTP response codes that Oracle Traffic Director can accept as indicators of a healthy origin server. By default, Oracle Traffic Director accepts response codes from |
|
|
For HTTP GET health-check requests, a regular expression for the response body that Oracle Traffic Director can accept as the indicator of a healthy origin server |
|
|
For HTTP GET health-check requests, the maximum number of bytes in the response body that Oracle Traffic Director should consider when comparing the response body with the specified acceptable response body. |
2048 |
When Is an Origin Server Considered Available and Healthy?
If the configured health-check connection type is TCP, an origin server is considered available if the connection is successfully established, indicating that the server is actively listening on its service port.
If the configured health-check connection type is HTTP, an origin server is considered available and health when all of the following conditions are fulfilled:
There is no error while sending the HTTP request.
The response is received before timeout period is reached.
The status code in the response matches any of the acceptable response codes, if specified.
By default, Oracle Traffic Director accepts response codes from 1xx to 4xx as indicators of a healthy origin server.
The response body matches the acceptable response body, if specified.
Configuring Health-Check Settings for Origin Servers Using the Administration Console
To view and change health-check settings origin servers in a pool by using the administration console, do the following:
Log in to the administration console, as described in Section 2.3.2, "Accessing the Administration Console."
Click the Configurations button that is situated at the upper left corner of the page.
A list of the available configurations is displayed.
Select the configuration for which you want to view or change origin-server health-check settings.
In the navigation pane, expand Origin-Server Pools, and select the origin-server pool for which you want to view or change health-check settings.
The Origin-Server Pools page is displayed. It shows a list of the origin-server pools that are defined for the configuration.
Click the name of the origin-server pool that you want to modify.
The Server Pool Settings page is displayed.
Go to the Advanced Settings section of the page.
Specify the parameters that you want to change.
On-screen help and prompts are provided for all of the parameters.
When you change the value in a field or tab out of a text field that you changed, the Save button near the upper right corner of the page is enabled.
At any time, you can discard the changes by clicking the Reset button.
After making the required changes, click Save.
A message, confirming that the updated configuration was saved, is displayed in the Console Messages pane.
In addition, the Deployment Pending message is displayed at the top of the main pane. You can either deploy the updated configuration immediately by clicking Deploy Changes, or you can do so later after making further changes as described in Section 4.3, "Deploying a Configuration."
Configuring Health-Check Settings for Origin Servers Using the CLI
To view the current health-check settings for an origin-server pool in a configuration, run the get-health-check-prop command, as shown in the following example:
tadm> get-health-check-prop --config=soa --origin-server-pool=osp1
response-body-match-size=2048
protocol=HTTP
interval=30
request-method=OPTIONS
failover-threshold=3
request-uri=/
dynamic-server-discovery=false
timeout=5
To change the health-check settings for an origin-server pool in a configuration, run the set-health-check-prop command.
For example, the following command changes the health-check interval to 60 seconds and the health-check timeout period to 10 seconds for the origin-server pool osp1 in the configuration soa.
tadm> set-health-check-prop --config=soa --origin-server-pool=osp1 interval=60 timeout=10
OTD-70201 Command 'set-health-check-prop' ran successfully.
For the updated configuration to take effect, you should deploy it to the Oracle Traffic Director instances by using the deploy-config command.
For more information about the commands mentioned in this section, see the Oracle Traffic Director Command-Line Reference or run the commands with the --help option.
Oracle Traffic Director supports a generic health check hook-up mechanism, so that you can write your own health check programs/scripts to monitor the health of specific origin servers. An external executable is especially useful for a protocol-level health check monitor for the origin servers.
If you configure Oracle Traffic Director to use an external executable to check the health of a server, Oracle Traffic Director periodically invokes the executable and passes certain parameters to it as arguments and environment variables. If the executable successfully returns a status code 0 before a timeout, Oracle Traffic Director sets the server's status to online. If the executable returns a value other than zero or a timeout occurs before the execution ends, Oracle Traffic Director immediately sets the server status to offline without retrying, and terminates the execution in the timeout case. There are different reasons why the executable could return a non-zero status code, including a core dump, signal termination, or the logic of external executable itself. Oracle Traffic Director marks the server offline whenever the return status is non-zero.
Also, Oracle Traffic Director captures the standard output and standard error from the executable and logs the messages into the event log (server log).
The external executable handles the actual health check jobs, including establishing connection to the origin server, sending/receiving request/response, dealing with SSL (if applicable), retry logic (if required), and so on. The executable is expected to exit with a status 0 after it finishes the health check operation and wants to set the server status to online. If the executable wants to have some messages logged in the event log, it should print those messages to standard output.
To configure the health-check settings to use an external executable for an origin-server pool in a configuration, run the set-health-check-prop command.
For example, the following command sets the health-check method to COMMAND, and specifies a path of /path/myhcscript for the external health-check executable. The interval, and timeout properties are also specified.
tadm> set-health-check-prop --user=admin --host=admin.example.com --password-file=./admin.passwd --port=8989 --no-prompt --config=www.example.org --origin-server-pool=test-pool protocol=COMMAND interval=25 timeout=4 command=/path/myhcscript
OTD-70201 Command 'set-health-check-prop' ran successfully.
Note:
In case of an HTTP type of origin server pool, theCOMMAND health check protocol is not considered if:
the origin server type is UNDETECTED or,
the origin server type is WLS and dynamic discovery is set.
For the updated configuration to take effect, you should deploy it to the Oracle Traffic Director instances by using the deploy-config command.
Oracle Traffic Director passes parameters to the external health check executable in two ways. In particular, Oracle Traffic Director passes the origin server host, origin server port, and timeout value via arguments, and passes all the existing environment variables as well as ORACLE_HOME, INSTANCE_HOME, INSTANCE_NAME, DOMAIN_HOME, and OTD_LOG_LEVEL as environment variables. The argument parameters are passed in the format of command line options, as shown in the following example command:
/path/myhcscript -h server1.myserver.com -p 389 -t 10
Where, -h, -p, and -t stand for host, port, and timeout respectively.
Table 14-2 Argument Parameters
| Option | Meaning |
|---|---|
|
|
Origin server host. |
|
|
Origin server port. |
|
|
Health-check timeout. |
You can pass other parameters to the external executable by specifying additional option arguments in the parameter command:
/path/myhcscript --secure -d /dbpath
Correspondingly, Oracle Traffic Director passes those additional arguments to the external executable:
/path/myhcscript --secure -d /dbpath -h server1.myserver.com -p 389 -t 10
Oracle Traffic Director does not automatically pass the origin server port type (for example, LDAP over SSL) to the executable. If the type information is needed in the executable, you can specify the type information in the command string as an additional argument (as shown in the example above) or have the type hard-coded or obtained from other resource (for example, its own configuration file or environment variable) in their health check program/script.
Furthermore, it is recommended that the external executable takes the timeout value into account and tries to complete execution and return status before timeout. If timeout occurs but execution is not complete, Oracle Traffic Director terminates the process and set the server status to offline.
Oracle Traffic Director passes the configured logging level to the external program via the environment variable OTD_LOG_LEVEL, and the value of the environment variable is an integer. In the external executable, you can customize the amount of logging messages based on the logging level. The following table defines the mapping between the Oracle Traffic Director logging levels and the argument values.
Table 14-3 Mapping Oracle Traffic Director Logging Levels and Argument Values
| Value | Oracle Traffic Director Logging Level |
|---|---|
|
0 |
NOTIFICATION:1 or higher |
|
1 |
TRACE:1 |
|
2 |
TRACE:16 |
|
3 |
TRACE:32 |
Oracle Traffic Director logs contents in both standard output and the standard error of the external executable in a single log entry in the server log. If the exit status of the command health check script is 0, the messages are logged at TRACE:1 level. Otherwise, standard output is logged at NOTIFICATION:1 level and the standard error is logged at WARNING:1 level.