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.
- 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.
If you specify a property that is not supported for your application type, it is ignored.
Property format
- 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 (=).
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®.
- com.ibm.diagnostics.healthcenter.mqtt.broker.host
- com.ibm.diagnostics.healthcenter.mqtt.broker.port
- Set the MQTT broker host name and port.
- com.ibm.java.diagnostics.healthcenter.agent.port
- Sets the JMX port number.
- com.ibm.java.diagnostics.healthcenter.agent.iiop.port
- Sets the IIOP 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.
- 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.
- 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.
- inprocess:
- Specifies in-process mode.
- 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.
- com.ibm.java.diagnostics.healthcenter.headless.output.directory
-
Specifies the directory for the output files that are created by the headless mode. For example: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.output.directory=/tmp
- 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.
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
[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.
- 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.
- 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.
Property summary
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 |
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 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 protocol | iiop or jrmp. The default is iiop. |
com.ibm.java.diagnostics.healthcenter.data.collection.level=value
(or |
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. |