After perfino is installed, the agent can be added to JVMs on the local machine and on remote machines.
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
To get started, click on the "Add VMs" button in the header.
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.
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
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.
If you monitor multiple VMs, you have to give them names in order to be able to identify them in the
perfino UI. To assign a VM name, pass the
name option to the
-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
-javaagent parameter looks like this:
VM names must be unique within the same group.
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:
group option, the
pool option takes a hierarchical name with
forward slashes as the hierarchy separator. If
pool is specified, you cannot
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.
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
This is necessary if the port is already in use or if you install multiple instances of perfino on the same
To tell the agent about such a non-default port, you have to add the
port option to the
-javagent VM parameter. For example:
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
where <VM name> is the value of the
name or the
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.
Mutual authentication and encryption are enabled by the agent
agent.ks in the same directory as the
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
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 onLocate
[perfino data directory]/ssl/agent.ksand 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 offDelete the file
agent.ksnext to the file
perfino.jarin 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
option to the
-javagent VM parameter. For example: