Skip to content
Go to file

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


GSampler is a tool for sampling stats/metrics from various sources and writing them to either Graphite or the console.

The following stats readers are supported out of the box:

  • Groovy (inline script or file)
  • JDBC (inline queries or sql file)
  • Exec (execute a system command)
  • ElasticSearch (inline queries, tested with ES 5.1)

The following stats writers are supported out of the box:

  • Graphite
  • Console


The configuration file for GSampler is a groovy script located in $BASEDIR/config/gsampler.groovy (can be changed with -c option).

The following global methods are available in a config script:

  • globalPrefix(String) - all stats read are prefixed like this: "${globalPrefix}.${statName}" [default: 'sampler']
  • sampler(id, reader, namePrefix, interval, TimeUnit[default: SECONDS]) - registers a sampler with specified reader, prefix, and interval
  • writer(writer) - registers the specified writer to writer stats
  • decrypt('') - decrypts the given string


// top level block is an extension name
groovy {
	// creates a groovy stat reader that executes the inline script, scripts must return a Map<String, Number|StatValue>
	def groovyTextReader = scriptText('[groovyStat: new StatValue(1, new Date())]')

	// creates a reader that executes the groovy script file and passes the arguments specified to it (bound to 'args')
	def groovyFileReader = scriptFile('/scripts/groovy/readSomeStats.groovy', ['arg1', 'arg2'])

    sampler('text', groovyTextReader, 'groovy.stats', 1)
    sampler('file', groovyFileReader, 'groovy.stats', 1)

jdbc {
	// registers a JDBC driver, will download driver jar using Aether
	driver('org.h2.Driver', 'com.h2database:h2:1.1.105')

	// creates a connection factory object which can be passed to any jdbc reader
	def cf = connectionFactory('jdbc:h2:mem:', 'sa', '')

	def queries = ["select '', count(*) from some_table"]

	// registers a sampler with the connection factory and queries from a list
	sampler('jdbc-stats', jdbcReader(cf, queries), 'sql.stats.prefix', 5, MINUTES)

exec {
    // use default metric parsing, <metric name>[whitespace]<value>
    sampler('default', command(''), 'default', 5, MINUTES)

    // set a custom parser, expects either regex with 2 matching groups or 1 AND metric name
    def p = parser(/Average = (\\d+)ms/, 'ping.average')
    sampler('exec', command('ping -n 1', 1000, p), 'net', 1, MINUTES)

elasticsearch {
    def idx = index('http://elasticseach:9200')
    def esQueries = ['posts': 'type:apacheAccess AND verb:POST']

	//for 'term', pass null if you are not doing a terms query
    sampler('es', queries(idx, esQueries, 'term', 5, MINUTES), 'prefix', 5, MINUTES)

console {
	// registers a console writer to write sampled stats to

graphite {
	// registers a graphite writer (both console and graphite will write each stat sampled)
	writer(graphiteWriter('graphite-host', 2003))


The simplest way to run GSampler is with Docker.

docker run -v /your/data/dir:/sampler/data -p 2245:2245 reicoop/gsampler

Encryption Support

Passwords and any other secret data can be encrypted in the configuration file.

  1. POST /encrypt with plaintext value as the request body
  2. Pass the response body to the decrypt function in the config file: decrypt('HspkoY4K8RBtSIMBJR864ACUgDooH16uqbi8r1WjqaDHG9iUs+czog==')

HTTP Interface

A very simple JSON based HTTP interface is exposed by GSampler. The http server is started on port 2245.

The following endpoints are exposed by GSampler:

  • GET /self-stats - returns a json map with stats about the sampler itself (total stats collected, etc)
  • GET /config - returns a json version of the parsed configuration that lists the registered samplers/writers
  • GET /errors - any exceptions thrown by a sampler
  • POST /reload-config - forces a configuration reload
  • POST /encrypt - accepts a request body to encrypt, returns the encrypted value that can be used in decrypt(...) method


A tool for sampling stats/metrics from various sources and writing them to a stats collection tool like Graphite.




No releases published


No packages published
You can’t perform that action at this time.