Health Center configuration properties

You can modify the behavior of the monitoring agent by using configuration properties, such as the port number to use to connect to the client. The format of the property varies depending on the way that you specify the property. If you are using IBM® Bluemix®, you cannot configure the agent that is provided as part of the Bluemix runtime environments.

The properties listed here apply to Java™ applications. For other applications, such as Node.js applications, the following statements apply:

Some of these properties might apply, but could have different default values.
Some of these properties might not apply.
Other properties that are not listed here might be available.

For information about the properties that are available to Node.js applications, see the documentation for the Node Application Metrics module.

If you specify a property that is not supported for your application type, it is ignored.

Property format

Properties consist of a property name and a value, separated by an equals sign (=). You usually set monitoring agent properties in a properties file. For Java applications, you can also set properties on the command line when you start the agent.

Property formats for Java applications

The format of the property varies depending on the method you use to specify it:

System property format, for example com.ibm.java.diagnostics.healthcenter.agent.port=1980. Use this format in the Health Center properties file, or with the -D option of the Java command.
-Xhealthcenter format, for example port=1980. Use this format with the -Xhealthcenter option of the Java command when you start the agent and the application at the same time, or as a parameter to the Java command that you use to attach the agent to a JVM that is already running. In this format, you can use a colon (:) to separate the property name and value instead of the equal sign (=).

For more information about setting properties, see Configuring the monitoring agent.

Properties

Health Center includes the following configurable properties:

Client/agent connection properties

You can choose the technology that is used for communicating between the client and the agent. You might also have to set appropriate port numbers.

com.ibm.diagnostics.healthcenter.headless: Set to on to enable the agent to store its collected data in files rather than sending it to the client. For more information, see the headless option of the com.ibm.java.diagnostics.healthcenter.data.collection.level property. The default value is off.
com.ibm.diagnostics.healthcenter.jmx: Set to on to enable the client to communicate with the agent by using a JMX connection. This property is set to on by default.
com.ibm.diagnostics.healthcenter.mqtt: Set to on to enable the client to communicate with the agent by using an MQTT broker. The default value is off. Due to platform limitations, MQTT connections are currently unavailable for z/OS®.

Note: For Java applications, the previous three options are overridden by the com.ibm.java.diagnostics.healthcenter.data.collection.level property. For example, if you set the com.ibm.java.diagnostics.healthcenter.data.collection.level property to headless, the com.ibm.diagnostics.healthcenter.jmx and com.ibm.diagnostics.healthcenter.mqtt properties are set to off.

com.ibm.diagnostics.healthcenter.mqtt.broker.host

com.ibm.diagnostics.healthcenter.mqtt.broker.port

Set the MQTT broker host name and port.

For MQTT client-agent connections, these properties must match the host name and port number for your MQTT broker. Refer to the documentation for your broker for information about setting a host name and port number.

If the properties do not match, the client and agent cannot use the MQTT broker to communicate with each other. The default values are as follows:

com.ibm.diagnostics.healthcenter.mqtt.broker.host=localhost
com.ibm.diagnostics.healthcenter.mqtt.broker.port=1883

com.ibm.java.diagnostics.healthcenter.agent.port

Sets the JMX port number.

For JMX client-agent connections (the default), the client uses port 1972 by default for communicating with the agent. If the client cannot use port 1972, it increments the port number and tries again, for up to 100 attempts. You can override the first port number that the agent tries to use.

If you set the port number in the properties file, the port is changed permanently. If you want to change the port temporarily, specify the port on the command line instead.

Note: If you have a firewall between the client and the agent, ensure that the required ports are open.

com.ibm.java.diagnostics.healthcenter.agent.iiop.port

Sets the IIOP port number.

By default, the Health Center agent uses the IIOP protocol for communicating with the Health Center client over a JMX connection. When this protocol is used, the Health Center client uses a second port for communication with the object request broker (ORB) on the machine that is running the monitored application. Usually, you do not have to be aware of this second port. However, if you have a firewall between the client and the agent, you must know the port number so that you can open that port in the firewall. Use this system property to specify the port number.

com.ibm.java.diagnostics.healthcenter.agent.transport

Sets the transport protocol to use for the connection between the client and the agent, either IIOP or JRMP. If you are using Health Center version 1.3.0 or later with WebSphere® Application Server for z/OS, set this property to jrmp. The default value is iiop.

Security properties

You can set the level of security for the client/agent connection.

com.ibm.diagnostics.healthcenter.mqtt.broker.user
com.ibm.diagnostics.healthcenter.mqtt.broker.pass: For MQTT client-agent connections, these properties must match the user name and password for your MQTT broker. Refer to the documentation for your broker for information about setting these credentials.
Note: The password is saved as plain text.
com.ibm.java.diagnostics.healthcenter.agent.authentication.file
com.ibm.java.diagnostics.healthcenter.agent.authorization.file: Sets the MBean authentication and authorization file locations.; You can secure a JMX connection in Health Center by using MBean authentication. This authentication requires a user name and password when the Health Center client connects to the agent. These credentials are stored in an authentication file on the machine that is running the agent. MBean authentication also requires an authorization file, which defines the access for the user name in the authentication file. Use these properties to specify the location of the authentication and authorization files.; For more information about Health Center security, see Securing Health Center.
com.ibm.java.diagnostics.healthcenter.agent.ssl.keyStore
com.ibm.java.diagnostics.healthcenter.agent.ssl.keyStorePassword
com.ibm.java.diagnostics.healthcenter.agent.ssl.keyStoreCertificatePassword: Set the location (path and name), password, and certificate password of the SSL keystore for the agent, if you are using an SSL connection. For more information about Health Center security, see Securing Health Center.

Agent collection mode properties

These properties define the collection mode that the agents starts in. For example, you can set the agent to start collecting data immediately, or only when a client connects to it.

com.ibm.java.diagnostics.healthcenter.data.collection.level

This property has the following values:

off

Specifies no client connection.

From Health Center V1.2, you can start the agent without a client connection in place. The agent waits for a client connection with no impact on the application that is running. When the client connects to the agent, data collection starts.

full

The agent starts collecting data immediately; you do not need to start the client to trigger data collection. However, the data is not available for viewing until you connect a client to the agent.

headless

Specifies headless mode.

The agent starts collecting data immediately, and stores the data in files rather than sending it to the client. When the application ends, the agent creates a file called healthcenter pid.hcd, where pid is the process ID of the agent. You can load this file into the client at a later date, to view the data.

Headless mode is useful for systems where you cannot connect a client to the agent. For example, where firewall restrictions prevent connection.

For limitations when running the agent in headless mode, see Known limitations.

inprocess:

Specifies in-process mode.

The agent starts, but does not connect to the GUI client. A network socket is not opened. You must use the Health Center API to retrieve data from the agent. Use this mode when you want monitor an application from within the same runtime environment process. For more information about in-process monitoring, see ConnectionProperties .

For limitations when running the agent in in-process mode, see Known limitations.

If you specify headless for the com.ibm.java.diagnostics.healthcenter.data.collection.level property, you can optionally specify the following properties to control how Health Center creates the output files:

com.ibm.java.diagnostics.healthcenter.headless.delay.start

Sets a delayed start time, in minutes. The agent waits for this length of time before starting to collect data. The default time is 0, which specifies no delay.

com.ibm.java.diagnostics.healthcenter.headless.files.max.size

Sets the maximum size, in bytes, of each output file that is created by headless mode. The size must be between 5000000 (5 MB) and 2000000000 (2GB). If you set a value lower than 5 MB, the property defaults to 5 MB. If you set a value greater than 2 GB, the property is ignored. By default, this property is not set, and the maximum file size is 2GB.

com.ibm.java.diagnostics.healthcenter.headless.files.to.keep

Sets the number of output files to keep.

The maximum file size that Health Center can read is 2 GB. When running in headless mode, if the data that Health Center collects exceeds that amount, the agent automatically creates a second file, and so on. If you are gathering lots of data, a long headless run will result in a collection of files. By default, Health Center keeps only the last 10 files, to manage disk space. You can override this value by using the com.ibm.java.diagnostics.healthcenter.headless.files.to.keep property.

com.ibm.java.diagnostics.healthcenter.headless.output.directory

Specifies the directory for the output files that are created by the headless mode. For example:

com.ibm.java.diagnostics.healthcenter.headless.output.directory=/tmp

If you do not specify a directory for the output files, or Health Center cannot write to the directory you choose, the current working directory of the application is used instead. If Health Center cannot write to the current working directory of the application, the default temporary directory of the operating system is used.

com.ibm.java.diagnostics.healthcenter.headless.run.duration

Sets the time, in minutes, to collect data for. The default value is 0, which specifies that collection runs for the life of the application. The default value also overrides the settings for pause duration and number of runs.

com.ibm.java.diagnostics.healthcenter.headless.run.number.of.runs

Sets the number of collection runs. The default value is 0, which specifies that this value has no effect and the run lasts until the application ends. At the end of each collection run, the agent creates a file called healthcenter pid_run_number.hcd, where pid is the process number of the agent, and run_number identifies the run that generated the file. For example, healthcenter23453_1.hcd is the file that is generated by the first run of the agent with process ID 23453.

com.ibm.java.diagnostics.healthcenter.headless.run.pause.duration

Sets the time, in minutes, for the agent to pause between collections. The default value is 0, which specifies no pause.

Use these settings to create a profile across the lifetime of a running application. For example, if you set the pause duration to 5, the number of runs to 10 and the run duration to 2, the agent collects data for 2 minutes, pauses for 5 minutes, then collects data again for 2 minutes, and so on, for 10 collections.

Other properties

com.ibm.diagnostics.healthcenter.logging.level

Modifies the level of messages that are output by the agent to the stderr stream. You can specify one of the following levels; the default is info.

none
warning
info
fine
finest
debug

Use these messages to monitor, for example, the connection between the agent and the MQTT broker, or information about data collection runs when the com.ibm.java.diagnostics.healthcenter.data.collection.level property is set to headless. For example, the following messages are displayed when the MQTT broker restarts and the agent temporarily loses the connection:

[Tue 21 Oct 2014 14:24:30 BST] com.ibm.diagnostics.healthcenter.mqtt INFO: Connected to broker localhost:1883 [Tue 21 Oct 2014 14:24:45 BST] com.ibm.diagnostics.healthcenter.mqtt WARNING: Connection to broker localhost:1883 has been lost [Tue 21 Oct 2014 14:25:12 BST] com.ibm.diagnostics.healthcenter.mqtt INFO: Connected to broker localhost:1883

com.ibm.diagnostics.healthcenter.readonly

If you set this property to on, the monitoring agent ignores requests from the Health Center client that might disrupt the monitored application. For example, requests for class histogram data or for generating a dump file. These functions could be used in a denial-of-service attack because they can affect the monitored application. By default, this property is set to off.

com.ibm.diagnostics.healthcenter.mqtt.topic.namespace

com.ibm.diagnostics.healthcenter.mqtt.application.id

User-specified strings for assisting the identification of agents that are available through an MQTT broker.

When you open a new MQTT connection in the Health Center client, the client shows a list of available agents. Each agent is identified by a generated string, which by default has the following format:

ibm/healthcenter/ agent_ID (host_name: process_ID)

If the MQTT broker is shared, for example by one or more people monitoring multiple applications, this default string might not be enough to identify the agent that corresponds to each user or application. To avoid this problem, you can modify the generated string for your agent by setting one or both of these properties. The generated string then becomes as follows:

 topic.namespace /ibm/healthcenter/ agent_ID (application.id)

If there are many agents in the list, you can also use these properties to organize the list. For example, if you have multiple agents running on your machine and you are sharing the MQTT broker with users on other machines, you can set the com.ibm.diagnostics.healthcenter.mqtt.topic.namespace property for each of your agents to your machine name. Your agents then appear grouped together in the list.

com.ibm.java.diagnostics.healthcenter.agent.path

Specifies the path to an agent that is installed outside the Java SDK, when you want to use that agent to monitor an application in a VM that is already running. You might install an agent outside the SDK when you want to update to the latest version of the agent, but updating the SDK file system is difficult, for example on z/OS systems. For more information about monitoring applications that are already running, see Starting the Health Center agent after starting an application (Java applications only).

com.ibm.java.diagnostics.healthcenter.output.folder

Sets the garbage collection file location.

If you enable the collection of garbage collection data, this data is stored in a file. You cannot specify the name of the file, but you can specify its location by using this property. If you do not set this property, the file is stored in the directory that is specified by the user.dir system property. For more information, see Controlling the collection of garbage collection information (Java applications only).

com.ibm.java.diagnostics.healthcenter.inprocess.delay

Sets a delayed start time, in ms, for inprocess connections. The agent waits for this length of time before starting to collect data. The default time is 0, which specifies no delay. This property must be specified as a Java System property, that is, using -D on the command line or in a jvm.options file.

com.ibm.java.diagnostics.healthcenter.socket.readwrite ( IBM SDK, Java Technology Edition, Version 8 or later)

Specifies whether network socket send and receive data is included when the Health Center agent starts to collect data. By default, this property is set to off (no data collected). Set the property to on to enable data collection.

com.ibm.java.diagnostics.healthcenter.thread.stack.depth

Sets the thread stack depth.

This property is an integer that specifies the depth of thread stack information to collect for the Threads perspective. The default setting is Integer.MAX_VALUE, which specifies that full thread stacks are collected. Set this property to 0 to turn off the collection of thread stack information.

Property summary

The following table shows a summary of each property.

Table 1. Summary of Health Center configuration properties
Property	Property description	Value (defaults are for Java applications)
`com.ibm.diagnostics.healthcenter.headless`	Enables the agent to store data in files rather than sending it to the client.	off or on. The default value is off.
`com.ibm.diagnostics.healthcenter.jmx`	Enables the agent to communicate with the client by using a JMX connection.	off or on. The default value is on.
`com.ibm.diagnostics.healthcenter.logging.level`	Modifies the level of messages that are output by the agent.	`none`, `warning`, `info`, `fine`, `finest`, or `debug`. The default is `info`.
`com.ibm.diagnostics.healthcenter.mqtt`	Enables the agent to communicate with the client by using an MQTT broker.	off or on. The default value is off.
`com.ibm.diagnostics.healthcenter.mqtt.application.id`	The application ID to display in the agent identifier string	A string
`com.ibm.diagnostics.healthcenter.mqtt.broker.host=value`	The MQTT broker host name	The host name of the machine on which the MQTT broker is running. The default is `localhost`.
`com.ibm.diagnostics.healthcenter.mqtt.broker.pass`	The MQTT user password	The user password that is specified in the MQTT broker configuration. This property is not set by default.
`com.ibm.diagnostics.healthcenter.mqtt.broker.port=value`	The MQTT broker port	The port number that the MQTT broker is set to use. The default is `1883`.
`com.ibm.diagnostics.healthcenter.mqtt.broker.user`	The MQTT user name	The user name that is specified in the MQTT broker configuration. This property is not set by default.
`com.ibm.diagnostics.healthcenter.mqtt.topic.namespace`	The MQTT topic name space to display in the agent identifer string	A string
`com.ibm.diagnostics.healthcenter.readonly`	Whether the agent ignores requests from the client that might disrupt the monitored application	Set to on to ignore requests. The default value is off.
`com.ibm.java.diagnostics.healthcenter.agent.authentication.file=value`	MBean authentication file location	An absolute or relative path to a file. For example, ./authentication.txt
`com.ibm.java.diagnostics.healthcenter.agent.authorization.file=value`	MBean authorization file location	An absolute or relative path to a file. For example, ./authorization.txt
`com.ibm.java.diagnostics.healthcenter.agent.iiop.port=value`	IIOP port number	A valid port number. There is no default value.
`com.ibm.java.diagnostics.healthcenter.agent.path=value` (or `path=value` when not used in system property format)	The agent installation directory, if the agent is installed outside the Java SDK directory	A path, for example /home/hclatest
`com.ibm.java.diagnostics.healthcenter.agent.port=value` (or `port=value` when used with -Xhealthcenter)	Port number	A valid port number. The default is `1972`.
`com.ibm.java.diagnostics.healthcenter.agent.ssl.keyStore=value`	SSL keystore location	An absolute or relative path to a keystore file. For example, ./HCAgentKeystore
`com.ibm.java.diagnostics.healthcenter.agent.ssl.keyStoreCertificatePassword=value`	SSL keystore certificate password	A text string containing only letters or numbers. For example password123.
`com.ibm.java.diagnostics.healthcenter.agent.ssl.keyStorePassword=value`	SSL keystore password	A text string containing only letters or numbers. For example password123.
`com.ibm.java.diagnostics.healthcenter.agent.transport=value` (or `transport=value` when used with -Xhealthcenter)	Transport protocol	iiop or jrmp. The default is iiop.
`com.ibm.java.diagnostics.healthcenter.data.collection.level=value` (or `level=value` when used with -Xhealthcenter)	Collection level	full, off, headless, or inprocess. The default is full.
`com.ibm.java.diagnostics.healthcenter.headless.delay.start=value`	Delayed start time	A time in minutes. The default value is `0`.
`com.ibm.java.diagnostics.healthcenter.headless.files.max.size=value`	Maximum size of output files	A size in bytes, between 5000000 (5 MB) and 2000000000 (2 GB). By default, this property is unset, which specifies the maximum size of 2 GB. Values of less than 5 MB are changed to 5 MB. Values of greater than 2 GB are ignored.
`com.ibm.java.diagnostics.healthcenter.headless.files.to.keep=value`	Number of output files to keep	A whole number. The default is `10`. Use `0` to keep all the files.
`com.ibm.java.diagnostics.healthcenter.headless.output.directory=value`	Location of output files	An absolute or relative path to a directory. The default value is the working directory of the application, or if Health Center cannot write to that directory, the default temporary directory of the operating system.
`com.ibm.java.diagnostics.healthcenter.headless.run.duration=value`	Run duration	A time in minutes. The default value is `0`.
`com.ibm.java.diagnostics.healthcenter.headless.run.number.of.runs=value`	Number of runs	A whole number. The default value is `0`.
`com.ibm.java.diagnostics.healthcenter.headless.run.pause.duration=value`	Pause duration	A time in minutes. The default value is `0`.
`com.ibm.java.diagnostics.healthcenter.inprocess.delay=value`	Time to wait before inprocess mode starts	A time in ms. The default value is `0`.
`com.ibm.java.diagnostics.healthcenter.output.folder property=value`	Garbage collection file location	An absolute or relative path to a directory. There is no default value.
`com.ibm.java.diagnostics.healthcenter.socket.readwrite=value`	Whether network send and receive data is collected.	off or on. The default value is off.
`com.ibm.java.diagnostics.healthcenter.thread.stack.depth=value`	Thread stack depth	A whole number, or Integer.MAX_VALUE (default). Use `0` to turn off the collection of thread call stacks.