Groovy Resource Connector

Groovy connector allows to monitor and manage external components using Groovy scripts. It can be useful in following cases:

Groovy connector is based on Groovy 2.4

Each attribute, event, operation and health check should be declared in main script file using DSL extensions

Connection String

Connection string specifies name of the main script and set of paths in URL format with Groovy scripts separated by symbol ;. For example: Main.groovy;file:/usr/local/snamp/groovy;file:/usr/local/snamp/scripts

Configuration parameters

JMX Resource Connector recognizes the following parameters:

Parameter Type Required Meaning Example
groovy.warnings String No Groovy warning level likely errors
groovy.source.encoding String No Encoding to be used when reading Groovy source files
groovy.classpath String No Classpath using to find third-party JARs /usr/local/jars:/home/user/jars
groovy.output.verbose Boolean (true or false) No Turns verbose operation on or off true
groovy.output.debug Boolean No Turns debugging operation on or off false
groovy.errors.tolerance Integer No Sets the error tolerance, which is the number of non-fatal errors (per unit) that should be tolerated before compilation is aborted

All these parameters (including user-defined) will be visible as global variables within all the available scripts.

Configuring attributes

Each attribute configured in Groovy Resource Connector has following configuration schema:

Configuring events

Each event configured in Groovy Resource Connector has following configuration schema:

Parameter Type Required Meaning Example
severity String No Overrides severity level of the emitted notification warning

Configuring operations

Each operation configured in Groovy Resource Connector has following configuration schema:

Scripting

Groovy Resource Connector provides following features for Groovy scripting:

Each instance of the Groovy Resource Connector has isolated sandbox with its own Java class loader used for Groovy scripts.

All configuration parameters specified at the resource-level will be visible for all scripts. For example, you have configured initScript and customParam parameters. The value of these parameters can be obtained as follows:

println customParam

Read SNAMP Management Information Model before you continue

Groovy connector provides following DSL extensions accessible from any type of scripts:

Following example demonstrates reading attribute of the connected managed resource:

println resourceName
def value = getResourceAttribute 'app-server', 'freeMemory'
if(value < 100) error 'Not enough memory'

Following example demonstrates subscribing on the event within the connected managed resource:

import javax.management.NotificationListener

NotificationListener listener = { notif, hndback -> println notif.message }

addNotificationListener 'app-server', listener

Working with timers:

def timer = createTimer({ println 'Tick' }, 300)  //will print 'Tick' every 300 milliseconds
timer.run() //start printing
timer.close() //stop printing

the code above is equivalent to

def timer = schedule({ println 'Tick' }, 300)
timer.close()

Get configuration of the connected resource:

def config = getResourceConfiguration 'app-server'

println config.connectionString
println config.connectionType
println config.parameters.socketTimeout //socketTimeout is the name of configuration property

Simple messaging using communicator:

def communicator = getCommunicator 'test-communicator'
communicator.addMessageListener({ msg -> println msg}, MessageType.SIGNAL)

in other script file

def communicator = getCommunicator 'test-communicator'
communicator.sendSignal 'Hello, world!'

Synchronous messaging using communicator:

//script1.groovy
communicator = getCommunicator 'test-communicator'
def listen(message){
    communicator.sendMessage('pong', MessageType.RESPONSE, message.messageID)
}
communicator.addMessageListener(this.&listen, MessageType.REQUEST)

//script2.groovy
communicator = getCommunicator 'test-communicator'
def response = communicator.sendRequest('ping', {msg -> msg.payload}, 2000)  //2 seconds for response timeout
println response  //pong

Programming attributes

Attribute declaration consists of the following parts:

Skeleton of attribute declaration:

attribute {
    name "<attribute-name>"
    description "<human-readable description>"  //optional
    type <type>
    get <getter>
    set <setter>  //optional
}

Example:

attribute {
    name "DummyAttribute"
    type INT32
    get {return 42}
    set {value -> println value}
}

Programming events

Event declaration consists of the following parts:

Skeleton of event declaration:

event {
    name <event-category>
    description "<human-readable description>"  //optional
}

Example:

event {
    name "GroovyEvent"
}

Programming operations

Operation declaration consists of the following parts:

Skeleton of operation declaration:

operation {
    name "<operation-name>"
    description "<human-readable description>"  //optional
    parameter "<param-name>", <param-type>  //zero or more parameters
    ...
    returns <type>
    implementation <implementation code>
}

Example:

operation {
    name "CustomOperation"
    description "Test operation"
    parameter "x", INT64
    parameter "y", INT64
    returns INT64
    implementation {x, y -> x + y}
}

Programming health checks

Health check can be implemented using the following declaration:

import com.bytex.snamp.connector.health.HealthStatus

protected HealthStatus getStatus(){
  new OkStatus()
}

If implementation of this method is not provided then connector always return OK status.

Information Model Mapping

This section describes mapping between Groovy data types and SNAMP Management Information Model

Groovy Data Type Management Information Model Example
byte int8
short int16
int int32 42i
long int64 42L
float float32 3.14F
double float64 3.14D
BigInteger bigint 42G
BigDecimal bigdecimal 42.1G
char char 'a'
String string "Hello, world!"
boolean bool true
Date datetime new Date()
javax.management.ObjectName objectname new ObjectName('type=Foo')
javax.management.openmbean.CompositeData Dictionary asDictionary(key1: 67L, key2: true)
javax.management.openmbean.TabularData Table asTable([[column1: 6, column2: false], [column1: 7, column2: true]])

Clustering

emitNotification can cause duplication of notifications and receiving side in clustered environment. SNAMP doesn't provide automatic resolution of this issue for Groovy Connector. Guard emitNotification call with if(activeClusterNode) condition.