jmxtrans-agent is a version of jmxtrans intended to be used as a java agent. JmxTrans Agent has zero dependencies to ease integration.
Download jmxtrans-agent-1.0.6.jar
Sample setenv.sh
for Apache Tomcat
export JAVA_OPTS="$JAVA_OPTS -javaagent:/path/to/jmxtrans-agent-1.0.6.jar=jmxtrans-agent.xml"
- java agent jar path can be relative to the working dir
jmxtrans-agent.xml
is the configuration file, can be classpath relative (classpath:โฆ
), http(s) (http(s)://...
) or file system system based (relative to the working dir)
Use attribute
to specify the value to lookup. See javax.management.MBeanServer.getAttribute(objectName, attribute)
.
<query objectName="java.lang:type=Threading" attribute="ThreadCount"
resultAlias="jvm.thread"/>
Use key
to specify the key of the CompositeData. See javax.management.openmbean.CompositeData#get(key)
.
<query objectName="java.lang:type=Memory" attribute="HeapMemoryUsage" key="used"
resultAlias="jvm.heapMemoryUsage.used"/>
Use position
to specify the value to lookup. Position is `0 based.
<query objectName="MyApp:type=MyMBean" attribute="MyMultiValuedAttribute" position="2"
resultAlias="myMBean.myMultiValuedAttributeValue"/>
If position
is not specified, all the values of the attribute are outputted with the name ${resultAlias}_${position}
.
Sample: myMBean.myMultiValuedAttributeValue_0
, myMBean.myMultiValuedAttributeValue_1
, ...
Sample jmxtrans-agent.xml
configuration file for Tomcat:
<jmxtrans-agent>
<queries>
<!-- OS -->
<query objectName="java.lang:type=OperatingSystem" attribute="SystemLoadAverage" resultAlias="os.systemLoadAverage"/>
<!-- JVM -->
<query objectName="java.lang:type=Memory" attribute="HeapMemoryUsage" key="used"
resultAlias="jvm.heapMemoryUsage.used"/>
<query objectName="java.lang:type=Memory" attribute="HeapMemoryUsage" key="committed"
resultAlias="jvm.heapMemoryUsage.committed"/>
<query objectName="java.lang:type=Memory" attribute="NonHeapMemoryUsage" key="used"
resultAlias="jvm.nonHeapMemoryUsage.used"/>
<query objectName="java.lang:type=Memory" attribute="NonHeapMemoryUsage" key="committed"
resultAlias="jvm.nonHeapMemoryUsage.committed"/>
<query objectName="java.lang:type=ClassLoading" attribute="LoadedClassCount" resultAlias="jvm.loadedClasses"/>
<query objectName="java.lang:type=Threading" attribute="ThreadCount" resultAlias="jvm.thread"/>
<!-- TOMCAT -->
<query objectName="Catalina:type=GlobalRequestProcessor,name=*" attribute="requestCount"
resultAlias="tomcat.requestCount"/>
<query objectName="Catalina:type=GlobalRequestProcessor,name=*" attribute="errorCount"
resultAlias="tomcat.errorCount"/>
<query objectName="Catalina:type=GlobalRequestProcessor,name=*" attribute="processingTime"
resultAlias="tomcat.processingTime"/>
<query objectName="Catalina:type=GlobalRequestProcessor,name=*" attribute="bytesSent"
resultAlias="tomcat.bytesSent"/>
<query objectName="Catalina:type=GlobalRequestProcessor,name=*" attribute="bytesReceived"
resultAlias="tomcat.bytesReceived"/>
<!-- APPLICATION -->
<query objectName="Catalina:type=Manager,context=/,host=localhost" attribute="activeSessions"
resultAlias="application.activeSessions"/>
</queries>
<outputWriter class="org.jmxtrans.agent.GraphitePlainTextTcpOutputWriter">
<host>localhost</host>
<port>2003</port>
<namePrefix>app_123456.servers.i876543.</namePrefix>
</outputWriter>
<outputWriter class="org.jmxtrans.agent.ConsoleOutputWriter"/>
<collectIntervalInSeconds>20</collectIntervalInSeconds>
</jmxtrans-agent>
Note why xml and not json ? because XML parsing is out of the box in the JVM when json requires additional libraries.
OutputWriters are very simple to develop, you just have to extend AbstractOutputWriter.java or to implement OutputWriter.java.
Out of the box output writers
- GraphitePlainTextTcpOutputWriter: output to Graphite Carbon plain text protocol on TCP. Configuration parameters:
enabled
: to enable/disable the output writer. Optional, default valuetrue
host
: Graphite Carbon listener hostport
: Graphite Carbon Plain Text TCP listener port. Optional, default value2003
namePrefix
; prefix of the metric name. Optional, default valuesservers.#hostname#.
where#hostname#
is the auto discovered hostname of computer with.
escpaed as_
(InetAddress.getLocalHost().getHostName()
).
- FileOverwriterOutputWriter: store the last collection of metrics in a file. Configuration parameters:
fileName
: name of the file in which the collected metrics are stored. Optional, default valuejmxtrans-agent.data
(in JVM working dir, for example$TOMCAT_HOME/bin
)
- SummarizingFileOverwriterOutputWriter: Similar to the
FileOverwriterOutputWriter
but displays "per minute" values for counters of typecounter
- ConsoleOutputWriter: output metric values to
stdout
- SummarizingConsoleOutputWriter: Similar to the
ConsoleOutputWriter
but displays "per minute" values for counters of typecounter
Output writers configuration support an expression language based on property placeholders with the {prop-name[:default-value]}
syntax (e.g. "${graphite.host:2003}
").
The default-value
is optional. An exception is raised if no default value is defined and the property placeholder is not found.
Environment variables are looked-up in the following order:
- JVM system properties (
System.getProperty("graphite.host")
) - JVM environment variables (
System.getenv("graphite.host")
) - JVM environment variables after a "to-upper-case + dot-to-underscore" transformation (
System.getenv("GRAPHITE_HOST")
)
os.systemLoadAverage 1.80419921875 1366199958
jvm.heapMemoryUsage.used 20438792 1366199958
jvm.heapMemoryUsage.committed 119668736 1366199958
jvm.nonHeapMemoryUsage.used 15953560 1366199958
jvm.nonHeapMemoryUsage.committed 24313856 1366199958
jvm.loadedClasses 2162 1366199958
jvm.thread 13 1366199958
tomcat.requestCount 0 1366199958
tomcat.requestCount 0 1366199958
tomcat.errorCount 0 1366199958
tomcat.errorCount 0 1366199958
tomcat.processingTime 0 1366199958
tomcat.processingTime 0 1366199958
tomcat.bytesSent 0 1366199958
tomcat.bytesSent 0 1366199958
tomcat.bytesReceived 0 1366199958
tomcat.bytesReceived 0 1366199958
application.activeSessions 0 1366199958
os.systemLoadAverage 1.27734375
jvm.heapMemoryUsage.used 33436016
jvm.heapMemoryUsage.committed 133365760
jvm.nonHeapMemoryUsage.used 23623096
jvm.nonHeapMemoryUsage.committed 24707072
jvm.loadedClasses 3002
jvm.thread 21
tomcat.requestCount 27
tomcat.requestCount 0
tomcat.errorCount 0
tomcat.errorCount 0
tomcat.processingTime 881
tomcat.processingTime 0
tomcat.bytesSent 135816
tomcat.bytesSent 0
tomcat.bytesReceived 0
tomcat.bytesReceived 0
application.activeSessions 0
The ResultNameStrategy
is the component in charge of building the metric name. The default implementation uses the resultAlias
if provided
and otherwise will build the metric name using the ObjectName
.
You can use your own implementation for the ResultNameStrategy
<resultNameStrategy class="com.mycompany.jmxtrans.agent.MyResultNameStrategyImpl">
<attrA>valA</attrA>
<atttrB>valB</atttrB>
</resultNameStrategy>
You then have to make this implementation available in the classpath (adding it the the jmxtrans-agent jar, adding it to the boot classpath ...)
- Create directory
${ACTIVEMQ_HOME}/jmxtrans-agent/
- Copy
jmxtrans-agent-1.0.6.jar
under${ACTIVEMQ_HOME}/jmxtrans-agent/
- Update
${ACTIVEMQ_HOME}/bin/activemq
, add ininvoke_start()
andinvoke_console()
:
JMXTRANS_AGENT="-javaagent:${ACTIVEMQ_HOME}/jmxtrans-agent/jmxtrans-agent-1.0.6.jar=${ACTIVEMQ_HOME}/jmxtrans-agent/jmxtrans-agent-activemq.xml" ACTIVEMQ_OPTS="$ACTIVEMQ_OPTS $JMXTRANS_AGENT"
* Copy to `${ACTIVEMQ_HOME}/jmxtrans-agent/` a config file similar to
```xml
<jmxtrans-agent>
<queries>
<!-- OS -->
<query objectName="java.lang:type=OperatingSystem" attribute="SystemLoadAverage"
resultAlias="os.systemLoadAverage"/>
<!-- JVM -->
<query objectName="java.lang:type=Memory" attribute="HeapMemoryUsage" key="used"
resultAlias="jvm.heapMemoryUsage.used"/>
<query objectName="java.lang:type=Memory" attribute="HeapMemoryUsage" key="committed"
resultAlias="jvm.heapMemoryUsage.committed"/>
<query objectName="java.lang:type=Memory" attribute="NonHeapMemoryUsage" key="used"
resultAlias="jvm.nonHeapMemoryUsage.used"/>
<query objectName="java.lang:type=Memory" attribute="NonHeapMemoryUsage" key="committed"
resultAlias="jvm.nonHeapMemoryUsage.committed"/>
<query objectName="java.lang:type=ClassLoading" attribute="LoadedClassCount" resultAlias="jvm.loadedClasses"/>
<query objectName="java.lang:type=Threading" attribute="ThreadCount" resultAlias="jvm.thread"/>
<!-- ACTIVE MQ -->
<query objectName="org.apache.activemq:type=Broker,brokerName=*,destinationType=Queue,destinationName=*"
attribute="QueueSize" resultAlias="activemq.%brokerName%.queue.%destinationName%.QueueSize"/>
<query objectName="org.apache.activemq:type=Broker,brokerName=*,destinationType=Queue,destinationName=*"
attribute="EnqueueCount" resultAlias="activemq.%brokerName%.queue.%destinationName%.EnqueueCount"/>
<query objectName="org.apache.activemq:type=Broker,brokerName=*,destinationType=Queue,destinationName=*"
attribute="ExpiredCount" resultAlias="activemq.%brokerName%.queue.%destinationName%.ExpiredCount"/>
<query objectName="org.apache.activemq:type=Broker,brokerName=*,destinationType=Queue,destinationName=*"
attribute="DequeueCount" resultAlias="activemq.%brokerName%.queue.%destinationName%.DequeueCount"/>
<query objectName="org.apache.activemq:type=Broker,brokerName=*,destinationType=Topic,destinationName=*"
attribute="EnqueueCount" resultAlias="activemq.%brokerName%.topic.%destinationName%.EnqueueCount"/>
</queries>
<outputWriter class="org.jmxtrans.agent.GraphitePlainTextTcpOutputWriter">
<host>localhost</host>
<port>2203</port>
</outputWriter>
<outputWriter class="org.jmxtrans.agent.ConsoleOutputWriter">
<enabled>false</enabled>
</outputWriter>
</jmxtrans-agent>