Pulse Quick Start (Embedded Mode)

Use Pulse in embedded mode to monitor a GemFire deployment directly from a GemFire JMX Manager. By default, the embedded Pulse application connects to the local JMX Manager that hosts the Pulse application. Optionally, configure Pulse to connect to a GemFire system of your choice.

Note: GemFire cannot start Pulse in embedded mode if you run the GemFire member itself inside of a Tomcat server instance. GemFire displays an error message if you attempt to start an embedded Pulse application using this configuration. See Hosting Pulse on a Web Application Server instead.
To run Pulse in embedded mode:
  1. Configure a GemFire member to run as a JMX Manager node, specifying the HTTP port on which you will access the Pulse Web application. For example, the following command starts a GemFire locator as a JMX Manager node, using the default HTTP port 8080 for the Pulse application:
    gfsh
    gfsh> start locator --name=loc1
    Note: GemFire locators become JMX Manager nodes by default. To start a non-locator member as a JMX Manager node, include the --J=-Dgemfire.jmx-manager=true option. To specify a non-default port number for accessing the Pulse application, include the --J=-Dgemfire.jmx-manager-http-port=port_number option when starting the JMX Manager node.

    When the JMX Manager node boots, it starts an embedded Tomcat instance and deploys the Pulse Web application at the specified or default HTTP port.

    gfsh automatically connects to the manager when you start it in this way. If you already started a manager process earlier, use the connect command in gfsh to connect to that process.

  2. Access the embedded Pulse application from a Web browser. If you are connected to the GemFire cluster using gfsh, use the start pulse command to load the correct URL in your browser:
    gfsh> start pulse

    Or, enter the URL http://address:jmx-manager-http-port/pulse directly in your Web browser, substituting the address and HTTP port of the manager. For example, you access Pulse on the local locator machine from Step 1 at the URL http://localhost:8080/pulse.

  3. If you have configured authentication for the Pulse application, enter the username and password of a valid Pulse account in the login screen. Otherwise, enter the default "admin" in both fields. Click Sign In to continue.

    See Configuring Pulse Authentication.

  4. After you log in, Pulse displays the main cluster view for the local distributed system. See Using Pulse Views.
Note: When running in embedded mode, the Pulse application connects only to the JMX Manager running in the locator or member that hosts Pulse. This enables you to monitor all members of that distributed system. You can also view (but not monitor) connected WAN clusters, and can view gateway senders and receivers that are configured in the local cluster.

Hosting Pulse on a Web Application Server

Host Pulse on a dedicated Web application server to make the Pulse application available at a consistent address, or to use SSL for accessing the Pulse application. When you host Pulse in this way, you also configure Pulse to connect to a specific locator or JMX Manager node for monitoring.

To host Pulse on a Web application server:
  1. Set the jmx-manager-http-port property to zero (-Dgemfire.jmx-manager-http-port=0) when you start your GemFire JMX Manager nodes. Setting this property to zero disables the embedded Web server for hosting the Pulse application.
  2. Create a pulse.properties file somewhere in the classpath of your Web application server. For example, if you are hosting Pulse on Tomcat, create the pulse.properties file in the $TOMCAT_SERVER/lib directory.

  3. Define the following configuration properties in the pulse.properties file:
    Property Description
    pulse.useLocator Specify "true" to configure Pulse to connect to a GemFire Locator member, or "false" to connect directly to a JMX Manager.

    When Pulse connects to a GemFire locator, the locator provides the address and port of an available JMX Manager to use for monitoring the distributed system. In most production deployments, you should connect Pulse to a locator instance; this allows Pulse to provide monitoring services using any available JMX Manager.

    If you specify "false," Pulse connects directly to a specific JMX Manager. If this manager is not available, the Pulse connection fails, even if another JMX Manager is available in the distributed system.

    pulse.host Specify the DNS name or IP address of the GemFire locator or JMX Manager machine to which Pulse should connect. You specify either a locator or JMX Manager address depending on how you configured the pulse.useLocator property.
    pulse.port Specify the port number of the GemFire locator or the HTTP port number of the JMX Manager to which Pulse should connect. You specify either a locator or JMX Manager port depending on how you configured the pulse.useLocator property.

    If you configured pulse.useLocator=false, then pulse.port must correspond to the jmx-manager-http-port setting of the JMX Manager.

    pulse.jmxUserName If you configured authentication for the GemFire JMX Manager node, specify a valid JMX user name that the Pulse application will use to authenticate to the JMX Manager.
    Note: The JMX account that Pulse uses must have both read and write privileges.

    See Configuring a JMX Manager for information about configuring authentication for JMX Manager nodes.

    pulse.jmxUserPassword Specify the password of the JMX user account to use for authentication at startup.
    For example, with this configuration Pulse connects to the locator at mylocator[10334] and accesses any available JMX Manager:
    pulse.useLocator=true
    pulse.host=locsrv.gemstone.com
    pulse.port=10334
    pulse.jmxUserName=pulseapp
    pulse.jmxUserPassword=pulsepass
    With this configuration Pulse accesses only the JMX Manager instance at manager1[8080]:
    pulse.useLocator=false
    pulse.host=jmxsrv.gemstone.com
    pulse.port=8080
    pulse.jmxUserName=pulseapp
    pulse.jmxUserPassword=pulsepass
  4. (Optional.) Configure authentication for the Pulse Web application using the instructions in Configuring Pulse Authentication.
  5. Deploy the Pulse Web application to your application server. GemFire installs the pulse.war file in the tools/Pulse subdirectory of your GemFire installation directory. Depending on your application server, you may need to copy the pulse.war file to a deployment directory or use a configuration tool to deploy the file.
  6. Access the Pulse application using the address, port, and application URL that you configure in your Web application server. For the default Tomcat URL is http://address:8080/pulse. Your application server provides options for configuring the address, port, and application name; substitute the correct items to access the deployed Pulse application.

    Pulse connects to the locator or JMX Manager that you configured in the pulse.properties file, authenticating using the credentials that you configured in the file.

  7. If you have configured authentication for the Pulse application, enter the username and password of a valid Pulse account in the login screen. Otherwise, enter the default "admin" in both fields. Click Sign In to continue.

    See Configuring Pulse Authentication.

  8. After you log in, Pulse displays the main cluster view for the distributed system to which it has connected. See Using Pulse Views.

Configuring Pulse Authentication

Pulse requires all users to authenticate themselves before they can use the Pulse Web application. If you have configured JMX authentication on the GemFire JMX Manager node, the Pulse Web application itself may also need to authenticate itself to the GemFire JMX Manager node on startup.

Authenticating Pulse Users

By default, Pulse uses the Spring security framework to implement a simple, file-based authentication mechanism. You define the names and passwords for valid Pulse users in a pulse-users.properties file, which must be available in the classpath of the Pulse application. By default, GemFire installs a default pulse-users.properties in the WEB-INF subdirectory of the pulse.war file. Each line in this file defines the username, password, and access level for a Pulse user with the format:
username=password,role,{enabled | disabled}
The role entry must correspond to a valid Spring security role. For example, this entry shows the default "admin" user enabled with basic user access:
admin=admin,ROLE_USER,enabled

To define your own Pulse users, create a pulse-users.properties file with one account definition per line, and place the file in the classpath of your Pulse application before you deploy it. Only users that are specified in the pulse-users.properties can log into Pulse.

Authenticating Pulse to the JMX Manager

If you run Pulse in embedded mode, the Pulse application runs on the JMX Manager node and no JMX authentication is required. You do not need to specify valid JMX credentials to start an embedded Pulse application.

If you host Pulse on a Web Application server (non-embedded mode) and you configure JMX authentication on the GemFire manager node, then the Pulse Web application must authenticate itself with the manager node when it starts. Specify the credentials of a valid JMX user account in the pulse.properties file, as described in Hosting Pulse on a Web Application Server.

Note: The credentials that you specify must have both read and write privileges in the JMX Manager node. See Configuring a JMX Manager.

Using Pulse Views

Pulse provides a variety of different views to help you monitor GemFire clusters, members, and regions.

The following sections provide an overview of the main Pulse views:

Cluster View

The cluster view is a high-level overview of the GemFire distributed system. It is displayed immediately after you log into Pulse. Information displays around the perimeter of the cluster view show statistics such as memory usage, JVM pauses, and throughput.


Use these basic controls while in Cluster view:
  1. Click a host machine icon to display the GemFire members on that machine.
  2. Click the display icons to display the GemFire members using icon view, block view, or table view.

    While in block view or table view of the Cluster Members, click the name of a GemFire member to monitor that member. See Member View. For example, in table view, members are displayed similar to the following:

  3. In the Alerts pane, click the severity tabs to filter the message display by the level of severity.
  4. Click Data View to display region information for the entire cluster. See Data View.

Cluster View Screen Components

The following table describes the data pieces displayed on the Cluster View screen.
Screen Component Description
Cluster Status Overall status of the distributed system being monitored. Possible statuses include Normal, Warning, or Severe.
Total Heap Total amount of memory (in GB) allocated to the Java heap across all members.
Members Total number of members in the cluster.
Servers Total number of servers in the cluster.
Clients Total number of clients in the cluster.
Locators Total number of locators in the cluster.
Regions Total number of regions in the cluster.
Functions Total number of functions registered in the cluster.
Unique CQs Total number of unique CQs. Corresponds to the UNIQUE _CQ_QUERY statistic.
Subscriptions Total number of client event subscriptions.
Cluster Members Graphical, block, or table view of the members in the cluster.
Host Machine When you mouse over a machine icon in Graphical View, a pop-up appears with the following machine statistics:
  • CPU Usage. Percentage of CPU being used by GemFire processes on the machine.
  • Memory Usage. Amount of memory (in MB) being used by GemFire processes.
  • Load Avg. Average number of threads on the host machine that are in the run queue or are waiting for disk I/O over the last minutes. Corresponds to the Linux System statistic loadAverage1. If the load average is not available, a negative value is shown.
  • Threads. Number of threads running on the machine.
  • Sockets. Number of sockets currently open on the machine.
Member When you mouse over a machine icon in Graphical View, a pop-up appears with the following member statistics:
  • CPU Usage. Percentage of CPU being used by the GemFire member process.
  • JVM Pauses. Number of times the JVM used by the member process has paused due to garbage collection or excessive CPU usage.
  • Regions. Number of regions hosted on the member process.
  • Clients. Number of client currently connected to the member process.
  • Gateway Sender. Number of gateway senders configured on the member.
  • Port. Server port of the cache server member where clients can connect and perform cache operations.
Member In List View, the following data fields are displayed for each member:
  • ID. DistributedMember Id of the member.
  • Name. Name of the member.
  • Host. Hostname or IP address where the member is running.
  • Heap Usage. Amount of JVM heap memory being used by the member process.
  • CPU Usage. Percentage of CPU being used by the GemFire member process.
  • Uptime. How long the member has been up and running.
  • Clients. Number of clients currently connected to the member. It will have a value only if the member acts as a CacheServer.
Key Statistics Displays a few key performance measurements of the distributed system (over the last 15 minutes).
Write/Sec Number of write operations per second that have occurred across the cluster. Each put/putAll operation counts as a write; for example, a putAll of 50 entries is counted as one write.
Read/Sec Number of read operations per second that have occurred across the cluster.
Queries/Sec Number of queries per second that have been executed across the cluster.
No. of JVM Pauses Number of times the JVM has paused during the last five minutes to perform garbage collection.
WAN Information If you have configured gateway senders or receivers for a multi-site (WAN) deployment, this box displays whether the remote cluster is reachable (working connectivity represented by a green triangle).
Disk Throughput Total disk throughput for all disks in cluster.
Alerts View Displays alerts for the cluster.

Member View

When you select an individual GemFire member, Pulse displays the regions available on the member, as well as member-specific information such as the configured listen ports and WAN configuration.


Use these basic controls while in Member View:
  1. Click the display icons to display regions using block view or table view.
  2. Use the drop down to select a specific member or search for specific members by name.
  3. Click the main cluster tab to return to Cluster View. See Cluster View.
  4. Click Data View to display region information for the entire cluster. See Data View.

Member View Screen Components

The following table describes the data elements displayed on the Member View screen.
Screen Component Description
Member Status Overall status of the member being monitored. Possible statuses include Normal, Warning, or Severe.
Regions Total number of regions hosted on the member.
Threads Total number of threads being executed on the member.
Sockets Total number of sockets currently open on the member.
Load Avg. Average number of threads on the member that are in the run queue or are waiting for disk I/O over the last minute. Corresponds to the Linux System statistic loadAverage1. If the load average is not available, a negative value is shown.
Member Regions Block or table view of the regions hosted on the member.
Regions When you mouse over a region in block view, a pop-up appears with the following data fields:
  • Name. Region name.
  • Type. For example, REPLICATE, PARTITION.
  • EntryCount. Number of entries in the region.
  • EntrySize. The aggregate entry size (in bytes) of all entries. For replicated regions this field will only provide a value if the eviction algorithm has been set to EvictionAlgorithm#LRU_ MEMORY. All partition regions will have this value. However, the value includes redundant entries and will also count the size of all the secondary entries on the node.
Regions In table view, the following fields are listed for each region:
  • Name. Region name.
  • Type. For example, REPLICATE, PARTITION.
  • EntryCount. Number of entries in the region.
  • EntrySize. The aggregate entry size (in bytes) of all entries. For replicated regions this field will only provide a value if the eviction algorithm has been set to EvictionAlgorithm#LRU_ MEMORY. All partition regions will have this value. However, the value includes redundant entries and will also count the size of all the secondary entries on the node.
  • Scope. Scope configured for the region.
  • Disk Store Name. Name of disk stores (if any) associated with the region.
  • Disk Synchronous. True if writes to disk are set to synchronous and false if not. This field reflects the configured disk-synchronous region attribute.
  • Gateway Enabled. Whether gateway sender and receiver configurations have been defined on members hosting this region.
Member Clients In table view, the following fields are listed for each client:
  • Id. DistributedMember ID of the client process.
  • Name. Name of the client process.
  • Host. Hostname or IP address of the client process.
  • Connected. Whether the client process is currently connected to the member.
  • Queue Size. The size of the queue used by server to send events in case of a subscription enabled client or a client that has continuous queries running on the server.
  • CPU Usage. Percentage of CPU being used by the client process.
  • Uptime. Amount of time the client process has been running.
  • Threads. Threads being used by the member clients
  • Gets. Total number of successful get requests completed.
  • Puts. Total number of successful put requests completed.
Key Statistics Displays a few key performance measurements for the member (over the last 15 minutes).
% CPU Usage Percentage of CPU used by the member.
Write/Sec Number of write operations per second that have occurred on the member. Each put/putAll operation counts as a write; for example, a putAll of 50 entries is counted as one write.
Read/Sec Number of read operations per second that have occurred on the member.
Memory Usage Total memory used on the member in MB.
No. of JVM Pauses Number of times the JVM has paused during the last five minutes due to garbage collection or excessive CPU usage.
WAN Information Displays cluster information. This dialog box only appears if you have configured WAN functionality (gateway senders and gateway receivers).
Disk Throughput Rate of disk writes on the member.

Data View

The Pulse Data View provides a comprehensive overview of all regions in the GemFire distributed system:


Use these basic controls while in Data View:
  1. Click a region to display more information about that region.
  2. Click the display icons to display regions using block view or table view.
  3. Search for specific members that host the selected regions.
  4. Click the main cluster tab to return to Cluster View. See Cluster View.

Data View Screen Components

The following table describes the data elements displayed on the Data View screen.
Screen Component Description
Regions Summary Lists information about regions in the cluster, either in block view or table view.
Regions When you mouse over a region in block view, a pop-up appears with the following data fields:
  • Name. Region name.
  • Type. For example, REPLICATE, PARTITION.
  • EntryCount. Number of entries in the region.
  • EntrySize. The aggregate entry size (in bytes) of all entries. For replicated regions this field will only provide a value if the eviction algorithm has been set to EvictionAlgorithm#LRU_ MEMORY. All partition regions will have this value. However, the value includes redundant entries and will also count the size of all the secondary entries on the node.
Regions In table view, the following fields are listed for each region:
  • Name. Region name.
  • Type. For example, REPLICATE, PARTITION.
  • EntryCount. Number of entries in the region.
  • EntrySize. The aggregate entry size (in bytes) of all entries. For replicated regions this field will only provide a value if the eviction algorithm has been set to EvictionAlgorithm#LRU_ MEMORY. All partition regions will have this value. However, the value includes redundant entries and will also count the size of all the secondary entries on the node.
  • Scope. Scope configured for the region.
  • Disk Store Name. Name of disk stores (if any) associated with the region.
  • Disk Synchronous. True if writes to disk are set to synchronous and false if not. This field reflects the configured disk-synchronous region attribute.
  • Gateway Enabled. Whether gateway sender and receiver configurations have been defined on members hosting this region.
Region Detail When you have selected a region, the right hand pane displays the following information about the region:
  • Region Path. Path for the region.
  • Name. Name of the region.
  • Type. For example, REPLICATE, PARTITION
  • Members. Members that are hosting the region.
  • Write/Sec. Number of write operations per second that have occurred in the region. Each put/putAll operation counts as a write; for example, a putAll of 50 entries is counted as one write.
  • Read/Sec. Number of read opertaions per second that have occurred in the region.
  • Empty Nodes. Nodes where the region DataPolicy is defined as EMPTY or where LocalMaxMemory is set to 0.
  • Entry Count. Total number of entries in the region.
  • Persistence. ON or OFF. Whether disk peristence has been enabled for this region.
  • Memory Usage. "Used" corresponds to the amount of memory currently used by the region. The "Total" amount corresponds to total amount of memory allocated. A graph below displays the percentage view of memory being used.
  • Region Members. Lists the member where the region is hosted.
  • Reads. Rate of read/write across all members. The rate is defined as number of Reads/Writes per sampling interval. Sampling interval is the statistic-sample-rate defined while configuring the system. Default sampling interval is 1000 milliseconds.
  • Writes. Rate of read/write across all members. The rate is defined as number of Reads/Writes per sampling interval. Sampling interval is the statistic-sample-rate defined while configuring the system. Default sampling interval is 1000 milliseconds.

Alerts Widget

The Alerts Widget appears in the right portion of the screen and displays a list of alerts.

The alerts displayed for the cluster appear based on the alertLevel field set in the DistributedSystemMXBean. By default, log messages with the level of SEVERE are shown as alerts. You can modify the level by using the DistributedMXBean.changeAlertLevel method. See System Alert Notifications ofr more information.

Use these basic controls in the Alerts Widget:
  1. Select an alert level to view only alerts with a specific severity.
  2. Enter text in the search box to filter the list of alerts.
  3. Select an alert and click Clear to remove it from the alert list.
  4. Click Clear All to remove all alerts from the widget.
  5. Double-click an alert to open a pop-up window that displays the full text of the alert message.
  6. Click the check mark in an alert pop-up window to acknowledge the alert. Acknowledged alerts display a check mark in the list of alerts.
  7. Triple-click the alert in the pop-up or in the alert list to select the message text. You can then copy and paste the text into another application.
  8. Click the X to close the pop-up alert window.