vrealize Hyperic 5.8.4 This document supports the version of each product listed and supports all subsequent versions until the document is replaced by a new edition. To check for more recent editions of this document, see http://www.vmware.com/support/pubs. EN-01613-01
You can find the most up-to-date technical documentation on the VMware Web site at: http://www.vmware.com/support/ The VMware Web site also provides the latest product updates. If you have comments about this documentation, submit your feedback to: docfeedback@vmware.com Copyright 2015 VMware, Inc. All rights reserved. Copyright and trademark information. VMware, Inc. 3401 Hillview Ave. Palo Alto, CA 94304 www.vmware.com 2 VMware, Inc.
Contents About 5 1 Configuring and Running a vrealize Hyperic Agent 7 Using a Command Line to Run the Agent Launcher 8 Running the Agent Launcher from the vrealize Hyperic User Interface 9 Run the vrealize Hyperic Agent Without a Java Service Wrapper 10 Configuring Agent Logging 10 Configuring Plug-in Loading 13 Configuring an Agent to Enable a Resource Plug-in 14 Managing the vrealize Hyperic Agent 16 Agent Properties 21 Configuring the Agent Java Service Wrapper 36 Tailoring the Agent Wrapper Configuration 38 Automated Deployment of Multiple vrealize Hyperic Agents 39 2 Configuring and Running the vrealize Hyperic Server 41 Starting the vrealize Hyperic Server 41 Configuring Metric Baselining and Alert Processing Behavior 42 Scaling and Tuning vrealize Hyperic Performance 44 Integrating vrealize Hyperic Server with Other Systems 48 Managing the vrealize Hyperic Database 53 Clustering vrealize Hyperic Servers for Failover 63 vrealize Hyperic Server Properties 66 Tuning the vrealize Hyperic vapp 73 Index 75 VMware, Inc. 3
4 VMware, Inc.
About The provides information about configuring and running the vrealize Hyperic agent and server. VMware, Inc. 5
6 VMware, Inc.
Configuring and Running a 1 vrealize Hyperic Agent There are various options that you can use to run a vrealize Hyperic agent. You can customize certain parameters to suit your environment requirements. Using a Command Line to Run the Agent Launcher on page 8 You can use the command line to initiate the vrealize Hyperic agent launcher and agent lifestyle commands. Running the Agent Launcher from the vrealize Hyperic User Interface on page 9 In vrealize Hyperic, you can issue selected commands to a running vrealize Hyperic agent. Run the vrealize Hyperic Agent Without a Java Service Wrapper on page 10 If you run a If you run an Hyperic agent on a system that does not support the Java Service Wrapper, or for other reasons prefer not to use the wrapper, you can start the agent without the wrapper. Configuring Agent Logging on page 10 You can configure the name, location, and logging level for vrealize Hyperic agent logs. You can also redirect system messages to the agent log, and configure the debug log level for an agent subsystem. Configuring Plug-in Loading on page 13 At startup, a vrealize Hyperic agent loads all the plug-ins in the AgentHome/bundles/agent-x.y.znnnn/pdk/plugins directory. You can reduce the agent's memory footprint by configuring it to load only the plug-ins that you use. Configuring an Agent to Enable a Resource Plug-in on page 14 You can configure a vrealize Hyperic agent to enable a specific plug-in to perform one or more of its management functions. Managing the vrealize Hyperic Agent on page 16 You can monitor your vrealize Hyperic agents and tune them to your requirements. You can view the status of all the agents, view the metrics of a specific agent and reduce the memory footprint of an agent. Agent Properties on page 21 Multiple properties are support in the agent.properties file for a vrealize Hyperic agent. Not all supported properties are included by default in the agent.properties file. Configuring the Agent Java Service Wrapper on page 36 The configuration file for the vrealize Hyperic agent;s Java service wrapper is located in AgentHome/bundles/BundleHome/conf/wrapper.conf. Tailoring the Agent Wrapper Configuration on page 38 The Java options that are supplied to the vrealize Hyperic agent at startup are configured in the Java Additional Parameters section of the wrapper.conf file. VMware, Inc. 7
Automated Deployment of Multiple vrealize Hyperic Agents on page 39 You can deploy multiple vrealize Hyperic agents simultaneously, using vrealize Infrastructure Navigator. You configure the agent properties prior to deployment. Using a Command Line to Run the Agent Launcher You can use the command line to initiate the vrealize Hyperic agent launcher and agent lifestyle commands. Run the Agent Launcher from a Linux Command Line on page 8 You initiate the agent launcher and agent life cycle commands with the hq-agent.sh script in the AgentHome/bin directory. Run the Agent Launcher from a Windows Command Line on page 8 You initiate the agent launcher and agent life cycle commands with the hq-agent.bat script in the AgentHome/bin directory. Run the Agent Launcher from a Linux Command Line You initiate the agent launcher and agent life cycle commands with the hq-agent.sh script in the AgentHome/bin directory. Procedure 1 Open a command shell or terminal window. 2 Type the required command using the format sh hq-agent.sh command where command is one of the following. Option start stop restart status dump ping setup Description Starts the agent as a daemon process. Stops the agent's JVM process. Stops and then starts the agent's JVM process. Queries the status of the agent's JVM process.. Runs a thread dump for the agent process, and writes the results to the agent.log file in AgentHome/log. Pings the agent process. Causes the vrealize Hyperic agent to prompt you for the agent-server connection properties, enabling you to change values that were provided at first agent startup. Run the Agent Launcher from a Windows Command Line You initiate the agent launcher and agent life cycle commands with the hq-agent.bat script in the AgentHome/bin directory. Procedure 1 Open a terminal window. 2 Type the required command using the format hq-agent.bat command where command is one of the following. Option start stop Description Starts the agent as an NT service. Stops the agent as an NT service. 8 VMware, Inc.
Chapter 1 Configuring and Running a vrealize Hyperic Agent Option restart install remove query ping setup Description Stops and then starts the agent's JVM process. Installs the agent NT service Removes the agent's service from the NT service table Queries the current status of the agent NT service (status) Pings the agent process. Prompts for setup configuration for the agent process. Running the Agent Launcher from the vrealize Hyperic User Interface In vrealize Hyperic, you can issue selected commands to a running vrealize Hyperic agent. Agent control commands are available on the Views tab for a vrealize Hyperic agent or a group of agents in inventory. Restart an Agent from the Hyperic User Interface on page 9 You can use the restart action to invoke the restart command in the Java Service Wrapper of the vrealize Hyperic agent. Ping an Agent from the vrealize Hyperic User Interface on page 9 You can ping an agent or group of agents to check connectivity. Upgrade an Agent from the vrealize Hyperic User Interface on page 10 You can upgrade agents directly from the vrealize Hyperic user interface. Push a Resource Plug-in to an Agent from the vrealize Hyperic User Interface on page 10 The push plugin action sends new and changed resource plug-ins to the target agent or agents. Restart an Agent from the Hyperic User Interface You can use the restart action to invoke the restart command in the Java Service Wrapper of the vrealize Hyperic agent. The restart action shuts down the JVM process in which the agent runs, waits for the process to terminate cleanly, and generates a new JVM process for the agent. During the restart process, the agent's metric collection and resource control functionality is interrupted. The restart action occurs asynchronously. To verify that the restart succeeded go to the page for the agent in the vrealize Hyperic user interface and check its availability. Alternatively, you could configure an alert for the agent that is triggered when the agent's availability changes. Procedure 1 On the Views tab for a vrealize Hyperic agent or group of agents, select restart from the drop-down menu. 2 Click Execute. The agent restarts. Ping an Agent from the vrealize Hyperic User Interface You can ping an agent or group of agents to check connectivity. Procedure 1 On the Views tab for a vrealize Hyperic agent or group of agents, select ping from the drop-down menu. VMware, Inc. 9
2 Click Execute. Example: What to do next Upgrade an Agent from the vrealize Hyperic User Interface You can upgrade agents directly from the vrealize Hyperic user interface. Procedure 1 On the Views tab for a vrealize Hyperic agent or group of agents, select upgrade from the drop-down menu. 2 Select the relevant agent bundle and click Execute. 1 The agent bundle is transferred from the vrealize Hyperic server to the target agent or agents. 2 The agent expands the bundle locally. 3 The agent updates the local bundle property. 4 The server restarts the agent. The configuration properties in the agent's /conf/agent.properties file are preserved. Push a Resource Plug-in to an Agent from the vrealize Hyperic User Interface The push plugin action sends new and changed resource plug-ins to the target agent or agents. Procedure 1 On the Views tab for a vrealize Hyperic agent or group of agents, select push plugin from the dropdown menu. 2 Select the required plugin and click Execute. 1 The plug-in is transferred from the vrealize Hyperic server to the target agent or agents. 2 The server restarts the agent. Run the vrealize Hyperic Agent Without a Java Service Wrapper If you run a If you run an Hyperic agent on a system that does not support the Java Service Wrapper, or for other reasons prefer not to use the wrapper, you can start the agent without the wrapper. Procedure u From the AgentHome/bundles/agent-x.y.z/bin directory, run the hq-agent-nowrapper.sh agent start script using nohup. nohup AgentHome/bundles/agent-x.y.z/bin/hq-agent-nowrapper.sh Configuring Agent Logging You can configure the name, location, and logging level for vrealize Hyperic agent logs. You can also redirect system messages to the agent log, and configure the debug log level for an agent subsystem. Agent Log Files on page 11 The vrealize Hyperic agent log files are stored in the AgentHome/log directory. 10 VMware, Inc.
Chapter 1 Configuring and Running a vrealize Hyperic Agent Configuring the Agent Log Name or Location on page 11 Use these properties to change the name or location of the agent log file. Configuring the Agent Logging Level on page 12 Use this property to control the severity level of messages that the vrealize Hyperic agent writes to the agent log file. Redirecting System Messages to the Agent Log on page 12 You can use these properties to redirect system-generated messages to the vrealize Hyperic agent log file. Configuring the Debug Level for an Agent Subsystem on page 12 For troubleshooting purposes, you can increase the logging level for an individual agent subsystem. Agent Log Files The vrealize Hyperic agent log files are stored in the AgentHome/log directory. Agent log files include the following: agent.log agent.startup.log wrapper.log The Java service wrapper-based agent launcher writes messages to the wrapper.log file. Configuring the Agent Log Name or Location Use these properties to change the name or location of the agent log file. agent.logdir You can add this property to the agent.properties file to specify the directory where the vrealize Hyperic agent will write its log file. If you do not specify a fully qualified path, agent.logdir is evaluated relative to the agent installation directory. This property does not exist in the agent.properties file unless you explicitly add it. The default behavior is equivalent to the agent.logdir=log setting, resulting in the agent log file being written to the AgentHome/log directory. To change the location for the agent log file, add agent.logdir to the agent.properties file and enter a path relative to the agent installation directory, or a fully qualified path. The name of the agent log file is configured with the agent.logfile property. agent.logfile This property specifies the path and name of the agent log file. In the agent.properties file, the default setting for the agent.logfile property is made up of a variable and a string, agent.logfile=${agent.logdir}\agent.logdir. agent.logdir is a variable that supplies the value of an identically named agent property. By default, the value of agent.logdir is log, interpreted relative to the agent installation directory. agent.log is the name for the agent log file. By default, the agent log file is named agent.log and is written to the AgentHome/log directory. To configure the agent to log to a different directory, you must explicitly add the agent.logdir property to the agent.properties file. VMware, Inc. 11
Configuring the Agent Logging Level Use this property to control the severity level of messages that the vrealize Hyperic agent writes to the agent log file. agent.loglevel This property specifies the level of detail of the messages that the vrealize Hyperic agent writes to the log file. Available values are INFO and DEBUG. The default value is INFO. Setting the agent.loglevel property value to DEBUG level is not advised. This level of logging across all subsystems imposes overhead, and can also cause the log file to roll over so frequently that log messages of interest are lost. It is preferable to configure debug level logging only at the subsystem level. Redirecting System Messages to the Agent Log You can use these properties to redirect system-generated messages to the vrealize Hyperic agent log file. agent.loglevel.systemerr This property redirects System.err to agent.log. Commenting out this setting causes System.err to be directed to agent.log.startup. The default value is ERROR. agent.loglevel.systemout This property redirects System.out to agent.log. Commenting out this setting causes System.out to be directed to agent.log.startup. The default value is INFO. Configuring the Debug Level for an Agent Subsystem For troubleshooting purposes, you can increase the logging level for an individual agent subsystem. To increase the logging level for an individual agent subsystem, uncomment the appropriate line in the section of the agent.properties file that is labelled Agent Subsystems: Uncomment individual subsystems to see debug messages. Agent log4j Properties This is the log4j properties in the agent.properties file. log4j.rootlogger=${agent.loglevel}, R log4j.appender.r.file=${agent.logfile} log4j.appender.r.maxbackupindex=1 log4j.appender.r.maxfilesize=5000kb log4j.appender.r.layout.conversionpattern=%d{dd-mm-yyyy HH:mm:ss,SSS z} %-5p [%t] [%c{1}@%l] %m%n log4j.appender.r.layout=org.apache.log4j.patternlayout log4j.appender.r=org.apache.log4j.rollingfileappender ## ## Disable overly verbose logging ## log4j.logger.org.apache.http=error log4j.logger.org.springframework.web.client.resttemplate=error log4j.logger.org.hyperic.hq.measurement.agent.server.senderthread=info 12 VMware, Inc.
Chapter 1 Configuring and Running a vrealize Hyperic Agent log4j.logger.org.hyperic.hq.agent.server.agentdlistprovider=info log4j.logger.org.hyperic.hq.agent.server.measurementschedule=info log4j.logger.org.hyperic.util.units=info log4j.logger.org.hyperic.hq.product.pluginxml=info # Only log errors from naming context log4j.category.org.jnp.interfaces.namingcontext=error log4j.category.org.apache.axis=error #Agent Subsystems: Uncomment individual subsystems to see debug messages. #----------------------------------------------------------------------- #log4j.logger.org.hyperic.hq.autoinventory=debug #log4j.logger.org.hyperic.hq.livedata=debug #log4j.logger.org.hyperic.hq.measurement=debug #log4j.logger.org.hyperic.hq.control=debug #Agent Plugin Implementations #log4j.logger.org.hyperic.hq.product=debug #Server Communication #log4j.logger.org.hyperic.hq.bizapp.client.agentcallbackclient=debug #Server Realtime commands dispatcher #log4j.logger.org.hyperic.hq.agent.server.commanddispatcher=debug #Agent Configuration parser #log4j.logger.org.hyperic.hq.agent.agentconfig=debug #Agent plugins loader #log4j.logger.org.hyperic.util.pluginloader=debug #Agent Metrics Scheduler (Scheduling tasks definitions & executions) #log4j.logger.org.hyperic.hq.agent.server.session.agentsynchronizer.schedulerthread=debug #Agent Plugin Managers #log4j.logger.org.hyperic.hq.product.measurementpluginmanager=debug #log4j.logger.org.hyperic.hq.product.autoinventorypluginmanager=debug #log4j.logger.org.hyperic.hq.product.configtrackpluginmanager=debug #log4j.logger.org.hyperic.hq.product.logtrackpluginmanager=debug #log4j.logger.org.hyperic.hq.product.livedatapluginmanager=debug #log4j.logger.org.hyperic.hq.product.controlpluginmanager=debug Configuring Plug-in Loading At startup, a vrealize Hyperic agent loads all the plug-ins in the AgentHome/bundles/agent-x.y.znnnn/pdk/plugins directory. You can reduce the agent's memory footprint by configuring it to load only the plug-ins that you use. You can either specify a list of plug-ins to exclude, or configure a list of plug-ins to load. VMware, Inc. 13
plugins.exclude Use this property to specify the plug-ins that the vrealize Hyperic agent must not load at startup. This property is useful for reducing an agent's memory footprint. You supply a comma-separated list of plugins to exclude. For example, plugins.exclude=jboss,apache,mysql. plugins.include Use this property to specify the plug-ins that the vrealize Hyperic agent must load at startup. This property is useful for reducing an agent's memory footprint. You supply a comma-separated list of plugins to include. For example, plugins.include=weblogic,apache. Configuring an Agent to Enable a Resource Plug-in You can configure a vrealize Hyperic agent to enable a specific plug-in to perform one or more of its management functions. Configuring Agent Account Privileges under Solaris 10 on page 14 To auto-discover certain products under Solaris 10, the vrealize Hyperic agent must run as root, or you must grant additional permissions to the account where the agent runs. Configuring the Agent HTTP Request Header on page 15 If you monitor a remote HTTP server, it is useful to configure the HTTP request header for agent HTTP requests. Configuring the Agent to Monitor JBoss on page 15 You can specify the location of the JBoss root directory so that the vrealize Hyperic agent can monitor JBoss. Configuring the Data to Log Windows Events on page 15 When log tracking is enabled for a Windows resource, you can use the platform.log_track.eventfmt agent property to customize the content of events that the vrealize Hyperic agent logs for Windows events. Configuring Agent Account Privileges under Solaris 10 To auto-discover certain products under Solaris 10, the vrealize Hyperic agent must run as root, or you must grant additional permissions to the account where the agent runs. Under Solaris 10's Least Privilege Model (LPM), default privileges are minimal. The vrealize Hyperic agent must be able to read./proc/$pid/ files on the platform. Problems with auto-discovery on Solaris 10 might be the result of insufficient privileges. Depending on your account privilege implementation you might need to grant the proc_zone privilege to the agent account. For example, you could add the following line to /etc/user_attr, to grant the proc_owner privilege to the vrealize Hyperic user and to deny the proc_session privilege: hq::::type=normal;defaultpriv=basic,proc_owner,!proc_session After changing account privileges, you need to re-login. Your approach tp enabling agent access to /proc/$pid/ files is dependent on your company's LPM implementation and best practices. 14 VMware, Inc.
Chapter 1 Configuring and Running a vrealize Hyperic Agent Configuring the Agent HTTP Request Header If you monitor a remote HTTP server, it is useful to configure the HTTP request header for agent HTTP requests. http.useragent The http.useragent property defines the value for the User-Agent request header in HTTP requests issued by the vrealize Hyperic agent. By default, the User-Agent in agent requests includes the vrealize Hyperic agent version, and so changes when the agent is upgraded. Therefore, if a target HTTP server is configured to block requests with an unknown User-Agent, agent requests fail following an agent upgrade. You can use http.useragent to define a User-Agent value that is consistent across upgrades. The agent.properties file does not contain this property by default. You must add it to the file. The default is Hyperic-HQ-Agent/Version For example, Hyperic-HQ-Agent/4.1.2-EE. Configuring the Agent to Monitor JBoss You can specify the location of the JBoss root directory so that the vrealize Hyperic agent can monitor JBoss. jboss.installpath To enable the agent to monitor JBoss, specify the location of the JBoss root directory. The default location is /usr/local/jboss-4.0.0. Configuring the Data to Log Windows Events When log tracking is enabled for a Windows resource, you can use the platform.log_track.eventfmt agent property to customize the content of events that the vrealize Hyperic agent logs for Windows events. platform.log_track.eventfmt This property specifies the content and format of the Windows event attributes that a vrealize Hyperic agent includes when logging a Windows event as an event in Hyperic. agent.properties does not contain the platform.log_track.eventfmt property, you must add it if before you can customize the data logged for Windows events. By default, when Windows log tracking is enabled, an entry in the format [Timestamp] Log Message (EventLogName):EventLogName:EventAttributes is logged for events that match the criteria you specified on the resource's Configuration Properties page. Attribute Timestamp Log Message EventLogName EventAttributes Description The time at which the event occurred. A text string. The Windows event log type, System, Security, or Application. A colon-delimited string comprising the Windows event Source and Message attributes. The following example is for a Windows event that was written to the Windows System event log at 6:06 AM on 04/19/2010. The Windows event Source and Message attributes, are Print and Printer HP LaserJet 6P was paused., respectively. 04/19/2010 06:06 AM Log Message (SYSTEM): SYSTEM: Print: Printer HP LaserJet 6P was paused. VMware, Inc. 15
Configuration You can use the following parameters to configure the Windows event attributes that the agent writes for a Windows event. Each parameter maps to a Windows event attribute of the same name. Parameter %user% %computer% %source% %event% %message% %category% Description The name of the user on whose behalf the event occurred. The name of the computer on which the event occurred. The software that logged the Windows event. A number identifying the particular event type. The event message. An application-specific value used for grouping events. For example, if you set the following properties, platform.log_track.eventfmt=%user%@%computer% %source %:%event%:%message%, the vrealize Hyperic agent will write the following data when logging a Windows event. 04/19/2010 06:06 AM Log Message (SYSTEM): SYSTEM: HP_Admistrator@Office Print:7:Printer HP LaserJet 6P was paused The entry is for as for a Windows event that was written to the Windows System event log at 6:06 AM on 04/19/2010. The software associated with the event was running as HP_Administrator on the Office host. The Windows event's Source, Event, and Message attributes, are Print, 7, and Printer HP LaserJet 6P was paused., respectively. Managing the vrealize Hyperic Agent You can monitor your vrealize Hyperic agents and tune them to your requirements. You can view the status of all the agents, view the metrics of a specific agent and reduce the memory footprint of an agent. Viewing the Status of All Agents on page 17 You can view the health status of your vrealize Hyperic agents, including the number of platforms an agent monitors, the number of resource metrics that an agent collects, and the number of licenses consumed by an agent. Viewing the Metrics for an Agent on page 18 A vrealize Hyperic agent monitors itself. You can tailor the metric collection settings for an agent, use agent metrics to troubleshoot problems, and base alerts on agent metrics or events. View Agent Indicator Charts on page 18 The Indicators page for an agent charts the agent's indicator metrics. View Agent Metric Data on page 18 The Metric Data page for an agent displays all of the metrics collected for the agent. vrealize Hyperic Agent Metrics on page 19 This table lists the metrics that can be collected for a vrealize Hyperic agent. Reducing the Agent Memory Footprint on page 20 There are various options you can employ to reduce the amount of memory an agent uses. 16 VMware, Inc.
Chapter 1 Configuring and Running a vrealize Hyperic Agent Viewing the Status of All Agents You can view the health status of your vrealize Hyperic agents, including the number of platforms an agent monitors, the number of resource metrics that an agent collects, and the number of licenses consumed by an agent. You view the status of all agent that are registered with the vrealize Hyperic server on the Agents tab of the HQ Health page. Health Data for an Agent The data that you can view is described in the following table. Table 1 1. Agent Health Data Field Description Notes FQDN Address Port Fully-qualified domain name of the platform where the agent runs. IP address of the platform where the agent runs. Port where the agent listens for communication with the vrealize Hyperic server. If you configure unidirectional agent - server communications, the agent initiates all communications with the vrealize Hyperic server. Version Agent version number. Although an agent might work successfully with an vrealize Hyperic server of a later version, it is strongly recommended that you run the same version of the agent and server. Build # Bundle Version Creation Time Agent build number. Agent bundle version. The date/time that the vrealize Hyperic agent was first started up. # Platforms Number of platforms the agent manages. # Metrics The number of resource metrics the agent collects. This is the total number of metrics that are configured for collection across all resources the agent monitors. Typically, an agent manages one platform - the platform where it runs. Exceptions include: If the agent manages a vsphere vcenter instance, the number of platforms shown is the number of virtual machines the vcenter server manages. If the agent manages remote network devices or network host platform types. If one agent bears an inordinate metric load, you might be able to distribute it more evenly. VMware, Inc. 17
Table 1 1. Agent Health Data (Continued) Field Description Notes Time Offset (ms) License Count The difference in system clock time between the agent and the vrealize Hyperic server. The number of platform licenses consumed by the agent. A time offset can cause incorrect availability reporting. Typically, a single agent consumes a single license. If an agent manages a vcenter vsphere instance, it consumes a license for the platform that hosts vcenter, a license for each vsphere vhost administered by the vcenter instance, and, if an agent is installed in each virtual machine, license for each vsphere virtual machine on each vhost. Viewing the Metrics for an Agent A vrealize Hyperic agent monitors itself. You can tailor the metric collection settings for an agent, use agent metrics to troubleshoot problems, and base alerts on agent metrics or events. The metrics that an agent reports for itself are: Availability JVM Free Memory JVM Total Memory Number of Metrics Collected Per Minute Number of Metrics Sent to the Server Per Minute Server Offset Total Time Spend Fetching Metrics per Minute View Agent Indicator Charts The Indicators page for an agent charts the agent's indicator metrics. By default, the indicator metrics include JVM Free Memory JVM Total Memory Number of Metrics Collected Per Minute Procedure 1 Click Resources > Browse. 2 Click Servers. 3 Select HQ Agent from the Server Type menu. View Agent Metric Data The Metric Data page for an agent displays all of the metrics collected for the agent. Procedure 1 Click Resources > Browse. 18 VMware, Inc.
Chapter 1 Configuring and Running a vrealize Hyperic Agent 2 Click Servers. 3 Select HQ Agent from the Server Type menu. vrealize Hyperic Agent Metrics This table lists the metrics that can be collected for a vrealize Hyperic agent. Table 1 2. Available Metrics for a vrealize Hyperic Agent. Category Metric Notes Availability Availability Collected by default. Start Time Up Time Throughput Number of Active Threads Number of Metrics Collected Number of Metrics Collected per Minute By default, this is an indicator metric Number of Metrics that Failed to be Collected Number of Metrics that Failed to be Collected per Minute Number of Requests Served Number of Requests Served per Minute Number of Scheduled Metrics Performance Maximum Time Spent Fetching a Metric Maximum Time Spent Processing a Request Minimum Time Spent Fetching a Metric Minimum Time Spent Processing a Request Number of Connection Failures Number of Connection Failures per Minute Number of Metric Batches Sent to Server Number of Metric Batches Sent to Server per Minute Number of Metrics Sent to Server Number of Metrics Sent to Server per Minute Server Offset Collected by default. Collected by default. Total Time Spent Fetching Metrics VMware, Inc. 19
Table 1 2. Available Metrics for a vrealize Hyperic Agent. (Continued) Category Metric Notes Total Time Spent Fetching Metrics per Minute Collected by default. High value can indicate overloaded agent or problem with scheduling thread. Total Time Spent Processing Requests Total Time Spent Processing Requests per Minute Total Time Spent Sending Metrics to Server Total Time Spent Sending Metrics to Server per Minute Utilization Cpu Total Time Cpu Total Time per Minute JVM Free Memory JVM Total Memory By default, this is an indicator metric. By default, this is an indicator metric. Open File Descriptors Resident Memory Used Resident Memory" is the amount of memory the Hyperic Agent occupies in memory Time Spent in System Mode Time Spent in System Mode per Minute Time Spent in User Mode Time Spent in User Mode per Minute Total Memory Used Reducing the Agent Memory Footprint There are various options you can employ to reduce the amount of memory an agent uses. Limit Plug-in Loading The best way to reduce an agent's footprint is to configure it to load only the plug-ins for the resource types you want to monitor. See Configuring Plug-in Loading, on page 13. Reduce Java Heap To reduce the Java heap size that an agent allocates to itself on startup, add the agent.javaopts property to the agent's agent.properties file. This property does not exist in the default agent.properties file. You can reduce the heap from 128m to 64m. Delete JavaDocs File In an environment in which every MB is critical, you can delete the agent's javadocs folder, agent-4.x.x/bundles/agent-4.x.x-yyyy/pdk/javadoc;. Note that this action only reduces the agent footprint by (approximately) 70 MB. 20 VMware, Inc.
Chapter 1 Configuring and Running a vrealize Hyperic Agent Agent Properties Multiple properties are support in the agent.properties file for a vrealize Hyperic agent. Not all supported properties are included by default in the agent.properties file. You must add any properties that you want to use that are not included in the default agent.properties file. Following is a list of the available properties. agent.eventreportbatchsize Property This property specifies the maximum number of events that a vrealize Hyperic agent sends per contact with the server. By default, the agent.properties file does not include this property. The default behavior of the agent is to send a maximum of 100 events per contact with the server. agent.keystore.alias Property This property configures the name of the user-managed keystore for the agent for agents configured for unidirectional communication with the vrealize Hyperic server. Example: Defining the Name of a Keystore Given this user-managed keystore for a unidirectional agent hq self-signed cert), Jul 27, 2011, trustedcertentry, Certificate fingerprint (MD5): 98:FF:B8:3D:25:74:23:68:6A:CB:0B:9C:20:88:74:CE hq-agent, Jul 27, 2011, PrivateKeyEntry, Certificate fingerprint (MD5): 03:09:C4:BC:20:9E:9A:32:DC:B2:E8:29:C0:3C:FE:38 you define the name of the keystore like this agent.keystore.alias=hq-agent If the value of this property does not match the keystore name, agent-server communication fails. The default behavior of the agent is to look for the hq keystore. For unidirectional agents with user-managed keystores, you must define the keystore name using this property. agent.keystore.password Property This property configures the password for a vrealize Hyperic agent's SSL keystore. Define the location of the keystore using the agent.keystore.path Property, on page 22 property. By default, the first time you start the vrealize Hyperic agent following installation, if agent.keystore.password is uncommented and has a plain text value, the agent automatically encrypts the property value. You can encrypt this property value yourself, prior to starting the agent. It is good practice to specify the same password for the agent keystore as for the agent private key. By default, the agent.properties file does not include this property. VMware, Inc. 21
agent.keystore.path Property This property configures the location of a vrealize Hyperic agent's SSL keystore. Specify the full path to the keystore. Define the password for the keystore using the agent.keystore.password property. See agent.keystore.password Property, on page 21. Specifying the Keystore Path on Windows On Windows platforms, specifiy the path to the keystore in this format. C:/Documents and Settings/Desktop/keystore AgentHome/data/keystore. agent.listenip Property The IP address to which the agent binds at startup. The default value allows the agent to listen on all IP addresses on the agent host. This behavior is equivalent to setting the property to an asterisk. agent.logdir Property You can add this property to the agent.properties file to specify the directory where the vrealize Hyperic agent writes its log file. If you do not specify a fully qualified path, agent.logdir is evaluated relative to the agent installation directory. To change the location for the agent log file, enter a path relative to the agent installation directory, or a fully qualified path. Note that the name of the agent log file is configured with the agent.logfile property. By default, the agent.properties file does not include this property. The default behavior is agent.logdir=log, resulting in the agent log file being written to the AgentHome/log directory. agent.logfile Property The path and name of the agent log file. In the agent.properties file, the default setting for the agent.logfile property is made up of a variable and a string agent.logfile=${agent.logdir}\agent.log where agent.logdir is a variable that supplies the value of an identically named agent property. By default, the value of agent.logdir is log, interpreted relative to the agent installation directory. 22 VMware, Inc.
Chapter 1 Configuring and Running a vrealize Hyperic Agent agent.log is the name for the agent log file. By default, the agent log file is named agent.log, and is written to the AgentHome/log directory. agent.loglevel Property The level of detail of the messages the Agent writes to the log file. Allowable values are INFO and DEBUG. INFO agent.loglevel.systemerr Property Redirects System.err to the agent.log file. Commenting out this setting causes System.err to be directed to agent.log.startup. ERROR agent.loglevel.systemout Property Redirects System.out to the agent.log file. Commenting out this setting causes System.out to be directed to agent.log.startup. INFO agent.maxbatchsize Property The maximum number of metrics that the agent will send per contact with the server. The default behavior of the agent is to send a maximum of 500 per contact with the server. By default, the agent.properties file does not include this property. agent.proxyhost Property The host name or IP address of the proxy server that the vrealize Hyperic agent must connect to first when establishing a connection to the vrealize Hyperic server. This property is supported for agents configured for unidirectional communication. Use this property in conjunction with agent.proxyport and agent.setup.unidirectional. None VMware, Inc. 23
agent.proxyport Property The port number of the proxy server that the vrealize Hyperic agent must connect to first when establishing a connection to the vrealize Hyperic server. This property is supported for agents configured for unidirectional communication. Use this property in conjunction with agent.proxyport and agent.setup.unidirectional. None agent.setup.acceptunverifiedcertificate Property This property controls whether or not a vrealize Hyperic agent issues a warning when the vrealize Hyperic server presents an SSL certificate that is not in the agent's keystore and is either self-signed or signed by a different certificate authoridy than the one that signed the agent's SSL certificate. When the default is used, the agent issues the warning The authenticity of host 'localhost' can't be established. Are you sure you want to continue connecting? [default=no]: If you respond yes, the agent imports the server's certificate and will continue to trust the certificate from this point on. agent.setup.acceptunverifiedcertificate=false agent.setup.camip Property Use this property to define the IP address of the vrealize Hyperic server for the agent. The vrealize Hyperic agent reads this value only in the event that it cannot find connection configuration in its data directory. You can specify this and other agent.setup.* properties to reduce the user interaction required to configure an agent to communicate with the server. The value can be provided as an IP address or a fully qualified domain name. To identify an server on the same host as the server, set the value to 127.0.0.1. If there is a firewall between the agent and server, specify the address of the firewall, and configure the firewall to forward traffic on port 7080, or 7443 if you use the SSL port, to the vrealize Hyperic Server. Commented out, localhost. agent.setup.camlogin Property At first startup after installation, use this property to define the vrealize Hyperic agent username to use when the agent is registering itself with the server. The permission required on the server for this initialization is Create, for Platforms. Login from the agent to the server is only required during the initial configuration of the agent. The agent reads this value only in the event that it cannot find connection configuration in its data directory. You can specify this and other agent.setup.* properties to reduce the user interaction required to configure an agent to communicate with the server. 24 VMware, Inc.
Chapter 1 Configuring and Running a vrealize Hyperic Agent Commented our hqadmin. agent.setup.camport Property At first startup after installation, use this property to define the vrealize Hyperic agent server port to use for non-secure communications with the server. The agent reads this value only in the event that it cannot find connection configuration in its data directory. You can specify this and other agent.setup.* properties to reduce the user interaction required to configure an agent to communicate with the server. Commented out 7080. agent.setup.campword Property Use this property to define the password that the vrealize Hyperic agent uses when connecting to the vrealize Hyperic server, so that the agent does not prompt a user to supply the password interactively at first startup.. (The password for the user is that specified by agent.setup.camlogin. The agent reads this value only in the event that it cannot find connection configuration in its data directory. You can specify this and other agent.setup.* properties to reduce the user interaction required to configure an agent to communicate with the server. The first time you start the vrealize Hyperic agent after installation, if agent.keystore.password is uncommented and has a plain text value, the agent automatically encrypts the property value. You can encrypt these property values prior to starting the agent. Commented our hqadmin. agent.setup.camsslport Property At first startup after installation, use this property to define the vrealize Hyperic agent server port to use for SSL communications with the server. The agent reads this value only in the event that it cannot find connection configuration in its data directory. You can specify this and other agent.setup.* properties to reduce the user interaction required to configure an agent to communicate with the server. Commented out 7443. agent.setup.agentip Property Specifies the IP address that the vrealize Hyperic server uses to contact the vrealize Hyperic agent. This If the agent is on the same host as the server, a value of 127.0.0.1 is valid. VMware, Inc. 25
If there is a firewall between the server and agent, specify the IP address of the firewall, and configure the firewall to forward traffic intended for the agent to the agent's listen address, which can be configured with agent.listenip. The agent reads this value only in the event that it cannot find connection configuration in its data directory. You can specify this and other agent.setup.* properties to reduce the user interaction required to configure an agent to communicate with the server. Commented out default. If you use the agent.setup.* properties to supply an agent's configuration at first startup, then uncomment this property, leaving the value default, the vrealize Hyperic server contacts the agent using the IP address that SIGAR detects on the agent host. agent.setup.agentport Property This property specifies the port (on the IP address configured with agent.setup.agentip) on the vrealize Hyperic agent on which the vrealize Hyperic server communicates with the agent. If there is a firewall between the agent and the server, set agent.setup.agentport to the appropriate port on the firewall, and configure the firewall to forward traffic intended for the agent to the agent listen port. The agent reads this value only in the event that it cannot find connection configuration in its data directory. You can specify this and other agent.setup.* properties to reduce the user interaction required to configure an agent to communicate with the server. Commented out default. If you use the agent.setup.* properties to supply an agent's configuration at first startup, then uncomment this property, leaving the value default, the vrealize Hyperic server contacts the agent on port 2144, unless SIGAR detects it is not available, in which case another default is selected. agent.setup.resetuptoken Property Use this property to configure a vrealize Hyperic agent to create a new token to use for authentication with the server at startup. Regenerating a token is useful if the Agent cannot connect to the server because the token has been deleted or corrupted. The agent reads this value only in the event that it cannot find connection configuration in its data directory. Regardless of the value of this property, an agent generates a token the first time it is started after installation. Commented out no. agent.setup.unidirectional Property Enables unidirectional communications between the vrealize Hyperic agent and vrealize Hyperic server. If you configure an agent for unidirectional communication, all communication with the server is initiated by the agent. For a unidirectional agent with a user-managed keystore, you must configure the keystore name in the agent.properties file. 26 VMware, Inc.
Chapter 1 Configuring and Running a vrealize Hyperic Agent Commented out no. agent.startuptimeout Property The number of seconds that the agent startup script waits before determining that the agent has not started up successfully. If the agent is determined to not be listening for requests within this period, an error is logged, and the startup script times out. By default, the agent.properties file does not include this property. The default behavior of the agent is to timeout after 300 seconds. autoinventory.defaultscan.interval.millis Property Specifies how frequently the agent performs a default autoinventory scan. The default scan detects servers and platform services, typically using the process table or the Windows registry. scans are less resource-intensive than runtime scans. The agent performs the default scan at startup and every 15 minutes thereafter. Commented out 86,400,000 milliseconds, or one day. autoinventory.runtimescan.interval.millis Property Specifies how frequently the agent performs a runtime scan. A runtime scan may use more resource-intensive methods to detect services than a default scan. For example, a runtime scan might involve issuing an SQL query or looking up an MBean. 86,400,000 milliseconds, or one day. http.useragent Property Defines the value for the user-agent request header in HTTP requests issued by the vrealize Hyperic agent. You can use http.useragent to define a user-agent value that is consistent across upgrades. By default, the agent.properties file does not include this property. By default, the user-agent in agent requests includes the vrealize Hyperic Agent version, and so changes when the agent is upgraded. If a target HTTP server is configured to block requests with an unknown useragent, agent requests fail after an agent upgrade. Hyperic-HQ-Agent/Version, for example, Hyperic-HQ-Agent/4.1.2-EE. VMware, Inc. 27
log4j Properties The log4j properties for vrealize Hyperic are described here. log4j.rootlogger=${agent.loglevel}, R log4j.appender.r.file=${agent.logfile} log4j.appender.r.maxbackupindex=1 log4j.appender.r.maxfilesize=5000kb log4j.appender.r.layout.conversionpattern=%d{dd-mm-yyyy HH:mm:ss,SSS z} %-5p [%t] [%c{1}@%l] %m%n log4j.appender.r.layout=org.apache.log4j.patternlayout log4j.appender.r=org.apache.log4j.rollingfileappender ## ## Disable overly verbose logging ## log4j.logger.org.apache.http=error log4j.logger.org.springframework.web.client.resttemplate=error log4j.logger.org.hyperic.hq.measurement.agent.server.senderthread=info log4j.logger.org.hyperic.hq.agent.server.agentdlistprovider=info log4j.logger.org.hyperic.hq.agent.server.measurementschedule=info log4j.logger.org.hyperic.util.units=info log4j.logger.org.hyperic.hq.product.pluginxml=info # Only log errors from naming context log4j.category.org.jnp.interfaces.namingcontext=error log4j.category.org.apache.axis=error #Agent Subsystems: Uncomment individual subsystems to see debug messages. #----------------------------------------------------------------------- #log4j.logger.org.hyperic.hq.autoinventory=debug #log4j.logger.org.hyperic.hq.livedata=debug #log4j.logger.org.hyperic.hq.measurement=debug #log4j.logger.org.hyperic.hq.control=debug #Agent Plugin Implementations #log4j.logger.org.hyperic.hq.product=debug #Server Communication #log4j.logger.org.hyperic.hq.bizapp.client.agentcallbackclient=debug #Server Realtime commands dispatcher #log4j.logger.org.hyperic.hq.agent.server.commanddispatcher=debug #Agent Configuration parser #log4j.logger.org.hyperic.hq.agent.agentconfig=debug #Agent plugins loader #log4j.logger.org.hyperic.util.pluginloader=debug #Agent Metrics Scheduler (Scheduling tasks definitions & executions) #log4j.logger.org.hyperic.hq.agent.server.session.agentsynchronizer.schedulerthread=debug #Agent Plugin Managers #log4j.logger.org.hyperic.hq.product.measurementpluginmanager=debug 28 VMware, Inc.
Chapter 1 Configuring and Running a vrealize Hyperic Agent #log4j.logger.org.hyperic.hq.product.autoinventorypluginmanager=debug #log4j.logger.org.hyperic.hq.product.configtrackpluginmanager=debug #log4j.logger.org.hyperic.hq.product.logtrackpluginmanager=debug #log4j.logger.org.hyperic.hq.product.livedatapluginmanager=debug #log4j.logger.org.hyperic.hq.product.controlpluginmanager=debug jboss.installpath Specifies the location of the JBoss root directory to enable the agent to monitor JBoss. /usr/local/jboss-4.0.0 platform.log_track.eventfmt Property Specifies the content and format of the Windows event attributes that a vrealize Hyperic agent includes when logging a Windows event as an event in vrealize Hyperic. By default, the agent.properties file does not include this property. When Windows log tracking is enabled, an entry in the form [Timestamp] Log Message (EventLogName):EventLogName:EventAttributes is logged for events that match the criteria you specified on the resource's Configuration Properties page. Attribute Timestamp Log Message EventLogName EventAttributes Description When the event occurred A text string The Windows event log type System, Security, or Application A colon delimited string made of the Windows event Source and Message attributes For example, the log entry: 04/19/2010 06:06 AM Log Message (SYSTEM): SYSTEM: Print: Printer HP LaserJet 6P was paused. is for a Windows event written to the Windows System event log at 6:06 AM on 04/19/2010. The Windows event Source and Message attributes, are "Print" and "Printer HP LaserJet 6P was paused.", respectively. Configuration Use the following parameters to configure the Windows event attributes that the agent writes for a Windows event. Each parameter maps to Windows event attribute of the same name. Parameter %user% %computer% %source% %event% %message% %category% Description The name of the user on whose behalf the event occurred. The name of the computer on which the event occurred. The software that logged the Windows event. A number identifying the particular event type. The event message. An application-specific value used for grouping events. VMware, Inc. 29