After perfino is installed, the agent can be added to JVMs on the local machine and on remote machines.

Basic mechanism

The perfino agent is a Java agent. It is loaded into a VM by specifying the -javagent VM parameter. Java agents are able to instrument classes as they are loaded and to retransform classes that have already been loaded.

To prepare a VM for monitoring, you need the perfino agent files and you have to know the actual VM parameter that needs to be inserted into the start script of your application server or your application. In a production deployment, the monitored VMs will usually be running on different machines. You do not have to install perfino on those machines, you just download the agent files from the perfino UI. Also, you will get instructions on how to construct the correct -javaagent VM parameter.

To get started, click on the "Add VMs" button in the header.

perfino server and monitored VM running on the local machine

If the perfino UI server is running locally, the perfino agent is already available in the perfino installation directory and you can easily monitor a locally running VM. This is a likely scenario if you are evaluating perfino. In that case, you will be asked whether the VM is running on the local machine or on a remote machine.

The "Add VMs" dialog displays the complete -javaagent VM parameter for the simplest case without any further configuration. It is suitable for monitoring a single VM.

Further instructions regarding group and pool names are explained below.

perfino server and monitored VM running on the different machines

In the general case, where the perfino server and the monitored VMs are running on different machines, you can download the agent files from the dialog:

perfino has an integration with JProfiler that allows you to perform full sampling of a monitored VM and open the resulting snapshots in JProfiler. The libraries that implement full sampling are native libraries, and are included in the archive.

Depending on the selected option, a .zip or a .tar.gz file will be saved after clicking the Download button. Extract that archive anywhere on the computer where the monitored VM is running. In the top-level directory of that archive there is a file named perfino.jar, whose path will be referenced in the -javaagent VM parameter.

The VM parameter is not specified completely in the "Add VMs" dialog, since it depends on where you extract the archive and the name or IP address of the perfino server:

-javaagent:[path to perfino.jar]=server=[IP or host name]

Without the server option, the agent will assume that the perfino server is running on localhost.

Naming VMs

If you monitor multiple VMs, you have to give them names to be able to identify them in the perfino UI. To assign a VM name, pass the name option to the -javaagent VM parameter:

-javaagent:[path to perfino.jar]=server=[IP/host],name=[VM name]

Each name can only be used by one VM at the same time. A second VM that requests to be monitored with the same name will be rejected by the perfino server. If you have a pool of VMs that cannot be assigned with unique names, see the section on VM pools below.

In addition to the VM name, you can group VMs into a hierarchy. By default, a VM is inserted into the top-level group. To assign it to another group, set the group option in the VM parameter:

-javaagent:[path to perfino.jar]=server=[IP/host],name=[VM name],group=[group name]

In the group name, separate hierarchy levels with forward slashes, as in Web/Workers/Gen3. A complete -javaagent parameter looks like this:

-javaagent:/opt/perfino/perfino.jar=server=192.198.0.33,name=web,group=Web/Workers/Gen3

VM names must be unique within the same group.

VM pools

Sometimes it is not possible to configure VMs with unique names, for example, in a cloud environment where instances are provisioned dynamically. In that case, you can assign the VM to a VM pool:

-javaagent:/opt/perfino/perfino.jar=server=192.198.0.33,pool=Web/Workers

Like the group option, the pool option takes a hierarchical name with forward slashes as the hierarchy separator. If pool is specified, you cannot specify name or group and vice versa.

In a pool, a monitored VM is given a name with a unique identifier. When the VM detaches, this identifier will never be used again. Unlike for named VMs, the history of a single VM is limited to the connection time of that VM, so there is no associated long-term history. However, you can follow the history of the entire pool to analyze trends and make historical comparisons.

Server port

By default, a perfino server listens for VM connections on port 8847. This is the port that needs to be opened in firewalls to allow monitored VMs to reach the perfino server.

A perfino server may be configured to use a different port by adjusting the "vmPort" property in perfino.properties. This is necessary if the port is already in use or if you install multiple instances of perfino on the same machine.

To tell the agent about such a non-default port, you have to add the port option to the -javagent VM parameter. For example:

-javaagent:/opt/perfino/perfino.jar=server=192.198.0.33,port=8912,name=test

Logging

The perfino agent logs errors to the directory $HOME/.perfino/log on Linux/Unix or %USERPROFILE%\.perfino\log on Windows. Log files are created on demand, if nothing is logged, no file is created. The name of the log file is <VM name>.log where <VM name> is the value of the name or the pool parameter.

To log to a different file, you can add the logFile=<path to log file> option to the -javagent VM parameter. To disable logging altogether, the option logEnabled=false can be appended.

Encryption and authentication

Mutual authentication and encryption are enabled by the agent keystore file agent.ks in the same directory as the perfino.jar file. The agent keystore is generated by the server and is located in the ssl directory below the perfino data directory.

When the "vmUseSsl" property in perfino.properties is set to true, the agent keystore file is automatically added to the agent files that you download from the perfino UI. In that case, encryption and authentication work out of the box.

If you switch encryption and authentication on or off after you have set up your monitored VMs, you have to make the following changes manually:

• Switching encryption on

  Locate [perfino data directory]/ssl/agent.ks and copy it to the agent installations on all machines where VMs are monitored. The keystore file has to be copied to the same directory as the file perfino.jar. If the correct agent keystore is not present, the server will refuse the connection from the agent.

• Switching encryption off

  Delete the file agent.ks next to the file perfino.jar in the agent installations on all machines where VMs are monitored. If that file is present and the server does not use encryption, the agent will refuse to connect to it.

If you would like to keep the agent keystore file in a different path, add the keystore option to the -javagent VM parameter. For example:

-javaagent:/opt/perfino/perfino.jar=server=192.198.0.33,keystore=/sec/agent.ks,name=test