Agent startup checks
While starting the Agent, Plumbr goes through the following checks to verify the integrity of the installation:
- Verifying file system permissions: whether or not the folder Plumbr Agent resides and its subdirectories are readable and writable by the user launching the JVM Plumbr is attached to.
- Verifying the configuration: whether or not all the required configuration parameters are present and valid.
- Verifying the support for the environment: whether the OS, JVM and application server used are supported by Plumbr
- Verifying the connectivity: whether the Plumbr Agent can connect to Server.
- Verifying the Agent version: whether the Agent is still supported by the Server the Agent is connecting to
- Verifying the subscription: whether the account has an active subscription or has the subscription period expired
- Other miscellaneous checks, including but not limited to:
- If a proxy server is used to connect to Plumbr Server, then whether the proxy can be connected with the credentials provided
- Whether or not the jvmId parameter used to identify the JVM connecting to Server is unique
- Whether or not multiple JVMs are using the same Plumbr installation.
- Check for the jvmId does belong to the account it tries to connect to.
Some of the steps can fail due to various reasons. In such case the Agent will not be attached and the JVM starts without the Plumbr Agent monitoring the end user experience. The reason for the failure will be exposed in the server’s standard output.
So in order to find whether or not the Agent failed to initialize, search the log files for “Plumbr” phrase. In case you discover one of the error messages listed below, follow the instructions specified in the particular error message.
Verifying file system permissions
******************************************************************** * Plumbr encountered a filesystem permissions error. * * The user that runs your Java process has no write access to the * * /users/me/plumbr * * Plumbr needs write access to the whole directory. * * * * Please ensure that the user that runs your Java process has * * read and write permissions for that directory, * * its sub-directories and files inside it. * * * * Check out https://plumbr.io/support/agent-configuration * * for more information or contact support@plumbr.io * ********************************************************************
When you encounter this error message in log files, it indicates that the user launching the JVM Plumbr Agent is attached to does not have enough permissions to access the Plumbr Agent installation directory.
Plumbr Agent needs to be able to read and write the folder the Agent is installed (and its subdirectories). In order to proceed, you need to ensure the user running the Java process the Agent is attached to has read and write permissions for both the Agent’s installation folder and its subdirectories.
Verifying the configuration
****************************************************************************** * Plumbr is missing the following required properties: serverUrl. * * Either make sure the plumbr.properties file is present next to plumbr.jar * * or specify individual properties via -D parameters in your startup script. * * * * Check out https://plumbr.io/support/agent-configuration * * for more information or contact support@plumbr.io * ******************************************************************************
When you face such a banner in your JVM startup scripts then either the entire configuration stored in the file plumbr.properties file or some of the mandarory properties are missing. The plumbr.properties file is located next to the Plumbr Agent .jar file.
First step to overcome the problem is to make sure the Plumbr installation directory is intact and you have not extracted only the Agent’s plumbr.jar file. In case the file is present, check the content of the error message indicating the missing mandatory parameter(s) and add such parameters to the file. When in doubt, check the Agent Configuration page in our support materials.
An alternative to have the configuration present in the plumbr.properties file in the filesystem is to configure the Agent to specify parameters in the JVM startup script using -D parameters, prefixing each parameter with the “plumbr.” namespace. So, for example, you could specify the accountId, jvmId and serverUrl parameters for your JVM also via:
java -Dplumbr.accountId=a8nd2bar -Dplumbr.jvmId=BillingProduction -Dplumbr.serverUrl=https://app.plumbr.io
Verifying the support for the environment
********************************************************************************************** * Environment you are trying to run Plumbr in is not supported. * * Windows XP operation system is unsupported. Minimum supported Windows version is Windows 7.* * * * Check out the support page https://plumbr.io/support/is-my-environment-supported-by-plumbr * * for the list of supported environments. * **********************************************************************************************
When facing a banner similar to the one above in your log files, the environment the Plumbr Agent is running in is not supported by the Agent. The exact message will be different, depending on which unsupported operating system, JVM vendor/version or application server was detected in the environment.
To overcome the issue, consult the list of supported environments in our support documentation to find out whether or not you have a possibility to use Plumbr in an environment officially supported by Plumbr.
Verifying the connectivity
*********************************************** * Plumbr Server not responding - * * cannot connect to https://app.plumbr.io. * * Retrying in 60 seconds. * ***********************************************
*************************************************************** * Plumbr Server not responding - * * cannot connect to https://app.plumbr.io. * * Retrying in 60 seconds. * * * * In case your network configuration is blocking connections * * to Plumbr servers, see how to configure proxy server and/or * * firewall https://plumbr.io/support/network-configuration. * * * * In case your company policy does not allow using externally * * hosted services, try out Hosted Plumbr which does not * * require external network connections * * https://plumbr.io/support/hosted-plumbr * ***************************************************************
When you face a banner similar to the either of the above in your JVM log files, then it indicates the Agent deployed cannot connect to Plumbr Server over the network. Plumbr Agents will start without the presence of the Server, but as there is no endpoint to send the harvested data, then the Server cannot analyze the gathered data and thus you receive no value from Plumbr.
Pay attention that when the Server endpoint is just temporarily unavailable, the Agent will buffer the data locally. The Agent also periodically retries to connect to Server and when the Server (re)appears, the buffered data will be sent to Server.
To verify that the problem is related to network configuration only, try connecting to app.plumbr.io port 443 from the machine you are installing Plumbr, to see whether the connection is allowed. This can, for example, be achieved via telnet, similar to following:
$ telnet app.plumbr.io 443 Trying 54.171.1.110... Connected to app.plumbr.io Escape character is '^]'.
When the connection is successful, you should see a message Connected to app.plumbr.io, similar to the example above. When the connection fails, the network configuration is blocking connections to app.plumbr.io port 443.
To overcome the situation, connections via proxy servers or relaxing the firewall configuration are the first two options recommended. If you can not change the network configuration, you should turn to our On Premise offering where you can install the Server component in your network.
Verifying Agent version
During the startup, the Agent version will be compared to the Server version to verify whether or not the Agent is still supported by the Server the Agent is connecting to. In general we use the following policy for Agent version support
- Servers accept connections from Agents up to one year older than Servers. Agents older than one year will be rejected by Server.
- Servers will not be compatible with Agents released later than the Server.
Recommending to upgrade
************************************************************************************************ * You are using version 16.08.02 of Plumbr. We recommend upgrading to the latest version 12356. * * Download the latest version of the agent here: https://app.plumbr.io/download/agent/16.09.20 * ************************************************************************************************
When facing a banner like the one above, your currently used Agent is between 1 to 3 months behind the latest and greatest Agent available. As we add new features almost every month, you should consider upgrading, but you still have nothing to worry about.
Strongly recommending to upgrade
******************************************************************************************************** * You are using version 16.08.02 of Plumbr, which will be supported only until 2017-01-01 * * Download the latest version (16.12.12) of the agent here: https://app.plumbr.io/download/agent/16.12.12 * ********************************************************************************************************
When facing the banner above, your current Agent is between 3 and 6 months older than the Server the Agent connects to. The Server will still support the connecting Agent, but you should start planning for the Agent version upgrade t
Deprecated Agent version
******************************************************************************************************** * You are using deprecated version 16.08.02 of the Plumbr agent. * * Download the latest version (17.04.02) of the agent here: https://app.plumbr.io/download/agent/17.04.02 * ********************************************************************************************************
When facing the message above, then the Agent connecting to the Server is from 6 to 12 months older than the Server the Agent connects to. The version is already deprecated and will be unsupported when the 12 months limit will be hit. You should plan for Agent version upgrade as soon as possible.
Unsupported Agent version
************************************************************************************************************** * You are using unsupported version 16.08.02 of the Plumbr Agent, which can no longer connect to Plumbr Server. * * Please upgrade to the latest version of the agent from: https://app.plumbr.io/settings/download-center * **************************************************************************************************************
When seeing an error banner above, the Agent can no longer connect to the Server as the Agent version is older than the oldest Agent version supported by this particular Server. You need to upgrade to a new Agent version in order to proceed benefitting from Plumbr.
Agent version newer than Server version
************************************************************************************* * You are using unsupported version 16.08.02 of the Plumbr Agent * * Plumbr Server accepts only agents released before the server * * Please refer to Download Center https://app.plumbr.io/settings/download-center * * to get supported version of Plumbr Agent * *************************************************************************************
When facing an error message above in your JVM logs, the Agent connecting to the Server is newer than the Server. As Server accepts connections only from Agents it knew existed when the Server was released, this “agent from the future” is not allowed to connect.
When facing this message you are using our On Premise offering where you have installed the Server yourself. This means you have two options:
- Preferably you should upgrade the Server, so that new Agents with new and shiny features can apply all their new features in your deployment.
- If this is not possible, you need to use older Agent version, so that the Agent is not released later than the Server it connects.
Verifying the subscription
Plumbr is a subscription-based software with 14-day free trial subscription available. When the subscription has expired, the data on your account is kept for 10 more days, but you can no longer monitor the applications with Plumbr. After the 10 days have passed from your subscription expiring, the data on your account will be permanently deleted.
Expiration warning
*************************************************************************************** * Your subscription will expire on 2016-01-01. * * From 2016-01-01 Plumbr will not monitor your JVM(s) any more. * * To renew your subscription get in contact with Plumbr Sales at sales@plumbr.io. * ***************************************************************************************
When encountering such a warning in your log files, your subscription will expire soon. If you wish to benefit from Plumbr after the subscription period, you should start planning for the subscription extension.
Paid account expired
********************************************************************************************** * Your subscription expired on 2016-01-01 and Plumbr is not monitoring your JVM(s) any more. * * Your data will be available for 10 days, after which your account will be deleted. * * To renew your subscription go to https://app.plumbr.io/payment * **********************************************************************************************
If you encounter the message above, it means your subscription has expired. The data is still present on your account, but you can no longer monitor any JVMs. Whenever the 10 days have passed from the subscription expiration, the data will be permanently deleted.
To keep benefitting from Plumbr, extend your subscription.
Paid account deleted
****************************************************************************** * As you subscription was not renewed your Plumbr account has been deleted * * and you cannot monitor your JVM(s) with Plumbr any longer. * * To start monitoring your JVM(s), sign up and purchase Plumbr * * one year subscription: https://app.plumbr.io/payment * ******************************************************************************
Encountering the message above indicates your subscription has expired and more than 10 days have passed from the expiration date. The data on your account has been deleted.
The way to start reusing Plumbr is to purchase a new subscription.
Trial account expired
*************************************************************************************** * Your free trial is now expired and Plumbr is not monitoring your JVM(s) any more. * * Your data will be available for 10 days, after which your account will be deleted. * * To activate your account go to https://app.plumbr.io/payment *
The message above indicates that the free trial you used has expired. You can no longer monitor the JVMs with Plumbr. The data gathered during the trial is still available for you until 10 days have passed from the trial expiration. After this, the data on your account will be permanently deleted.
Trial account deleted
************************************************************************************* * As your free trial expired your Plumbr account has been deleted and you cannot * * monitor your JVM(s) with Plumbr any longer. To start monitoring your JVM(s), * * sign up and purchase Plumbr subscription: https://app.plumbr.io/payment * *************************************************************************************
The banner indicates that your free trial has been expired and the data on your account has been deleted.
If the trial demonstrated the value of Plumbr to you, then the way to keep using Plumbr is to switch to a paid subscription.
Miscellaneous checks.
Besides the categories above, Plumbr Agent performs a number of other checks, which can also result in error/warnings being printed into the JVM standard output.
Connecting to wrong Server
*************************************************************************************************** * The account does not exist at htts://my-plumbr-sever-installation:8080/. * * Check plumbr.properties to make sure you are connecting to the correct Plumbr Server instance. * * If indeed so, contact support@plumbr.io * ***************************************************************************************************
When facing the error above, the Agent is connecting to a Server using the accountId the Server is not aware of. This usually means you are connecting to an incorrect Plumbr Server. If this is the case, just make sure the serverUrl in plumbr.properties is pinpointing towards the correct Server.
When it is not the case, contact our support@plumbr.io and let us figure out the source for the problem.
Lambda support in early Java 8 releases
******************************************************************************************************* * There is a known issue with Java versions 1.8.0 - 1.8.0_31 where using Java agents * * together with code that uses dynamic invocation (such as lambdas or dynamic languages) * * may cause segmentation faults. If these are not used in your application, your JVM may be safe, * * but for production sites we do not recommend using Plumbr with Java 8 versions older than 1.8.0_40. * * To make sure this problem will not occur, either: * * a) Upgrade your Java version to 1.8.0_40 or newer * * b) If upgrading Java version is not possible, turn off JIT compilation for java.lang.invoke * * package by specifying -XX:CompileCommand=exclude,java/lang/invoke/ in your JVM startup script. * *******************************************************************************************************
When facing the warning above, you are running on an early Java 8 build which are known to contain bugs which will affect your JVM when you are making use of lambdas or dynamic languages along with any Java Agents attached to the JVM.
The application might work fine, but in order to make sure you will not run into any issues, please consider either
- upgrading the Java version to 1.8.0_40 or newer
- Turning off JIT compilation, as specified in the error message.
Native agent loading failure
***************************************************************** * Native agent could not be loaded from * * /users/me/plumbr * * This may be caused by missing read or execute permissions for * * plumbr home directory or one of its subdirectories. * * * * Check out https://plumbr.io/support/agent-configuration * * for more information or contact support@plumbr.io * *****************************************************************
When facing the error above, the filesystem permissions for native agents located in lib/ folder next to the Agent’s plumbr.jar file are not readable or executable by the user launching the JVM Plumbr is attached to.
To solve the problem you would need to make sure the user launching the JVM Plumbr Agent is attached has read and execute permissions for the lib/ folder and its subdirectories.
In all honesty, this is one of the cases we do not fully understand can be created. So if you are facing this situation, we would really appreciate if you could contact support@plumbr.io so we could understand how on earth this permission issue can even happen.
Proxy credentials missing
********************************************************************************** * The Proxy server at your-proxy-server.ip:3039 is requesting a username and a password. * * Please add them to plumbr.properties file. You can find the instructions here: * * https://plumbr.io/support/manual#network-configuration * **********************************************************************************
When seeing the banner above in your JVM standard output, then you are trying to connect from the Agent to Server using a proxy server. The proxy server requires authentication but the configuration you provided in plumbr.properties does not contain username and password.
To solve the issue, provide the correct username and password in the Plumbr configuration to access the proxy.
Multiple JVMs using the same jvmId
************************************************************************************************************************* * The JVM ID “myjvmid" is already in use. This happens when multiple JVMs are connecting * * to Plumbr Server using the same jvmId configuration parameter specified in plumbr.properties file. * * In order to solve the problem, download new Plumbr agent from here: https://app.plumbr.io/settings/download-center * * and make sure the agent location in the new JVM refers to a different Plumbr installation in file system. * *************************************************************************************************************************
When facing the error message above, the Plumbr Agent was not started. It was so due to a JVM already being connected to the Server using the same jvmId as specified for the rejected JVM.
This can happen when you have copied the Plumbr installation used by one JVM and are using it for the second JVM. The jvmId specified in the plumbr.properties file must be unique, so to solve the issue you would need to make sure all the JVMs you want to monitor with Plumbr have a unique jvmId specified in the configuration (either in plumbr.properties or passed as -D parameter).
Multiple JVMs accessing the same Plumbr installation
************************************************************************** * Working directory is locked. This might happen when you launch several * * applications from the same plumbrHome at the same time. * * In order to solve the problem, download new Plumbr agent from here: * * https://app.plumbr.io/settings/download-center * * and make sure the agent location in the new JVM refers to a different * * Plumbr installation in file system * **************************************************************************
When you encounter the error above, your are trying to launch two JVMs both loading the Plumbr Agent from the same location in the filesystem. Pay attention that each JVM monitored by Plumbr must use a unique Plumbr installation.
To overcome the issue, create a separate Plumbr Agent installation for each JVM monitored and load the javaagent from different locations for each JVM monitored.
