From a08337a4180f9584735c55c53e8233974bc7b5bf Mon Sep 17 00:00:00 2001 From: Venushka Perera Date: Sun, 6 Nov 2016 23:45:23 +0000 Subject: [PATCH] Update README.md --- README.md | 91 +++++++++++++++++++++++++++++++++---------------------- 1 file changed, 54 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index 5f243b3..768933b 100644 --- a/README.md +++ b/README.md @@ -7,12 +7,11 @@ jmxeval *jmxeval* is a highly flexible Nagios/NRPE plugin for monitoring Java applications via JMX. Instead of just checking just an attribute of an MBean, JMXEval allows you to query multiple MBean attributes as well as results of MBean method invocations, and also perform mathematical computations to derive much more meaningful figures for monitoring. JMXEval can also provide all the information captured from MBeans as well as any computed figures as performance data allowing you to capture and visualise trends in Nagios. # Setting up - -## Requirements -The only requirement for running *jmxeval* is a Java 7 runtime. +The only requirement for running *jmxeval* is a Java 7 runtime. Please follow the steps below to setup *jmxeval*. ## On Linux (or any \*nix based system) To setup jmxeval with Nagios/NRPE, + 1. Download the latest version's .tar.gz file. 2. Unpack it by running *tar -xvzf <filename>* 3. Copy the *check_jmxeval* file and the *jmxeval* directory to the Nagios/NRPE plugins directory from the zip file in the Nagios plugins directory, usually */usr/lib/nagios/plugins* on Nagios server and */usr/local/nagios/libexec* when using NRPE. @@ -21,6 +20,7 @@ To setup jmxeval with Nagios/NRPE, ## On Windows To setup jmxeval with NRPE, + 1. Download the latest version's .zip file. 2. Unzip the file. 3. Copy the *check_jmxeval.bat* file and the *jmxeval* directory to the NRPE plugins directory. @@ -61,6 +61,7 @@ This make jmxeval log more information to the console while its running and in a # Configuration files When running jmxeval, you will need to specify a configuration file. This is an XML file that specifies what checks it should perform. A configuration file for a really simple check would specify the following. + 1. How to connect to the Java process. 2. What is being checked. 3. What information needs to be fetched from the Java process. @@ -82,6 +83,7 @@ Let's look an example for checking the number of threads in a Java process, and ``` In the above example, + 1. *<connection>* specifies *how to connect*. 2. *<eval>* specifies *what is being checked*. 3. *<query>* specifies *what to get*. @@ -153,8 +155,9 @@ Represents a single check. This is a container for all the other elements that p | host | A regular expression pattern to match against the hostname of the machine the plugin is being executed on. This is useful if there are multiple *<eval>* elements are configured in the same configuration file and only some of them needs to be executed in some of the monitored machines. By default, it matches all hostnames. | No | .* | Following is an example where an *<eval>* is defined that should only run on machines that has hostnames starting with *ec2-*. - - `` +```xml + +``` ### <connection> Defines a JMX connection to a Java process. Any queries or method invocations on MBeans made using this connection should be nested within this element. Following attributes can be set on this element. @@ -168,17 +171,20 @@ Defines a JMX connection to a Java process. Any queries or method invocations on The *url* to can be quite different based on how JMX is configured on the Java process you are attempted to connect to. Here are some example URLs, -- Connection to a Java process running on *localhost* on port *8999*, without authentication. - - `` - -- Connection to a Java process running on *tomcat7.adahas.com* on port *8999*, with authentication and SSL. - - `` +Connection to a Java process running on *localhost* on port *8999*, without authentication. +```xml + +``` -- Connection to a Java process running on host named `tomcat7.adahas.com` having JMX and JNDI services running on two different ports; JMX on port *8999* and JNDI *1099*. Note that this type of URL will only be needed if JNDI service has been configured specifically to use a different port. +Connection to a Java process running on *tomcat7.adahas.com* on port *8999*, with authentication and SSL. +```xml + +``` - `` +Connection to a Java process running on host named `tomcat7.adahas.com` having JMX and JNDI services running on two different ports; JMX on port *8999* and JNDI *1099*. Note that this type of URL will only be needed if JNDI service has been configured specifically to use a different port. +```xml + +``` ### <query> Reads an attribute of a MBean and assigns it to a variable. This element must be contained in a *<connection>* element, which makes the JMX connection made to the Java process available to this element to execute the query. The variable that is created by this with the value of the MBean attribute can be referenced for performing calculations and alerting in the elements that follow it. Following attributes can be set on this element. @@ -191,12 +197,14 @@ Reads an attribute of a MBean and assigns it to a variable. This element must be | attribute | The attribute to read the value of. When a *compositeAttribute* is set, the *attribute* will refer to the attribute name in the [CompositeData](https://docs.oracle.com/javase/7/docs/api/javax/management/openmbean/CompositeData.html) field. | Yes | - | Following is an example of making a query for a simple attribute value. - - `` +```xml + +``` When querying attribute of a [CompositeData](https://docs.oracle.com/javase/7/docs/api/javax/management/openmbean/CompositeData.html) attribute, it would look like this. - - `` +```xml + +``` ### <exec> Executes an MBean operation, captures the return value and assigns it to a variable. Similar to the *<query>* element, this also must be contained in a *<connection>* element, from which it acquire the connection to perform the MBean operation call. Following attributes can be set on this element. @@ -209,16 +217,19 @@ Executes an MBean operation, captures the return value and assigns it to a varia | arg1 ... arg10 | Values of the arguments to pass to the operation call. The order of the arguments *must* match the order of the arguments specified in the *operation* attribute. If any of the attributes should be set to *null*, skip specifying the attribute altogether and continue with the next argument number. If an argument should be set to empty (""), specify the attribute with the value set to empty.| No | | An example of invoking a method without any arguments would look like this. - - `` +```xml + +``` If the operation requires a `String` argument, it would look like this. - - `` +```xml + +``` If the second argument need to be `null` and the third needs to have a value, you just skip specifying *arg2* altogether. - - `` +```xml + +``` ### <expr> Evaluate a mathematical expression. It supports addition (+), subtraction (-), multiplication (\*), division (/) and remainder (%) operations. You can use parentheses ( ) to specify the order of operations. Following attributes can be set on this element. @@ -230,12 +241,14 @@ Evaluate a mathematical expression. It supports addition (+), subtraction (-), m | scale | The number of decimal places to have in the result of the expression evaluation. | No | 2 | Here a simple example of an expression evaluation. This uses two variables, *heapUsage* and *heapMax*, probably created by two *<query>* elements before this, to calculate the heap usage as a percentage. - - `` +```xml + +``` To calculate the free heap percentage, it can be changed to the following. By adding parenthesis, we can get the expression within the parenthesis to execute first. - - `` +```xml + +``` ### <check> Reads a given variable and alerts if it matches the warning or critical alert criteria specified. The check can operate in two different modes, *default* and *regex* allowing a range of different ways to define the criteria for alerting. @@ -255,16 +268,19 @@ Following attributes can be set on this element. | message | The message to accompany the check result in the output. | No | | Let's have a look at few checks. Simplest check would be to see if a numeric variable is greater than 75 to raise a warning, and greater than 90 to raise a critical alert. - - `` +```xml + +``` If the variable value is text, a check can be done to see if the value exactly matches a given value. In this example, if the value of variable is "disconnected" a critical alert will be raised, and no warning alert set. - - `` +```xml + +``` Irrelevant of the variable's content, be it numeric or non-numeric, regular expressions can be used to check the result. This example raises a warning alert if the variable has a value that contains the word *awaiting lock* and a critical alert if it contains *dead lock* or *failed*. - - `` +```xml + +``` ### <perf> Captures information from the element that contains a *<perf>* element and reports it as [performance data](https://nagios-plugins.org/doc/guidelines.html#AEN200) for Nagios. Performance data allows Nagios to produce charts and graphs allowing you to identify trends and troubleshoot issues. @@ -284,8 +300,9 @@ A *<perf>* element can be nested in *<query>*, *<exec>*, *< *jmxeval* uses variables to hold information captured from MBeans, results from evaluating mathematical expressions, perform checks for raising alerts and report performance data. Many of the XMl elements in the configuration files creates variables as part of their role when the plugin is executing, the elements that follow can refer to them by the ${varName} notation. In addition to this, you can also define variables via [the command line](#command-syntax), which can then be referred in the configuration files. For example, you run *jmxeval* with `--set host=tomcat7.adahas.com --set port=8999` as a command line argument, and then refer in the configuration file as follows. - - `` +```xml + +``` This makes the configuration files much more reusable, as you can make all the process specific information and even the alert levels parameterised, so you can use the same configuration file to do similar (but not same) checks in multiple processes using the same configuration file. For example, the following configuration file allow you to set the process specific information such as *host* and *port*, along with the *warning* and *critical* alert thresholds via the command line. @@ -341,7 +358,7 @@ So, for the above example, the following configuration file will use the default # Feature requests & issues -If you have any feature requests or encounter a bug please do [raise is here](https://github.com/venushka/jmxeval/issues). +If you have any feature requests or encounter a bug please do [raise it here](https://github.com/venushka/jmxeval/issues). # License