Merge branch 'foundation' of github.com:OpenNMS/opennms into jira/NMS…

…-7812-foundation

opennms-doc/guide-admin/src/asciidoc/index.adoc

@@ -86,3 +86,7 @@ include::text/events.adoc[]
 
 // Provisioning guide
 include::text/provisioning.adoc[]
+
+// OpenNMS operation
+== OpenNMS Operation
+include::text/operation/jmx-config-generator.adoc[]

opennms-doc/guide-admin/src/asciidoc/text/operation/jmx-config-generator.adoc

@@ -0,0 +1,252 @@
+
+// Allow GitHub image rendering
+:imagesdir: ../../images
+
+=== JmxConfigTool
+The JmxConfigTool provides a fast and easy way to generate a proper _jmx-datacollection-config_ from a running Java application.
+Based on the generated configuration file it can also provide a set of _snmp-graph_ configurations.
+
+The JmxConfigTool offers two modes:
+
+==== Jmx Mode
+The _Jmx mode_ generates an _jmx-datacollection-config_ file to provide all relevant configurations to collect metrics from a Java Application and/or a Java Virtual Machine.
+The network connection to the JVM and the running Java Application is RMI based and can provide credentials.
+The following graphic offers an overview about the _Jmx mode_.
+
+.Overview of JmxConfigTool
+image:operation/jmx-config-generator/overview.png[]
+
+To start the JmxConfigTool in _Jmx mode_ a call like the following sample is used:
+
+[source, shell]
+----
+$ java -jar opennms_jmx_config_generator.jar -jmx -host myhost.org -port 7199 -out JmxConfig.xml
+----
+
+===== Credentials
+
+If the RMI connection to the JVM requires a username and a password, they can be added to the JmxConfigTool call like this:
+
+[source, shell]
+----
+$ java -jar opennms_jmx_config_generator.jar -jmx -host myhost.org -port 7199 -username foo -password bar -out JmxConfig.xml
+----
+
+===== Skip Default VM
+The option `-skipDefaultVM` offers the ability to ignore the MBeans provided as standard by the JVM and just create configurations for the MBeans provided by the Java Application itself.
+This is particularly useful if an optimized configuration for the JVM already exists.
+If the `-skipDefaultVM` option is not set the generated configuration will include the MBeans of the JVM and the MBeans of the Java Application.
+
+===== Run Writable MBeans
+By default all MBeans that are not just readable will be skipped.
+To get MBeans that are readable and writable into generated configuration files the option `-runWritableMBeans` is provided.
+
+===== JMXMP
+To use JMXMP instead of JMX-RMI for the connection the option `-jmxmp` is provided.
+
+===== Aliases for metrics
+Every metric in the configuration, even if it is an attribute of an MBean or a composite member, has to have a unique alias in its `jmx-collection` element.
+To meet this requirement, the aliases will be numbered.
+Additionally, the length of aliases is limited to 19 characters caused by the underlying RRDTool/JRobin technology.
+To create proper aliases the JmxConfigTool automatically trims the names for the MBean attributes and composite members in two steps.
+
+===== Dictionary for alias preparation:
+First the names will be split into name-parts at camel-case boundaries.
+Then a dictionary with replacements for name-parts will be applied.
+It is possible to add one's own dictionary entries using the `-dictionary` option followed by a dictionary file.
+The dictionary file is a Java properties file like this sample:
+
+[source]
+----
+# Dictionary Entries
+Auxillary:Auxil
+Available:Avail
+Average:Avg
+----
+
+The new entries will be added to the internal dictionary.
+If an entry already exists, it'll be replaced.
+Here is a sample of dictionary replacements:
+
+[source]
+----
+CommittedVirtualMemorySize CommitVirtMemSize
+AverageCompressionRatio    AvgCompRatio
+AllIdentityTokenizedCount  AllIdntToknzCnt
+----
+
+===== CamelCaseTrimmer for alias preparation
+
+In some cases the dictionary preparation is not able to shorten the alias to 19 characters, especially if the numbering of the aliases is applied.
+Then a second step to trim the aliases is applied, the CamelCaseTrimmer.
+This trimmer will split the name into name-parts at camel-case boundaries and stepwise remove the necessary number of characters from the longest name-part available.
+This is a sample of CamelCaseTrimmed names:
+
+[source]
+----
+CommittedVirtMemSize       CommitteVirtMemSize
+CommittedVirtualMemorySize CommiVirtuMemorSize
+AllIdentityTokenizedCount  AllIdentTokeniCount
+----
+
+===== Problems with aliases
+
+In some cases the JmxConfigTool will not be able to create unique names.
+The aliases in this case will be marked as `_NAME_CRASH_AS_19_CHAR_VALUE` and a log-message will be written.
+It's recommended to fix these aliases by hand or with some custom dictionary entries.
+
+==== Graph mode
+
+The _Graph mode_ generates a set of _snmp-graphs_ based on a _jmx-datacollection-config_ file. To run _JmxConfigTool_ in `graph mode` a basic call looks like this:
+
+[source, shell]
+----
+$ java -jar opennms_jmx_config_generator.jar -graph -input myJmxConfig.xml -out myJmxSnmpGraphs.properties
+----
+
+===== Graph Templates
+
+The JmxConfigTool uses a template file to generate the graphs.
+It is possible to use a user-defined template.
+The option `-template` followed by a file lets the JmxConfigTool use the external template file as base for the graph generation.
+A call with template option looks like this:
+
+[source, shell]
+----
+$ java -jar opennms_jmx_config_generator.jar -graph -input myJmxConfig.xml -out myJmxSnmpGraphs.properties -template myTemplate.vm
+----
+
+The template file has to be an Apache Velocity template.
+The sample represents the template that is used by default:
+
+[source]
+----
+reports=#foreach( $report in $reportsList )
+${report.id}#if( $foreach.hasNext ), \
+#end
+#end
+
+#foreach( $report in $reportsBody )
+
+#[[###########################################]]#
+#[[##]]# $report.id
+#[[###########################################]]#
+report.${report.id}.name=${report.name}
+report.${report.id}.columns=${report.graphResources}
+report.${report.id}.type=interfaceSnmp
+report.${report.id}.command=--title="${report.title}" \
+ --vertical-label="${report.verticalLabel}" \
+#foreach($graph in $report.graphs )
+ DEF:${graph.id}={rrd${foreach.count}}:${graph.resourceName}:AVERAGE \
+ AREA:${graph.id}#${graph.coloreB} \
+ LINE2:${graph.id}#${graph.coloreA}:"${graph.description}" \
+ GPRINT:${graph.id}:AVERAGE:" Avg \\: %8.2lf %s" \
+ GPRINT:${graph.id}:MIN:" Min \\: %8.2lf %s" \
+ GPRINT:${graph.id}:MAX:" Max \\: %8.2lf %s\\n" \
+#end
+
+#end
+----
+
+===== Types of generated graphs
+The JmxConfigTool generates different types of graphs from the _jmx-datacollection-config_.
+The different types are listed below:
+
+====== AttributeReport
+For each attribute of any MBean a graph will be generated. Composite attributes will be ignored.
+
+====== MbeanReport
+For each MBean a combined graph with all attributes of the MBeans is generated. Composite attributes will be ignored.
+
+====== CompositeReport
+For each composite attribute of every MBean a graph is generated.
+
+====== CompositeAttributeReport
+For each composite member of every MBean a combined graph with all composite attributes is generated.
+
+==== Installing JmxConfigTool
+From OpenNMS version 1.12 the jmx config generator is included as a separate installable package.
+
+===== Install JmxConfigTool Ubuntu
+
+Install the package from the OpenNMS repository:
+
+[source, shell]
+----
+# sudo apt-get install opennms-jmx-config-generator
+You should see:
+
+Reading package lists... Done
+Building dependency tree
+Reading state information... Done
+The following NEW packages will be installed:
+  opennms-jmx-config-generator
+0 upgraded, 1 newly installed, 0 to remove and 170 not upgraded.
+Need to get 2,176 kB of archives.
+After this operation, 2,236 kB of additional disk space will be used.
+Get:1 http://debian.opennms.org/ unstable/main
+   opennms-jmx-config-generator all 1.13.0-1 [2,176 kB]
+Fetched 2,176 kB in 3s (588 kB/s)
+Selecting previously unselected package opennms-jmx-config-generator.
+(Reading database ... 77133 files and directories currently installed.)
+Unpacking opennms-jmx-config-generator
+   (from .../opennms-jmx-config-generator_1.13.0-1_all.deb) ...
+Setting up opennms-jmx-config-generator (1.13.0-1) ...
+----
+
+===== Install JmxConfigTool RedHat
+
+Install the package from the OpenNMS repo:
+
+[source, shell]
+----
+# yum install opennms-jmx-config-generator.noarch
+You should see something like:
+
+Loaded plugins: downloadonly, product-id, security, subscription-manager
+This system is not registered to Red Hat Subscription Management.
+You can use subscription-manager to register.
+Setting up Install Process
+Resolving Dependencies
+--> Running transaction check
+---> Package opennms-jmx-config-generator.noarch 0:1.12.3-1 will be updated
+---> Package opennms-jmx-config-generator.noarch 0:1.12.4-1 will be an update
+--> Finished Dependency Resolution
+Dependencies Resolved
+===============================================================================
+Package                      Arch   Version       Repository              Size
+===============================================================================
+opennms-jmx-config-generator noarch 1.12.4-1      opennms-stable-common   2.4 M
+===============================================================================
+Upgrade       1 Package(s)
+Total download size: 2.4 M
+Is this ok [y/N]: y
+Downloading Packages:
+opennms-jmx-config-generator-1.12.4-1.noarch.rpm   | 2.4 MB     00:03
+Running rpm_check_debug
+Running Transaction Test
+Transaction Test Succeeded
+Running Transaction
+ Updating   : opennms-jmx-config-generator-1.12.4-1.noarch           1/2
+ Cleanup    : opennms-jmx-config-generator-1.12.3-1.noarch
+Verifying  : opennms-jmx-config-generator-1.12.4-1.noarch             1/2
+ Verifying  : opennms-jmx-config-generator-1.12.3-1.noarch            2/2
+Updated:
+ opennms-jmx-config-generator.noarch 0:1.12.4-1
+Complete!
+----
+
+==== Get the JmxConfigTool
+First clone the http://www.opennms.org/wiki/Developing_with_Git#Getting_OpenNMS[OpenNMS git repository].
+Then enter the folder `opennms/features/opennms-jmx-tools`.
+Next start Maven to create the JmxConfigTool by using `mvn package`.
+Inside the newly created “target” folder a file named like `jmxconfiggenerator-1.11.3-SNAPSHOT-jar-with-dependencies.jar` is present.
+Rename the file to `JmxConfigTool.jar`.
+
+Or, for example, you can browse to http://yum.opennms.org/stable/common/opennms/[http://yum.opennms.org/stable/common/opennms/] and find the rpm for the file listed as:
+`opennms-jmx-config-generator-<VERSION>.noarch.rpm`
+
+Once installed you will end up with two possible executables:
+
+* `/opt/opennms/bin/jmx-config-generator`
+* `/opt/opennms/lib/opennms_jmx_config_generator.jar`