Table of Contents

1. Overview
2. Module Description - What the module does and why it is useful
3. Usage - Configuration options and additional functionality
4. Installing jmxtrans
5. Managing the service
6. Configuring servers and queries
7. Development - Guide for contributing to the module

Overview

Configure jmxtrans for collecting and exporting JVM metrics data.

This module was adopted from PLoperations and was available as ploperations/jmxtrans before.

Module Description

This module can be used to install and manage the jmxtrans service, as well as configure how it connects to JVM processes, what data it pulls out, and where it sends the data it collects.

For more information on jmxtrans, see the source repo.

Requirements

This module is not dependent on any java puppet module, however without any java on the system, the startup of jmxtrans will fail. Please take care to have a working java installation on the server (recommended of course with the puppetlabs/java module) and the java binary in the PATH or at least a JAVA_HOME set. The jmxtrans startup script will try to detect the java via one of these ways.

Installing jmxtrans

If you have a repository configured on the system with a jmxtrans package available, you can install jmxtrans by setting the package_name parameter on the main jmxtrans class.

class { '::jmxtrans':
  package_name => 'jmxtrans',
}

If you have a package available on the local filesystem or remotely over HTTP (if your package manager supports it), you can set the package_source parameter. Note that if you are on anything other than a Debian or EL-based operating system, you will also need to set package_provider.

class { '::jmxtrans':
  package_name   => 'jmxtrans',
  package_source => 'http://central.maven.org/maven2/org/jmxtrans/jmxtrans/254/jmxtrans-254.rpm',
}

Managing the service

If you want to manage the service, you can set the service_name parameter, which will set ensure => running on the service.

class { '::jmxtrans':
  package_name => 'jmxtrans',
  service_name => 'jmxtrans',
}

Configuring servers and queries

The jmxtrans::query defined type is used to configure "servers" and "queries" as described in the jmxtrans documentation.

Example usage:

jmxtrans::query { 'puppetserver':
  host     => 'localhost',
  port     => 1099,
  queries  => [
    {
      object       => "metrics:name=puppetlabs.${facts['hostname']}.compiler.compile",
      attributes   => ['Max', 'Min', 'Mean', 'StdDev', 'Count'],
      result_alias => 'puppetlabs.puppetmaster.compiler.compile',
      writers      => [
        {
          '@class'          => 'com.googlecode.jmxtrans.model.output.KeyOutWriter',
          outputFile        => '/tmp/puppetserver-compile-metrics.txt',
          maxLogFileSize    => '10MB',
          maxLogBackupFiles => '200',
          debug             => true,
        },
      ],
    },
    {
      object       => "metrics:name=puppetlabs.${facts['hostname']}.jruby.num-free-jrubies",
      attributes   => ['Value'],
      result_alias => 'puppetlabs.puppetmaster.jruby.num-free-jrubies',
      writers      => [
        {
          '@class'          => 'com.googlecode.jmxtrans.model.output.KeyOutWriter',
          outputFile        => '/tmp/puppetserver-jruby-metrics.txt',
          maxLogFileSize    => '10MB',
          maxLogBackupFiles => '200',
          debug             => true,
        },
      ],
    },
  ],
}

This will configure jmxtrans to connect to a JMX RMI on localhost listening on port 1099, and it will:

• extract the values for Max, Min, Mean, StdDev, and Count from the metrics:name=puppetlabs.${facts['hostname']}.compiler.compile object and write them to /tmp/puppetserver-compile-metrics.txt.
• extract the value of the Value attribute for the object metrics:name=puppetlabs.${facts['hostname']}.jruby.num-free-jrubies and write it to /tmp/puppetserver-jruby-metrics.txt.

If you intend to use the GraphiteWriter, StdoutWriter or GelfWriter on all the objects for the server, there are top level parameters that you can set which will be inherited by all the query objects.

Development

Pull Requests on GitHub are welcome. Please include tests for any new features or functionality change. See rspec-puppet for details on writing unit tests for Puppet.

Always keep the reference up to date by running

bundle exec puppet strings generate --format markdown

Reference

Table of Contents

Classes

• jmxtrans: This is the main class for using jmxtrans. It should be included before using anything else from the module.
• jmxtrans::config: This class is used to configure the jmxtrans config files
• jmxtrans::install: This class is used to install the jmxtrans package. If $::jmxtrans::package_name is undef, then this class will do nothing. If `$::jmxtrans
• jmxtrans::service: This class manages the jmxtrans service. If $::jmxtrans::service_name is undef, this class does nothing.

Defined types

• jmxtrans::query: This defined type is used to add a JSON configuration for jmxtrans to pull metrics for a given JVM process and write them out. It can automat

Functions

• jmxtrans::merge_notundef: This function will merge a list of hashes, ignoring key => value pairs in the the latter which have a value of undef
• jmxtrans::to_json: Stringify data into the JSON format

Classes

jmxtrans

This is the main class for using jmxtrans. It should be included before using anything else from the module.

Examples

jmxtrans is installed via some other method

include jmxtrans

jmxtrans is available in a repository via the package jmxtrans

class { 'jmxtrans':
  package_name => 'jmxtrans',
  service_name => 'jmxtrans',
}

jmxtrans should be installed via rpm installing a remote package

class { 'jmxtrans':
  package_name  => 'jmxtrans',
  service_name  => 'jmxtrans',
  package_source => 'http://central.maven.org/maven2/org/jmxtrans/jmxtrans/254/jmxtrans-254.rpm',
}

jmxtrans runs under a different user with a different config path

class { 'jmxtrans':
  config_directory => '/etc/jmxtrans/config/',
  user             => 'java',
}

Parameters

The following parameters are available in the jmxtrans class:

• package_name
• service_name
• package_source
• package_provider
• working_directory
• systemd_environment_file
• manage_service_file
• package_version
• systemd_template
• binary_path
• config_directory
• user

package_name

Data type: Optional[String[1]]

The package to install. Skips managing the package if undef.

Default value: undef

service_name

Data type: Optional[String[1]]

The service to manage. Skips managing the service if undef.

Default value: undef

package_source

Data type: Optional[String[1]]

A URL or local path to get a package from.

Default value: undef

package_provider

Data type: Optional[String[1]]

Used to explicitly set the provider to use to install the package.

Default value: undef

working_directory

Data type: Optional[String[1]]

Sets the working directory for the jmxtrans processes.

Default value: undef

systemd_environment_file

Data type: Optional[String[1]]

Path to the file where the environment variables needed by the jmxtrans service should be defined (e.g. '/etc/default/jmxtrans' or '/etc/sysconfig/jmxtrans').

Default value: undef

manage_service_file

Data type: Boolean

Manage the service definition file (systemd/init) for the JMXtrans-Service

Default value: false

package_version

Data type: String[1]

The version of the package to be installed. Defaults to 'present'.

Default value: present

systemd_template

Data type: String[1]

Template to be be used to generate the systemd unit. Defaults to 'jmxtrans/jmxtrans.service.pp'

Default value: 'jmxtrans/jmxtrans.service.epp'

binary_path

Data type: String[1]

Path to the jmxtrans executable. Defaults to '/usr/share/jmxtrans/bin/jmxtrans'.

Default value: '/usr/share/jmxtrans/bin/jmxtrans'

config_directory

Data type: String[1]

Where to place JSON configurations. Defaults to '/var/lib/jmxtrans'.

Default value: '/var/lib/jmxtrans'

user

Data type: String[1]

The user who will own the JSON configurations. Defaults to 'jmxtrans'.

Default value: 'jmxtrans'

jmxtrans::config

This class is used to configure the jmxtrans config files

jmxtrans::install

This class is used to install the jmxtrans package. If $::jmxtrans::package_name is undef, then this class will do nothing. If $::jmxtrans::package_source is set, the package will be installed from the location specified.

This class will use the default provider for a platform if an explicit value is not set for $::jmxtrans::package_source. If a value is set for that parameter, this class will use the rpm provider on RedHat systems and the dpkg provider on Debian systems. This can be overridden by specifying a value for the $::jmxtrans::package_provider parameter.

jmxtrans::service

This class manages the jmxtrans service. If $::jmxtrans::service_name is undef, this class does nothing.

Defined types

jmxtrans::query

This defined type is used to add a JSON configuration for jmxtrans to pull metrics for a given JVM process and write them out. It can automatically configure the GraphiteWriter, or you can pass explicit configuration for any other jmxtrans-supported writer.

Parameters

The following parameters are available in the jmxtrans::query defined type:

• title
• ensure
• host
• port
• username
• password
• num_threads
• stdout
• graphite
• gelf
• queries

title

The resource title is used for the server alias.

ensure

Data type: Enum['present', 'absent']

Whether the configuration should exist or not.

Default value: 'present'

host

Data type: String[1]

The host to connect to JMX on. Defaults to $title.

Default value: $title

port

Data type: Optional[Integer[1]]

The port to connect to JMX on.

Default value: undef

username

Data type: Optional[String[1]]

The username to use to connect to JMX.

Default value: undef

password

Data type: Optional[String[1]]

The password to use to connect to JMX.

Default value: undef

num_threads

Data type: Optional[Integer[1]]

How many queries to execute concurrently. Defaults to undef, which will execute the queries serially.

Default value: undef

stdout

Data type: Boolean

Set to true to enable the StdoutWriter for each query on this object, so you don't have to do it manually.

Default value: false

graphite

Data type: Optional[Struct[{ host => String[1], port => Integer[1], Optional[root] => String[1], Optional[boolean_as_number] => Boolean, }]]

The Graphite configuration. Passing a hash with host and port will configure the GraphiteWriter for each query on this object, so you don't have to do it manually. You may also set:

• root [String] to configure the rootPrefix
• boolean_as_number [String] to configure the booleanAsNumber

Default value: undef

gelf

Data type: Optional[Struct[{ host => String[1], port => Integer[1], Optional[additionalFields] => Hash, Optional[transport] => String, Optional[queueSize] => Integer, Optional[connectTimeout] => Integer, Optional[reconnectDelay] => Integer, Optional[tcpNoDelay] => Boolean, Optional[sendBufferSize] => Integer, Optional[tlsEnabled] => Boolean, Optional[tlsTrustCertChainFile] => String, Optional[tlsCertVerificationEnabled] => Boolean, Optional[tcpKeepAlive] => Boolean, Optional[maxInflightSends] => Integer, }]]

The GelfWriter configuration. Passing a hash with hostand port will configure the GelfWriter for each query on this object, so you don't have to do it manually. You may also set additional parameters as documented in the JMXTrans Wiki

Default value: undef

queries

Data type: Optional[Array[Struct[{ object => String[1], attributes => Array[String[1]], Optional[type_names] => Array[String[1]], Optional[result_alias] => String[1], Optional[writers] => Array[Hash], }]]]

An array of queries to configure on the object. These consist of hashes of the form:

{
  'object'       => 'net.sf.ehcache:typeCacheStatistics,*',
  'attributes'   => [ 'CacheHits', 'CacheMisses', 'ObjectCount' ],
  'type_names'   => ['name'],
  'result_alias' => 'ehcache',
  'writers'      => [
    {
      '@class'            => 'com.googlecode.jmxtrans.model.output.KeyOutWriter',
      'outputFile'        => '/tmp/keyout2.txt',
      'maxLogFileSize'    => '10MB',
      'maxLogBackupFiles' => '200',
      'debug'             => true,
    },
  ],
}

Default value: undef

Functions

jmxtrans::merge_notundef

Type: Puppet Language

This function will merge a list of hashes, ignoring key => value pairs in the the latter which have a value of undef

jmxtrans::merge_notundef(Hash $original, Hash $to_merge)

This function will merge a list of hashes, ignoring key => value pairs in the the latter which have a value of undef

Returns: Any Merged list

original

Data type: Hash

The base hash. All key values from this will be included.

to_merge

Data type: Hash

A variable number of hashes to merge in. Each of these will have its key => value pairs added to the original hash, except where the value is undef. Later values will override earlier values.

jmxtrans::to_json

Type: Ruby 4.x API

Stringify data into the JSON format

jmxtrans::to_json(Data $data)

Stringify data into the JSON format

Returns: Any Generated JSON string

data

Data type: Data

Data to stringify

Change log

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

v0.1.5 (2021-07-29)

Full Changelog

Added

• Fixing module dependencies in metadata.json #10 (timdeluxe)

v0.1.4 (2021-07-28)

Full Changelog

Fixed

• Fixing beaker tests #11 (timdeluxe)

v0.1.3 (2021-06-10)

Full Changelog

v0.1.2 (2021-06-10)

Full Changelog

Added

• allow a URL source to be passed to dpkg #8 (suckatrash)
• Gelf writer #7 (dploeger)
• Systemd template parametrized #6 (mrodm)
• Remove preexec commands #5 (petems)
• Adds config class #1 (petems)

Fixed

• Updates so CI works #9 (genebean)
• Manage jmxtrans /var/run/ directory #4 (charlesdunbar)

v0.1.1 (2016-04-28)

Full Changelog

v0.1.0 (2016-04-28)

Full Changelog

* This Changelog was automatically generated by github_changelog_generator