jmx2logzio is a lightweight tool for polling JMX metrics and sending them to Logz.io.

This doc shows you how to set up jmx2logzio. You have two options here:

  • Run as a Java agent (to get metrics directly from the MBean platform)
  • Run as an app that connects to a Jolokia agent

How are metrics reported?

Metrics are reported as [SERVICE-NAME].[SERVICE-HOST].[METRIC-NAME].

Set up jmx2logzio as a Java agent

In most cases, you can configure jmx2logzio to run as an agent. In this configuration, jmx2logzio sends metrics to Logz.io at user-defined intervals.

The agent uses SLF4J logging framework. To get logs from the agent, you’ll need to supply an SLF4J binder.

Configuration

Before you begin, you’ll need: Java 1.8 or higher

Download jmx2logzio

Download jmx2logzio.jar to your current folder. You’ll use this in step 2.

RELEASE_JAR=$(curl -s https://api.github.com/repos/logzio/jmx2logzio/releases/latest \
  | grep "browser_download_url" | awk '{print substr($2, 2, length($2)-2)}') \
  ; wget -O jmx2logzio-javaagent.jar $RELEASE_JAR
Configure and run jmx2logzio

Run your Java app, adding -javaagent:path/to/jmx2logzio/jar/file.jar and configuration arguments to the command. Include extra configuration arguments as KEY=VALUE, with a comma between each argument.

This code block shows a sample command to run jmx2logzio with runtime configuration. For a complete list of options, see the configuration parameters below the code block.👇

java -javaagent:./jmx2logzio-javaagent.jar=LOGZIO_TOKEN=<<SHIPPING-TOKEN>>,SERVICE_NAME=myService /path/to/your/app
Parameters
Parameter Description
LOGZIO_TOKEN Your Logz.io account token
Replace <<SHIPPING-TOKEN>> with the token of the account you want to ship to.
SERVICE_NAME A name you define for the service. This is included in the reported metrics.
LISTENER_URL https://listener.logz.io:8071 Listener URL and port. Replace <<LISTENER-HOST>> with your region’s listener host (for example, listener.logz.io). For more information on finding your account’s region, see Account region.
SERVICE_HOST Host machine name Hostname to be included in the reported metrics.
POLLING_INTERVAL_IN_SEC 30 Metrics polling interval, in seconds.
WHITE_LIST_REGEX .* (match everything) Only metrics matching this regex will be sent.
BLACK_LIST_REGEX $a (match nothing) Metrics matching this regex will not be sent.
EXTRA_DIMENSIONS A list of key-values separated by : that will be added to the dimensions of the collected metrics.
Example: EXTRA_DIMENSIONS={origin=local:env=java}
FROM_DISK true If true, metrics are stored on disk until they’re shipped (see If FROM_DISK=true). If false, metrics persist in memory until they’re shipped (see If FROM_DISK=false).
If FROM_DISK=true
Parameter Description
QUEUE_DIR ./metrics Path to store the queue. Must be a path to an existing folder.
FILE_SYSTEM_SPACE_LIMIT 98 Threshold percentage of disk space at which to stop queueing. If this threshold is reached, all new metrics are dropped until used space drops below the threshold.
Set to -1 to ignore threshold.
DISK_SPACE_CHECKS_INTERVAL 1000 Time interval, in milliseconds, to check for disk space.
CLEAN_SENT_METRICS_INTERVAL 30 Time interval, in seconds, to clean sent metrics from the disk.
If FROM_DISK=false
Parameter Description
IN_MEMORY_QUEUE_CAPACITY 1024 * 1024 * 100 The amount of memory, in bytes, jmx2logzio can use for the memory queue. Set to -1 for unlimited bytes.
LOGS_COUNT_LIMIT -1 The number of logs in the memory queue before dropping new logs. Default value is -1 (the sender will not limit the queue by logs count).
Check Logz.io for your metrics

Give your metrics some time to get from your system to ours, and then open Logz.io.

Set up jmx2logzio with a Jolokia agent

If you want to poll metrics from a remote source, you can use Jolokia agent + Jmx2logzio. In this configuration, Jolokia exposes the metrics through an API, which jmx2logzio reads and sends to Logz.io. In this case, jmx2logzio can run as a docker.

Configuration

Before you begin, you’ll need: Java 1.8 or higher

Run the Jolokia agent

Download the Jolokia JVM Agent JAR file.

Run your Java app, adding -javaagent:path/to/jolokia/jar/file.jar to the command. For example:

java -javaagent:/opt/jolokia/jolokia-jvm-1.6.0-agent.jar /path/to/your/app

You can specify a custom configuration for Jolokia agent at runtime. For more information, see Jolokia as JVM Agent from Jolokia.

Download and configure jmx2logzio
RELEASE_JAR=$(curl -s https://api.github.com/repos/logzio/jmx2logzio/releases/latest \
  | grep "browser_download_url" | awk '{print substr($2, 2, length($2)-2)}') \
  ; wget -O jmx2logzio-javaagent.jar $RELEASE_JAR

Create a configuration file specifying the parameters below. For help, see our example configuration file.

Parameters
Parameter Description
service.name A name you define for the service. This is included in the reported metrics.
service.host Host machine name (if not defined in application.conf) Hostname to be included in the reported metrics.
service.poller.white-list-regex .* (match everything) Only metrics matching this regex will be sent.
service.poller.black-list-regex $a (match nothing) Metrics matching this regex will not be sent.
service.poller.jolokia.jolokiaFullUrl URL of the remote Jolokia agent you’re forwarding metrics to.
service.poller.metrics-polling-interval-in-seconds 30 Metrics polling interval, in seconds.
extra-dimensions A dictionary of key-values that will be added to the dimensions of the collected metrics.
logzio-java-sender.url https://listener.logz.io:8071 Listener URL and port.
For more information on finding your account’s region, see Account region.
logzio-java-sender.token Your Logz.io account token
logzio-java-sender.from-disk true If true, metrics are stored on disk until they’re shipped (see If from-disk=true). If false, metrics persist in memory until they’re shipped (see If from-disk=false).
If from-disk=true
Parameter Description
logzio-java-sender.queue-dir metrics Path to store the queue. Must be an existing folder.
logzio-java-sender.file-system-full-percent-threshold 98 Threshold percentage of disk space at which to stop queueing. If this threshold is reached, all new metrics are dropped until used space drops below the threshold. Set to -1 to ignore threshold.
logzio-java-sender.clean-sent-metrics-interval 30 Time interval, in seconds, to clean sent metrics from the disk.
logzio-java-sender.disk-space-checks-interval 1000 Time interval, in milliseconds, to check for disk space.
If from-disk=false
Parameter Description
logzio-java-sender.in-memory-queue-capacity 1024 * 1024 * 100 The amount of memory, in bytes, jmx2logzio can use for the memory queue. Set to -1 for unlimited bytes.
logzio-java-sender.log-count-limit -1 The number of logs in the memory queue before dropping new logs. Default value is -1 (the sender will not limit the queue by logs count).
Run jmx2logzio

Make sure your app is running with the Jolokia agent, and then start jmx2logzio.

You can launch jmx2logzio.jar as a standalone jar or in a Docker container.

As a jar:

java -jar jmx2logzio.jar config.conf

In a container:

docker pull logzio/jmx2logzio
docker run -v $(pwd)/config.conf:/application.conf logzio/jmx2logzio
Check Logz.io for your metrics

Give your metrics some time to get from your system to ours, and then open Logz.io.