jmx2logzio

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].

jmx2logzio as Java agent setup

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.

Note: The agent uses Slf4j logging framework. To get logs from the agent, you'll need to supply a slf4j binder.

Configuration

You'll need: Java 1.8 or higher

1. 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

2. 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	Required. Your Logz.io account token Replace <<SHIPPING-TOKEN>> with the token of the account you want to ship to.
SERVICE_NAME	Required. A name you define for the service.This is included in the reported metrics.
LISTENER_URL	Default: https://listener.logz.io:8071 Listener URL and port.Replace <<LISTENER-HOST>> with your region's listener host (for example listner.logz.io). For more information on finding your account's region, see Account region.
SERVICE_HOST	Hostname to be included in the reported metrics.
POLLING_INTERVAL_IN_SEC	Default: 30 Metrics polling interval, in seconds.
WHITE_LIST_REGEX	Default: .* (match everything) Only metrics matching this regex will be sent.
BLACK_LIST_REGEX	Default: $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	Default: 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
FILE_SYSTEM_SPACE_LIMIT	Default: 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	Default: 1000 Time interval, in milliseconds, to check for disk space.
CLEAN_SENT_METRICS_INTERVAL	Default: 30 Time interval, in seconds, to clean sent metrics from the disk.

If FROM_DISK=false

Parameter	Description
IN_MEMORY_QUEUE_CAPACITY	Default: 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	Default: -1 The number of logs in the memory queue before dropping new logs. If set to -1, the sender won't limit the queue by log count.

3. Check Logz.io for your metrics

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

jmx2logzio + Jolokia agent setup

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

You'll need: Java 1.8 or higher

1. 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

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

2. 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	Required. A name you define for the service. This is included in the reported metrics.
service.host	Default: Host machine name (if not defined in application.conf) Hostname to be included in the reported metrics.
service.poller.white-list-regex	Default: .* (match everything) Only metrics matching this regex will be sent.
service.poller.black-list-regex	Default: $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	Default: 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	Default: 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	Required. Your Logz.io account token
logzio-java-sender.from-disk	Default: 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.file-system-full-percent-threshold	Default: 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	Default: 30 Time interval, in seconds, to clean sent metrics from the disk.
logzio-java-sender.disk-space-checks-interval	Default: 1000 Time interval, in milliseconds, to check for disk space.

If from-disk=false

Parameter	Description
logzio-java-sender.in-memory-queue-capacity	Default: 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	Default: -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).

3. 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

4. Check Logz.io for your metrics

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

Changelog

• v1.1.0
  • Combine metrics with the same dimensions to a single doc.
• v1.0.10
  • Use newer version of logzio-java-sender to prevent tokens clash.
• v1.0.9
  • Provide an external configuration file when using as an app that connects to a Jolokia agent
• v1.0.8
  • Hide your logz.io token, to keep you safe
  • Change logger logic for 'instance not found'
• v1.0.7
  • For testing purposes and simulations we'd like the agent to be able to work with local addresses
• v1.0.6
  • This release ensures no conflicts between the dependencies of this agent and any java app.
• v1.0.5
  • Kill sender threads upon shutdown
• v1.0.4
  • Jmx2logz.io logger changed from logback to slf4j and will now inhere its properties from the java app.
  • Set level feature was removed and will also be inherited from the main app
• v1.0.2
  • Shade all dependencies
• v1.0.1
  • Jmx2logz.io output log level can be configured.
• v1.0.0
  • Added Javadoc
• v0.0.8
  • Additional metric information will be sent under "dim" instead of "dimensions"
• v0.0.7
  • Added a feature that allows you to add extra dimensions to the collected metrics before sent.

The other stuff

Contributing

We welcome any contribution! Here's how you can help:

• Open an issue (Bug, Feature request, etc)
• Pull requests for any additional functionality

License

See LICENSE