System Management Tools

C H A P T E R 4

Content Delivery Server provides tools to monitor and manage your system. This section describes the following tools:

Diagnostic Tool

License Auditing Tool

4.1 Diagnostic Tool

A diagnostic tool is provided with Content Delivery Server to report information about the system and the environment when problems occur. Use this tool to obtain diagnostic information for the following system components:

Application server

Content Delivery Server configuration

Java virtual machine

Database

Operating System

4.1.1 Command Syntax

The diagnostic tool cdsdiag is located in the $CDS_HOME/bin directory. Run the tool using the following command:

cdsdiag [options] -component

The following table describes the valid options. TABLE 4-2 describes the valid components.

TABLE 4-1 Diagnostic Tool Command Options
Option	Description
`-f` [file]	Name of the file to which the generated output is written. Include the path if the file is not in the current directory. If `-all` is specified as the component, the file name is the name of the TAR archive that contains the reports for different types of diagnostics. If no file name is specified, the data is written to standard output (`stdout`).
`-d` deployment	Name of the deployment for which diagnostic information is requested. If no deployment is specified, the default deployment specified for the `DEFAULT_DEPL` property in the `init_env.sh` file is used.
`-w`	Flag that indicates that the output file is to be overwritten. If not specified, new data is appended to data already in the file. This option is meaningful only if the `-f` option is also used. Note - This option is ignored if `-all` is specified for the component. The TAR file always rewrites the previous file unless the `-i` option is used.
`-i`	Flag that indicates that an index is to be added to the name of the output file. Each time the diagnostic tool is run using the same file name, the index is incremented by one and a new file is created. For example, if you specify `diaginfo` as the file name in three executions of the diagnostic tool, you have the following files after the third execution: `diaginfo.1.tar` `diaginfo.2.tar` `diaginfo.3.tar` This option is meaningful only if the `-f` option is also used and the component is `all`.

The following table describes the valid components.

TABLE 4-2 Diagnostic Tool Component Values
Value	Description
`all`	Provides all information for all components.
`appserv`	Provides information about the application server. See Section 4.1.2.1, Application Server Diagnostics.
`conf`	Provides information on the current configuration of Content Delivery Server. See `Section 4.1.2.2, Content Delivery Server Configuration`.
`jdkstat`	Provides information about the Java virtual machine. See Section 4.1.2.3, Java Virtual Machine Diagnostics.
`oracle` task	Provides information about the database based on the value specified for task. The following values are valid for task: `all` - Provides all information for the database. `config` - Provides information on the database configuration. `instance` - Provides information on the instance state. `memory` - Provides information on memory usage and cache hit rates. `session` - Provides information on the database sessions. `storage` - Provides information on storage. `rowcount` - Provides information on the number of rows in critical tables. `help` - Lists the valid values for task. See Section 4.1.2.4, Database Diagnostics.
`osstat`	Provides information about the operating system. See Section 4.1.2.5, Operating System Diagnostics.

4.1.2 Component Diagnostics

The information provided by the diagnostic tool depends on the component specified in the diagnostic tool command. The following sections describe the information by component.

Use the following command to generate all information for all components:

cdsdiag [options] -all

The valid options are described in TABLE 4-1.

Note - If you are using WebLogic Server, run this command for all diagnostics only when Content Delivery Server is not being heavily used. Otherwise, you risk bringing down the system.

4.1.2.1 Application Server Diagnostics

Content Delivery Server must be running before you use the diagnostic tool to get information on the application server. Use the following command to generate the diagnostic information:

cdsdiag [options] -appserv

The valid options are described in TABLE 4-1.

The following information is provided:

JMS server statistics:

Current and peak number of JMS messages

Current and peak number of sent bytes

Current and peak number of JMS message consumers

Number of active transactions created by the Java Transaction API

Diagnostic information for the Java virtual machine, only if using WebLogic Server

4.1.2.2 Content Delivery Server Configuration

Use the following command to generate diagnostic information about the Content Delivery Server configuration:

cdsdiag [options] -conf

The valid options are described in TABLE 4-1.

The following information is provided:

Version and build number for the current deployment of Content Delivery Server

Current values for the properties in the following files:

$CDS_HOME/deployment/deployment-name/conf/CDS.properties

$CDS_HOME/cfg/$DEFAULT_CONFIG (the default deployment configuration file)

$CDS_HOME/cfg/$DEFAULT_DB (the default database configuration file)

Current values for the following environment variables:

$BEA_HOME

$WL_HOME

$WL_JAVA_HOME

$SUN_AS_JAVA_HOME

$DEFAULT_CONFIG

$DEFAULT_DB

$DEFAULT_DEPL

4.1.2.3 Java Virtual Machine Diagnostics

Use the following command to generate diagnostic information for the Java virtual machine:

cdsdiag [options] -jdkstat

The valid options are described in TABLE 4-1.

The following information is provided:

Java virtual machine arguments

Number of active threads for Content Delivery Server

Free heap memory and maximum heap memory

Stack traces for threads

By default, Java virtual machine diagnostics are written to standard output for the command window in which Content Delivery Server is running. Use the -f option to write the diagnostics to a file. Use the log filter utility cdslogfilter.pl when Content Delivery Server is started to write the diagnostic information to the window in which the diagnostic tool is executed, for example:

cdse starterserver | cdslogfilter.pl [options]

See Section 4.1.3, Log Filter Utility more for information.

Note - If you are using WebLogic Server, run this command for Java virtual machine diagnostics only when Content Delivery Server is not being heavily used. Otherwise, you risk bringing down the system. With WebLogic Server, some Java virtual machine information is available through the application server diagnostics.

4.1.2.4 Database Diagnostics

Use the following command to generate diagnostic information for the database:

cdsdiag [options] -oracle task

The valid options are described in TABLE 4-1.

The information provided about the database is based on the value specified for task. The following values are valid:

all. Provides all information for the database.

config. Provides information on the database configuration.

instance. Provides information on the instance state.

memory. Provides information on memory usage and cache hit rates.

session. Provides information on the database sessions.

storage. Provides information on storage.

rowcount. Provides information on the number of rows in critical tables.

help. Lists the valid values for task.

4.1.2.5 Operating System Diagnostics

Use the following command to generate diagnostic information for the operating system:

cdsdiag [options] -osstat

The valid options are described in TABLE 4-1.

The following information is provided:

Network state

File system state

Stack traces for all processes related to Content Delivery Server

Disk space

List of currently open files and connections

The diagnostic tool uses the following system utilities to gather the information. If one of the utilities is not available or is not configured correctly, warnings might be generated and the corresponding information might not be provided.

netstat

ifconfig

df

ps

lsof

Note - If you receive errors from the lsof utility, make sure that you are running the latest version, which is available at http://people.freebsd.org/~abe/. Also, if the diagnostic tool is run by a non-privileged user, the s-bit must be set for the lsof utility. To set the s-bit, use the command chmod u+s lsof.

4.1.3 Log Filter Utility

The log filter utility captures the output of a Java virtual machine thread dump, and is called by the diagnostic tool when Java virtual machine diagnostics are requested. See Section 4.1.2.3, Java Virtual Machine Diagnostics for an example of how the utility is used.

This utility acts as a proxy for the output of another process and is not intended to be run as a stand-alone process. Use this utility whenever you want to filter a Java virtual machine thread dump from a Java virtual machine process. The utility is a script written in Perl and requires a Perl interpreter for execution.

The log filter utility cdslogfilter.pl is located in the $CDS_HOME/bin directory. Run the utility using the following command:

cdslogfilter.pl [options]

The following table describes the valid options.

TABLE 4-3 Log Filter Utility Options
Option	Description
`-v`	Flag that indicates that all the data from the incoming pipe is printed to `stdout` as well as to a file.
`-f` file	Name of the file to which the output is written. The default is `$CDS_HOME/.jvmdump`. Note - The diagnostic tool requires that the default file name be used. Do not use this option if you are using the log filter utility with the diagnostic tool.

4.1.4 Running the Diagnostic Tool on HP-UX

The option to obtain information about the operating system, -osstat, is currently not supported on the HP-UX platform.

For other options of the diagnostic tool to work, use the following code to create a wrapper script for the ps command.

$ cat > /ups.sh << _EOF_
#!/bin/sh
# translates BSD ps in HP-UX ps
[ -z "$1" ] && { ps ; exit $?; }
[ "$1" = "auxww" -o "$1" = "-auxww" ] && { ps -efx; exit $?; }
ps -xp $1
exit $?
_EOF_
$ chmod +x /ups.sh

Change the default locations for some of the system commands in the diagnostic tool itself using the following steps:

1. Open the $CDS_HOME/bin/cdsdiag file for edit.

2. Find the line that starts with TAIL= and replace it with TAIL=/usr/bin/tail.

3. Find the line that starts with AWK= and replace it with AWK=/usr/bin/awk.

4. Find the line that starts with UPS= and replace it with UPS=/ups.sh.

If you saved the wrapper script to a different location, specify that location in place of /ups.sh.

5. Save your changes.

4.2 License Auditing Tool

A license auditing tool is provided with Content Delivery Server to generate a report on system usage. The purpose of this tool is to monitor system usage to ensure that usage is within the bounds of the license agreement. This tool is run automatically every month and at the end of every license period. You can also run the tool manually to generate a report for a specific time period.

Auditing data is generated by the Event Service for the Vending Manager with which the Event Service is associated. Monthly data is stored locally in a file. Data generated at the end of a license period or by manual execution is emailed to an address that you specify.

4.2.1 Configuration

To ensure accurate reporting by the license auditing tool, set the properties described in the following table. These properties are in the License.properties file in the $CDS_HOME/deployment/deployment-name/conf directory. Set these properties for each deployment.

TABLE 4-4 Properties for the License Auditing Tool
Property	Description
`license.disable`	Flag that indicates whether to run the tool automatically. Set to `true` to disable automatic reporting. Note - Set this property to `false` for Vending Manager deployments. Set this property to `true` for a Catalog Manager deployment. Also, disable the licensing tool for all but one instance of the Event Service when you have multiple instances running for redundancy purposes.
`license.model`	License model specified in the license agreement under which Content Delivery Server is running. Use one of the following values: Active Subscribers. License is based on the number of active subscribers. An active subscriber is one who downloads content the number of time specified for `license.download_count` in the period specified for `license.period`. Transactional. License is based on the number of downloads in the period specified for `license.period`. Note - Both models count the number of downloads that were initiated. No adjustment is made for refunds, purchases, or content for which the pricing model allows unlimited downloads.
`license.download_count`	Number of downloads required by a subscriber in the period specified for `license.period` for the subscriber to be considered an active subscriber. This property is meaningful only if `license.model` is set to `Active Subscribers`.
`license.period`	Number of days in a license period. Note - 30 days is interpreted as one month, regardless of the number of days in a given month. 60 days is interpreted as two months, 90 days is interpreted as three months, 180 days is interpreted as six months, and 365 days is interpreted as one year.
`license.start_date`	Date on which the license becomes active. Enter a date in the format mm/dd/yyyy. Leading zeroes are not required for the month or day. For example, 6/7/2007 is a valid date.
`license.organization`	Name of the organization associated with the Vending Manager for which the report is generated. This value is included in the report that is sent by email.
`license.smtp.address`	Address to which the report is sent at the end of each license period or when the tool is run manually. See Section 10.1, “Configure the Mail Service,” in the Sun Java System Content Delivery Server Integration and Configuration Guide for information on setting up the mail service that you want to use.

4.2.2 Execution

If automatic reporting is enabled (the license.disabled property is set to false), the Event Service triggers the license auditing tool once each month and at the end of a license period. The license auditing tool can also be executed manually. The properties referred to throughout this section are defined in TABLE 4-4.

4.2.2.1 Monthly Execution

The first time the Event Service is started, an audit entry is generated for every month from the date specified for the license.start_date property to the current date. Subsequently, the license auditing tool runs monthly on the day of the month that corresponds to the license.start_date property. For example, if the start date is set to 6/7/2007, the license auditing tool runs on the 7th of each month.

The monthly report contains an entry for each month since the license start date. Depending on the license model, each entry contains either the number of active subscribers or the number of transactions for the month. Entries are written to the License.txt file in the $CDS_HOME/deployment/deployment-name/logs directory. If this file is not found, the tool recreates the file and regenerates the data for all past months.

4.2.2.2 End-of-Period Execution

The length of a reporting period is specified in the license.period property. Beginning with the license start date, the Event Service triggers the license auditing tool at the end of each period. The report generated contains either the number of active subscribers or the number of transactions for the period, depending on the license model. This information is sent to the email address specified for the license.smtp.address property.

4.2.2.3 Manual Execution

You can generate a manual report at any time using the following command:

cdsi license [-deployment deployment-name] [-date date]

The following table describes the optional arguments.

TABLE 4-5 License Auditing Tool Command Arguments
Argument	Description
deployment-name	The name of the deployment for which the tool is run. If no name is specified, the value of the `DEFAULT_DEPL` variable in the `init_env.sh` file is used.
date	The date in the format mm/yyyy for which the report is to be run. The information returned is for the period that contains the date specified. For example, if the period is 90 days beginning 1/1/2007 and 8/2007 is entered as the date, information for the period between 7/1/2007 and 9/30/2007 is returned. If no date is specified, the current date is used.

Content Delivery Server must be running when you execute the command. The license report is obtained from the Event Service in the specified deployment.

The report generated contains either the number of active subscribers or the number of transactions for the period that contains the date specified. The type of data reported depends on the license model. The information is sent to the email address specified for the license.smtp.address property.