Documentation

User Guide

This is the latest user guide for Thermostat 1.99.x. For older guides see the Archives

Component Overview

Storage

The Storage is where data gets stored. Currently, Thermostat supports Mongodb backends.

Web Endpoint

The Web Endpoint is an HTTP layer that runs in front of the Storage. By using the web endpoint, the Storage can be hidden from direct connection while Agents and Clients connect with credentials through HTTP.

Agent

The Agent monitors JVMs that run on the machine with the same userid as the Agent, storing the data through the Web Endpoint or directly into the Storage. The Agent also listens on a Command Channel for Client requests such as heap dumping or full garbage collection on JVMs being monitored. Agents require a valid Storage connection to start.

GUI and CLI Client

The Clients allow for displaying of data from the Storage (through the Web Endpoint or directly from Storage) as well as performing actions on JVMs such as a heap dump or full garbage collection through the Command Channel with the Agent. Clients require a valid Storage connection for most functions as well as a valid Agent connection for Command Channel actions.

Local Setup Tutorial

This tutorial will guide you through setting Thermostat up on a single machine. The machine will hold the Storage, accessed through HTTP via the Web Endpoint, the Agent which will monitor all JVMs on the machine and view the data through GUI or CLI Client.

The quickest way is to run the local command.

$ thermostat local

This starts the Agent (monitors jvms), the Web-Storage (stores data) and the GUI (displays data) all on your local machine.

Each component can be started individually or chained in certain configurations. For example, the local command chains the Storage, Web Endpoint (collectively referred to as Web-Storage), Agent and GUI in a single command.

The Storage, Web Endpoint and Agent can be started via:

$ thermostat web-storage-service

The Storage and Web Endpoint can be started via:

$ thermostat web-storage

The Storage can be started and stopped via:

$ thermostat storage --start

$ thermostat storage --stop

The Agent can be started via:

$ thermostat agent

The GUI Client can be started via:

$ thermostat gui

Distributed Setup Tutorial

This tutorial will guide you through setting Thermostat up on multiple machines. One machine will hold the Storage, accessed through HTTP via the Web Endpoint. One or more machines will hold the Agent, monitoring any JVMs on the machine and sending data to the Storage. One machine will view the data via GUI or CLI Client.

Any machine that is part of the distributed setup needs Thermostat installed. All machines should have the same version of Thermostat.

Storage And Web Endpoint Setup

To setup the Storage on a machine for remote access through HTTP it must be configured to bind to a proper IP address and port of the machine and have authentication for users.

First we setup the Mongodb backend and user authentication with:

$ thermostat setup -c

This runs the CLI setup, asking you to input the username/passwords for the Mongodb backend, default client user and default agent user. The Mongodb credentials are used by the Web Endpoint to connect to the local Mongodb backend. The default client user credentials are used by Clients to connect to the Web Endpoint. Likewise, the default agent user credentials are used by Agents to connect to the Web Endpoint. These credentials should be remembered for later use.

Next, the Web Endpoint needs to be configured to bind to the host machine's IP Address. This is done with the configuration file THERMOSTAT_HOME/etc/db.properties or USER_THERMOSTAT_HOME/etc/db.properties. The settings in USER_THERMOSTAT_HOME override those in THERMOSTAT_HOME.

The BIND and PORT fields should be set to the machine's IP address and a free port. For a machine with ip 192.168.0.1 and free port 27518, the db.properties file would look like:

BIND=192.168.0.1
PORT=27518

Finally, the Storage and Web Endpoint can be started via:

$ thermostat web-storage

The Web Endpoint can be accessed at http://192.168.0.1:27518/thermostat/storage (replace IP and Port with appropriate values for your setup). Accessing the URL through a web browser should bring up an authentication prompt if the Storage and Web Endpoint are setup successfully.

Agent Setup

To setup the Agent on a machine it must be configured to connect to the Web Endpoint via URL.

First, prevent setup from occurring by creating the file: USER_THERMOSTAT_HOME/data/setup-complete.stamp

Next, configure the agent to bind it's Command Channel to a remotely accessible IP address and to connect to the Web Endpoint via URL. This is done with the file: USER_THERMOSTAT_HOME/etc/agent.properties The CONFIG_LISTEN_ADDRESS property should be set to a remotely accessible IP address and free port and the DB_URL property should be set to the URL that the Web Endpoint is accessible on. For a machine with ip 192.168.0.2 and free port 12000, connecting to a Web Endpoint at 192.168.0.1:27518, the agent.properties file would look like:

CONFIG_LISTEN_ADDRESS=192.168.0.2:12000
DB_URL=http://192.168.0.1:27518/thermostat/storage

After this, set the credentials to be used in the file: USER_THERMOSTAT_HOME/etc/agent.auth These are used when connecting to the Web Endpoint and should be the same as the default agent user credentials in the setup for Storage and Web Endpoint. An example agent.auth file looks like:

username=agentuser
password=agentpassword

Finally, the Agent can be started via:

$ thermostat agent

Client Setup

To setup the Client on the machine it must be configured to connect to the Web Endpoint via URL.

First, prevent setup from occurring by creating the file: USER_THERMOSTAT_HOME/data/setup-complete.stamp

For the GUI Client, start via:

$ thermostat gui

A connection failed prompt will appear. Click "Configure..." and a dialog will appear where you can fill in the URL to connect to and the credentials to use. The URL is the URL of the Web Endpoint, e.g. http://192.168.0.1:27518/thermostat/storage. The credentials are for the default client user that was setup on the Storage and Web Endpoint machine.

For the CLI Client, start via:

$ thermostat shell

This enters the CLI terminal where you can connect to the Web Endpoint via:

connect -d http://192.168.0.1:27518/thermostat/storage

Replace the argument for -d with the correct URL for your Web Endpoint. The terminal will then prompt you for credentials to use. Once successfully connected, other CLI commands that use the Web Endpoint will use the one specified in the connect command.

CLI Features

The easiest way to see what features the CLI has is to run the help command.

$ thermostat help

Thermostat offers CLI through invocations of thermostat, for example:

$ thermostat list-vms

Thermostat also offers a Shell that can be started via:

$ thermostat shell

This brings up the Shell, printing the version and the prompt and then waiting for command input. Run 'help' to list all the commands available in the Shell.

Thermostat version 1.99.12
Please see the User Guide at http://icedtea.classpath.org/wiki/Thermostat/UserGuide
Thermostat - > 

GUI Features

Host Machine Information

  • Hardware/Network Information
  • CPU/Memory Usage
  • NUMA Allocation Data

JVM Information

  • JVM Process Information
  • CPU/Memory Usage
  • GC, Heap, Threads, Stack Trace, IO, Compiler, Class Information
  • NUMA Allocation Data for NUMA Aware systems

JVM Actions

  • Kill a JVM
  • Perform a full GC
  • Create a Heap Dump and analyze it in GUI
  • Profile JVM
  • Inject Byteman rules and view results
  • Detect deadlocks

Terminology

This section contains description for terminology used in the User Guide.

THERMOSTAT_HOME

THERMOSTAT_HOME refers to the install location of Thermostat. This location is usually owned by root. For an RPM based installation this is:

/usr/share/thermostat

For compilations from source (tarballs, cloned repository) this is:

{source-location}/distribution/target/image

USER_THERMOSTAT_HOME

USER_THERMOSTAT_HOME refers to the configuration and data location of Thermostat in the user's home directory. For user "someuser" this is:

/home/someuser/.thermostat

There are also a lot of resources in the Thermostat wiki targeting developers.

Wiki