Pulse Quick Start (Embedded Mode)

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

Note: GemFire XD cannot start Pulse in embedded mode if you run the GemFire XD member itself inside of a Tomcat server instance. GemFire XD displays an error message if you attempt to start an embedded Pulse application using this configuration. See Hosting Pulse on a Web Application Server.

About JMX Managers

A JMX Manager node is a member of a distributed system that can manage itself and other GemFire XD nodes. A distributed system has only one JMX manager. Any GemFire XD member can become a JMX Manager.

When a JMX Manager runs in embedded mode, the Pulse Web application is hosted on an embedded application server and the Pulse application connects to this local JMX Manager. You can also configure your system so that the Pulse Web application runs in a Web Application server (such as Tomcat, TC Server, or WebLogic). When the Pulse application launches, you specify a locator or JMX Manager URL. If you specify a locator, the locator searches for potential JMX Managers within the distributed system. If none are found, the locator becomes the JMX Manager. You can also specify that the application connect directly to a specific JMX Manager.

Note: Pivotal recommends that you run a JMX Manager that is embedded in a locator only in development environments. In production systems, you should assign a separate member as manager of the system. This member can run Pulse in embedded mode, but that should be the only task assigned to that member.

See Using a JMX Manager Node.

Running Pulse in embedded mode

To run Pulse in embedded mode:

Configure a GemFire XD 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 gfxd command starts a GemFire XD locator as a JMX Manager node, using the default HTTP port 7070 for the Pulse application.
```
>gfxd locator start -dir=locatorDir -jmx-manager-start=true
```
Note: GemFire XD locators become potential JMX Manager nodes by default. To start a non-locator member as a JMX Manager node, also include the -jmx-manager=true option. To specify a non-default port number for accessing the Pulse application, include the -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.
Access the embedded Pulse application from a Web browser. 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 described in Step 1 at the URL http://localhost:7070/pulse.
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.
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:

Set the jmx-manager-http-port property to zero (-jmx-manager-http-port=0) when you start your GemFire XD JMX Manager nodes. Setting this property to zero disables the embedded Web server for hosting the Pulse application.
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.

Define the following configuration properties in the pulse.properties file:

Property	Description
`pulse.useLocator`	Specify `true` to configure Pulse to connect to a GemFire XD Locator member, or `false` to connect directly to a JMX Manager. When Pulse connects to a GemFire XD 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 XD 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 XD 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 XD 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 Using a JMX Manager Node 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.
`pulse.product`	Set the value of this property to `gemfirexd`.

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
pulse.product=gemfirexd

With this configuration Pulse accesses only the JMX Manager instance at manager1[7070]:

pulse.useLocator=false
pulse.host=jmxsrv.gemstone.com
pulse.port=7070
pulse.jmxUserName=pulseapp
pulse.jmxUserPassword=pulsepass
pulse.product=gemfirexd

(Optional.) Configure authentication for the Pulse Web application using the instructions in Configuring Pulse Authentication.
Deploy the Pulse Web application to your application server. GemFire XD installs the pulse.war file in the tools/Pulse subdirectory of your GemFire XD 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.
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:7070/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.
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.
After you log in, Pulse displays the main cluster view for the distributed system to which it has connected. See Using Pulse Views.
If a JMX manager or locator is configured to use SSL, you can configure Pulse to connect to these processes. Create a file named pulsesecurity.properties and save it somewhere in the classpath of your Web application server. Include standard Java SSL properties, such as:
```
javax.net.ssl.keyStore={KeyStorePath}
javax.net.ssl.keyStorePassword={KeyStorePassword}
javax.net.ssl.trustStore={TrustStorePath}
javax.net.ssl.trustStorePassword={TrustStorePassword}
```

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 XD JMX Manager node, the Pulse Web application itself may also need to authenticate itself to the GemFire XD JMX Manager node on startup.

Authenticating the Pulse Application 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 XD 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 Configuring Pulse Authentication.

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

Authenticating Pulse Users

Pulse implements user authentication using the Spring security framework. The authentication configuration is specified in the spring-security.xml file, which is stored in the WEB-INF directory of Pulse WAR file. The spring-security.xml file contains bean definitions for role-based resource access, authentication profiles, and authentication handlers. The file also contains a default authentication manager bean definition.

Pulse uses a profile-based authentication configuration. You can choose to use either the default configuration profile or a custom configuration. The default profile uses the Spring security simple in-memory User Details Service to define a single user with the credentials:

User Name:	admin
Password:	admin
Role:	ROLE_USER

Pulse uses this default authentication profile if you do not specify a profile when starting the application, or if you specify the default profile at startup using the system property:

-Dspring.profiles.active=pulse.authentication.default

You can also configure Pulse to use a custom authentication configuration by specifying activating the custom profile at startup with the system property:

-Dspring.profiles.active=pulse.authentication.custom

Using a custom configuration enables you to use one or more different authentication providers to authenticate users to the application. For example, you may choose to authenticate users using an LDAP provider and/or an external properties file. Even if you choose to use the Spring security simple in-memory User Details Service, using a custom authentication configuration enables you to define your own user credentials rather than using the default "admin" account.

To configure and use a custom authentication configuration:

Create a directory in which you will store the custom authentication configuration. For example:
```
$ mkdir /opt/pulse-config
```
Ensure that the new directory you created is available on the Java class path. For example:
```
$ export CLASSPATH=$CLASSPATH:/opt/pulse-config
```
Create a new text file named pulse-authentication-custom.xml in the new directory:
```
$ touch /opt/pulse-config/pulse-authentication-custom.xml
```
Use a text editor to add the bean definitions for the authentication managers and providers that you want to use. The following listings show the example file contents for using the in-memory User Details Service and external properties file, and LDAP:
Example pulse-authentication-custom.xml for Spring simple in-memory User Details Service
```
<beans:beans >
  <authentication-manager>
    <authentication-provider>
      <user-service id="userDetailsService">
        <user name="john" password="johnspassword" authorities="ROLE_USER " />
        <user name="bob" password="bobspassword" authorities="ROLE_USER" />
      </user-service>
    </authentication-provider>
  </authentication-manager>
</beans:beans>
```
Example pulse-authentication-custom.xml for external properties file
```
<beans:beans >
  <authentication-manager>
    <authentication-provider>
      <user-service properties="classpath:pulse-users.properties">
      </user-service>
    </authentication-provider>
  </authentication-manager>
</beans:beans>
```
With 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. Each line in the pulse-users.properties 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
```
Example pulse-authentication-custom.xml for LDAP
```
<beans:beans >
  <ldap-server url="ldap://pulseldap.com:389/dc=pulseldap,dc=com" />
    <authentication-manager>
      <ldap-authentication-provider
        user-dn-pattern="uid={0},ou=people"
        group-search-base="cn=gemfirePulse,ou=groups"
        group-search-filter="memberUid={1}" />
    </authentication-manager>
</beans:beans>
```
The LDAP configuration must specify the LDAP server to use for authentication. You can also specify the DN pattern, search base, and search filter to use when authenticating the Pulse user.
If you run Pulse in embedded mode, specify the custom authentication profile system property when you start members that run a JMX manager instance (-Dspring.profiles.active=pulse.authentication.custom). Also add the path to the pulse-authentication-custom.xml file to the class path, if you have not already added it to the CLASSPATH environment variable. For example:
```
$ gfxd locator start -jmx-manager-start=true -jmx-manager-http-port=7070 
-J-Dspring.profiles.active=pulse.authentication.custom -classpath=/opt/pulse-config
```
If you host the Pulse application in a Web Application server such as Tomcat, you must specify the custom authentication profile system property when you start the Web Application server (-Dspring.profiles.active=pulse.authentication.custom). Also add the path to the pulse-authentication-custom.xml file to the class path, if you have not already added it to the CLASSPATH environment variable.
For example, if you use Tomcat to host the Pulse application, you can specify items in the CATALINA_OPTS and CLASSPATH environment variables which are both defined in the %CATALINA_HOME%/bin/setenv.bat file. Create or edit the file to specify the lines shown in bold:
```
set CATALINA_OPTS=-Dspring.profiles.active=pulse.authentication.custom
set "CLASSPATH=/opt/pulse-config"
exit /b 0
```
After starting the JMX manager or Web Application server, access the Pulse log in screen and provide credentials that are authorized in the custom configuration.

Using Pulse Views

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

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

Cluster View

Cluster View provides a high-level overview of a GemFire XD distributed system. When you first log in to Pulse, Cluster View displays by default.

To open Cluster View, click Cluster View in the upper-left portion of the Pulse screen.

Pulse displays the following information about the cluster:

Overall status of the cluster
Memory usage
Disk throughput
Number of JVM pauses
Key statistics such as gets per second and puts per second
Note: The "gets" rate is updated only for queries that use a primary key lookup. Any other predicates having other columns in the WHERE clause do not affect this field, even if the column is an identity field.
Total heap memory used
The number of members, servers, clients, locators, tables, and procedures defined in the cluster
The number of committed and rolled back transactions
Alerts

Cluster View

Use these basic controls while in Cluster view:

Click a host machine icon to display the GemFire XD members on that machine.
Click the display icons to display the GemFire XD members using icon view, block view, or list view.
Icon View displays each member as an icon and shows its relationship to other members. Click on an icon to open the Member View for the member.

Block View displays each member as a rectangle. The size of each rectangle represents the relative memory usage of each member. Hover the cursor over a block to see information about the member. Click on a block to open the Member View for the member.

List View displays members in a list. Click on a member row to open Member View for the member.
Click Data View to display table information for the entire cluster. See Data View.
Click the severity tabs in the Alerts Widget to filter the message display by the level of severity. See Alerts Widget.

Member View

When you select an individual GemFire XD member, Pulse displays the tables available on the member, as well as the following member-specific information:

The Number of tables, threads, and open file descriptors (Open FDs)
Load average
Off-heap free Size
Off-Heap used size
Information on Gateway Receivers and Gateway Senders
Memory usage
Disk throughput
Key statistics
Number of JVM pauses
Alerts

Member View

As shown in Figure 2, you can use these basic controls while in Member View:

Click the display icons to display tables using block view or list view.
Block view displays each table available on the member as a rectangle. The size of each rectangle represents the relative number of rows for each table. Hover the cursor over a block to see the name of the table, the type of table, the number of rows in the table, and its size in megabytes.

List View displays the same information as Block View but in tabular format.
Search for specific members by name.
Click the Cluster View tab to return to Cluster View.
Click Data View to display table information for the entire cluster. See Data View.

Data View

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

Data View

Note: For HDFS-persistent tables, all row count and disk space statistics apply only to the in-memory, operational data for the table. Data that is available in HDFS log files (but that is not in operational memory) is never considered for Pulse statistics.

Use these basic controls while in Data View:

Click the display icons to display tables using block view or list view.
Block view displays each table as a rectangle. The size of each rectangle represents the relative number of rows of each table. Hover the cursor over a block to see the name of the table, the type of table, the number of rows in the table, and its size in megabytes.

List View displays the same information in tabular format.
Click a table name to display the following additional information about the table:
- The type of table (replicated, partitioned, or HDFS-persistent partitioned)
- The number of members that host the table
- The number of empty nodes
- The number of rows in the table (for HDFS tables, Pulse displays only the in-memory row count)
- The amount of disk space used by the table
- Whether persistence is enabled
- Whether off-heap storage is enabled
- For HDFS-persistent tables, whether the table is write-only or read/write
- Memory usage
- Reads rate and average writes per second for memory and disk
  Note: The "reads" rate is updated only for queries that use a primary key lookup. Any other predicates having other columns in the WHERE clause do not affect this field, even if the column is an identity field.
Search for specific members that host the selected tables.
Click the main cluster tab to return to Cluster View.

Query Statistics View

Query Statistics View displays statistics about recent queries.

To use this view, launch the interactive gfxd command prompt, connect to your distributed system, and issue the following command to enable query statistics:

gfxd>call syscs_util.set_statement_statistics(1);

To open Query Statistics View, click Query Statistics in the upper-left portion of the Pulse screen.

Use these basic controls while using Query Statistics view:

Use the search box to filter the queries displayed from the entire list of queries. A maximum of 50 queries are viewable at one time.
Click on a column header to sort the queries by that column.

Query Statistics View

The Query Statistics View displays the following statistics.

Note: Except for NumExecutionsInProgress, all statistics apply only to the last sampling period. For example, NumRowsModified returns only the number of rows that were modified during the last sampling period, rather than the total number of rows modified by the query.

NumTimesCompiled—The number of times the statement was compiled (including recompilations) during the last sampling period.
NumExecution—The number of times the statement was executed during the last sampling period.
NumExecutionsInProgress—The number of statements that are actively being processed during the statistics snapshot of the sampling interval.
NumTimesGlobalIndexLookup—The number of times global index lookup message exchanges occurred during the sampling interval.
NumRowsModified—The number of rows modified by DML operations (insert/delete/update) during the sampling interval.
ParserTime—The time spent (in milliseconds) parsing the query string during the sampling interval.
BindTime—The time spent (in milliseconds) mapping the statement with the database object's metadata (binding) during the sampling interval.
OptimizeTime—The time spent (in milliseconds) determining the best execution path for this statement (optimizing) during the sampling interval.
RoutingInfoTime—The time spent (in milliseconds) compiling details about routing information of query strings to data node(s) (processQueryInfo) during the sampling interval.
GenerateTime—The time spent (in milliseconds) generating query execution plan definitions (activation class) during the sampling interval.
TotalCompilationTime—The total compilation time (in milliseconds) of the statement on this node (prepMinion) during the sampling interval.
ExecutionTime—The time spent (in nanoseconds) creating all the layers of query processing (ac.execute) during the sampling interval.
ProjectionTime—The time (in nanoseconds) to apply the projection and additional filters during the sampling interval.
TotalExecutionTime—The total execution time (in nanoseconds) taken to process the statement on this node (execute/open/next/close) during the sampling interval.
RowsModificationTime—The time taken (in nanoseconds) to modify rows by DML operation (insert/delete/update) during the sampling interval.
QNNumRowsSeen—The number of rows returned from remote nodes (ResultHolder/Get convertibles) during the sampling interval.
QNMsgSendTime—The TCP send time (in nanoseconds) of all the messages including serialization time and queue wait time during the sampling interval.
QNMsgSerTime—The serialization time (in nanoseconds) for all the messages while sending to remote node(s) during the sampling interval.
QNRespDeSerTime—The response message deserialization time (in nanoseconds) from remote node(s) excluding result set deserialization during the sampling interval.

Alerts Widget

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

Use these basic controls in the Alerts Widget:

Select an alert level to view only alerts with a specific severity.
Enter text in the search box to filter the list of alerts.
Select an alert and click Clear to remove it from the alert list.
Click Clear All to remove all alerts from the widget.
Double-click an alert to open a pop-up window that displays the full text of the alert message.
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.
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.
Click the X to close the pop-up alert window.

Alerts Widget

Parent topic: GemFire XD Pulse Parent topic: GemFire XD Pulse Parent topic: GemFire XD Pulse Parent topic: GemFire XD Pulse