Page tree
Skip to end of metadata
Go to start of metadata
After reading this section, you will know...

... how to configure MoSKito with external configuration file, via ConfigureMe system.

In this section:

Since v2.x, MoSKito may be configured via external configuration file. This configuration is based on ConfigureMe - the state of the art JSON configuration framework.

MoSKito Config is build of different configuration objects, which makes it easier to change and maintain. Each object can be configured separately. 

Below is a typical configuration, different sections of it will be discussed separately.

{
	"@thresholdsAlertsConfig": {
		"@notificationProviders": [
			{
				"className": "net.anotheria.moskito.core.threshold.alerts.notificationprovider.LogFileNotificationProvider",
				"parameter": "MoskitoAlert",
				"guardedStatus": "GREEN"
			},{
				"className": "net.anotheria.moskito.core.threshold.alerts.notificationprovider.MailNotificationProvider",
				"parameter": "leon@leon-rosenberg.net",
				"guardedStatus": "RED"
			},{
				"className": "net.anotheria.moskito.core.threshold.alerts.notificationprovider.SysoutNotificationProvider",
				"parameter": "",
				"guardedStatus": "GREEN"
			}
		],
		"@alertHistoryConfig": {
			"maxNumberOfItems": 500,
			"toleratedNumberOfItems": 550
		}
	},
	"@accumulatorsConfig" : {
		"accumulationAmount": 500,
		"@accumulators": [
			{
				"name": "Configured SessionCount Cur 5m",
				"producerName": "SessionCount",
				"statName": "Sessions",
				"valueName": "cur",
				"intervalName": "5m",
			}
		]
 },
	"@thresholdsConfig": {
		"@thresholds": [
			{
			"name": "Configured-5m-ThreadCount",
			"producerName": "ThreadCount",
			"statName": "ThreadCount",
			"valueName": "Current",
			"intervalName": "5m",
			//timeUnit can be ignored here
            "@guards": [
				{"value": "30", "direction": "DOWN", "status": "GREEN"},
				{"value": "30", "direction": "UP", "status": "YELLOW"},
				{"value": "45", "direction": "UP", "status": "ORANGE"},
				{"value": "60", "direction": "UP", "status": "RED"},
				{"value": "100", "direction": "UP", "status": "PURPLE"},
			]
			}
		]
	},

Configuration file and location

MoSKito is configured based on @ConfigureMe Annotations:

@ConfigureMe(name="moskito")
public class MoskitoConfiguration {
	@Configure
	private ThresholdsAlertsConfig thresholdsAlertsConfig = new ThresholdsAlertsConfig();
	@Configure
	private ThresholdsConfig thresholdsConfig = new ThresholdsConfig();
	@Configure
	private AccumulatorsConfig accumulatorsConfig = new AccumulatorsConfig();
...

ConfigureMe expects the Configuration file to be named moskito.json and looks for it in the classpath. However, it is possible to give this file a different name (or use xml or properties instead of json). 

MoskitoConfiguration configuration = new MoskitoConfiguration();
ConfigurationManager.INSTANCE.configureAs(configuration, "anothername");
MoskitoConfigurationHolder.INSTANCE.setConfiguration(configuration);

Of course, you can setup the configuration object entirely by yourself (write the needed code) or get current configuration object from MoskitoConfigurationHolder and alter it.
However, do it at the start of the system, since many of the configuration options can't be changed on the fly (yet). Still, you can change others.

Sections

ThresholdsAlerts

The ThresholdsAlerts config contains two sections: AlertHistory and NotificationProviders

	"@thresholdsAlertsConfig": {
		"@notificationProviders": [ NOTIFICATIONPROVIDER ],
		"@alertHistoryConfig": { }
    }

AlertHistory

The AlertHistory config defines how many items are stored in the in-memory alert history, and can be displayed in MoSKito-WebUI:

		"@alertHistoryConfig": {
			"maxNumberOfItems": 500,
			"toleratedNumberOfItems": 550
		}
AttributeValueDefault
maxNumberOfItems
Number of items that can be stored in the alert history.200
toleratedNumberOfItems
Tolerated overload. The AlertHistory will be shortened only after the size growth above toleratedNumberOfItems.
This helps to reduce the amount of list operations.
220

NotificationProviders

The built-in notification system allows to configure multiple notification providers. Notification providers will be triggered as soon as a threshold changes its status and the change breaks the limits of this notification provider. 

Each notification provider is configured with the following attributes:

AttributeValue
classNameName of the class that implements net.anotheria.moskito.core.threshold.alerts.NotificationProvider
parameterCustomization of the provider. This attribute is provider-specific.
guardedStatus

The triggering status.

Parameter interpretation:

ClassNameInterpretation
net.anotheria.moskito.core.threshold.alerts.notificationprovider.LogFileNotificationProviderName of the Logger.
net.anotheria.moskito.core.threshold.alerts.notificationprovider.MailNotificationProviderComma-separated list of recipient's email addresses.
net.anotheria.moskito.core.threshold.alerts.notificationprovider.SysoutNotificationProvider
Ignored.

Thresholds

What is a Threshold?

Thresholds continuously watch a single producer and give a signal when its performance changes.

For more info, read the Thresholds section of MoSKito Concepts.

The thresholds config contains a list of threshold objects. This is another way to define thresholds.

Thresholds may also be added via MoSKito-Inspect.

	"@thresholdsConfig": {
		"@thresholds": [ THRESHOLD ]
	},

or, in Java words:

public class ThresholdsConfig {

	/**
	 * Configured thresholds.
	 */
	@Configure
	private ThresholdConfig[] thresholds;

Threshold

Each Threshold contains the following info:

{
  "name": "Configured-5m-ThreadCount",
  "producerName": "ThreadCount",
  "statName": "ThreadCount",
  "valueName": "Current",
  "intervalName": "5m",
  //timeUnit can be ignored here
  "@guards": [ GUARD ]
}
AttributeValue
nameThe name of the value for AlertHistory, Logs and WebUI
producerNameName (id) of producer. Exact match required!
statNameName of the StatValue. Exact match required!
valueNameName of the Value. Exact match required!
intervalNameName of the interval the Threshold is tied to.
timeUnitTimeUnit if applicable (for example, MILLISECONDS or SECONDS)See net.anotheria.moskito.core.stats.TimeUnit
guardsList of GUARD objects.

Threshold Guards

A guard is a trigger (set of conditions) that changes the status of a Threshold. 

For example:

	{"value": "30", "direction": "DOWN", "status": "GREEN"},
	{"value": "30", "direction": "UP", "status": "YELLOW"},
	{"value": "45", "direction": "UP", "status": "ORANGE"},
AttributeValue
valueThe value of the associated (producer | stat | statvalue) tuple, which changes the Threshold's status.
directionDirection in which the value is passed: UP means the current value is higher than the guard value, DOWN - lower than the guard value.
statusThe status that the Threshold is set to after the guard is triggered.

Accumulators

Accumulators store the performance history of a producer and display accumulated data in charts.

For more info, read about Accumulators in MoSKito Concepts.

The accumulators section configures accumulators, setting the default accumulationAmount.

Accumulation amount

	"@accumulatorsConfig" : {
		"accumulationAmount": 500
	},

The accumulationAmount controls the amount of values an accumulator can store. The real amount can be 10% higher, because 10% overload is allowed to reduce number of list operations.

Accumulators

	"@accumulatorsConfig" : {
...
		"@accumulators": [
			{
				"name": "Configured SessionCount Cur 5m",
				"producerName": "SessionCount",
				"statName": "Sessions",
				"valueName": "cur",
				"intervalName": "5m"
			}
            ...
		]
	},

Basically, accumulators' section contains the same values for each accumulator as for each threshold:

AttributeValue
nameThe name of the value for WebUI
producerNameName (id) of the producer. Exact match required!
statNameName of the StatValue. Exact match required!
valueNameName of the Value. Exact match required!
intervalNameName of the interval the accumulator is tied to.
timeUnitTimeUnit if applicable (for example, MILLISECONDS or SECONDS)See net.anotheria.moskito.core.stats.TimeUnit

Gauges

Gauges are a visualization tool for representation of current state of a producer in relation to it's expected min and max states.

Gauges can be used in Dashboards. 


Gauges

Gauges are configured in their own section in the configuration file. 

"@gaugesConfig": {
    "@gauges": [GAUGE],
	"@defaultZones":[ZONE]
}

Each gauge is configured in following way

{
  "name": "Name of the gauge is displayed in the gauge itself and should be short",
  "caption": "Caption of the gauge block, has more chars to fit",
  "@minValue" : GAUGEVALUE,
  "@currentValue" : GAUGEVALUE,
  "@maxValue" : GAUGEVALUE,
  "@zones": [ZONE] 
}

GAUGEVALUE can be a constant or a reference to a producer. In the following example a static gauge is configured.

"@minValue": {
    "constant": 0
},
"@currentValue": {
  "constant": 70
},
"@maxValue": {
  "constant":100
},

One might argue, that a static gauge doesn't make much sense, but it demonstrates the principle and you can use it to present a value which is produced outside of the system.

A GAUGEVALUE can be tight to a producer/stat/value tuple as in following example:

{
  "name": "Running",
  "caption": "Running Threads",
  "@minValue": {
    "constant": 0
  },
  "@currentValue": {
    "producerName": "ThreadStates",
    "statName": "RUNNABLE",
    "valueName": "Current",
    "intervalName": "1m"
  },
  "@maxValue": {
    "producerName": "ThreadCount",
    "statName": "ThreadCount",
    "valueName": "current",
    "intervalName": "default"
  }
}

Remember you can use either constant keyword or producerName, statName and valueName. If a gauge value config contains constant everything else will be ignored for this value.

Besides the values the zones of each gauge can be configured. If you don't provide gauge specific configuration, defaultZones are applied. If you provide no defaultZones either, the pre-configured default zones are used, which are hardwired in GaugeAPIImpl.


DefaultZones

You can configure default zones which would be applied to all your gauges, if the gauges don't have explicit zone configuration. 

"@gaugesConfig": {
    "@gauges": [GAUGE],
	"@defaultZones":[ZONE]
}

For example:

"@defaultZones":[
  {
    "color": "orange",
    "left": 0.85,
    "right": 0.9
  },
  {
    "color": "red",
    "left": 0.9,
    "right": 1
  }
]

Full example

Below example configuration of gauges part.

"@gaugesConfig": {
    "@gauges": [
      {
        "name": "Constant",
        "@minValue": {
            "constant": 0
        },
        "@currentValue": {
          "constant": 70
        },
        "@maxValue": {
          "constant":100
        },
        "@zones":[
          {
            "color": "green",
            "left": 0,
            "right": 0.25
          },
          {
            "color": "yellow",
            "left": 0.25,
            "right": 0.5
          },
          {
            "color": "orange",
            "left": 0.5,
            "right": 0.75
          },
          {
            "color": "red",
            "left": 0.75,
            "right": 1
          }
        ]

      },
      {
        "name": "Sessions",
        "@minValue": {
          "constant": 0
        },
        "@currentValue": {
          "producerName": "SessionCount",
          "statName": "Sessions",
          "valueName": "cur",
          "intervalName": "default"
        },
        "@maxValue": {
          "producerName": "SessionCount",
          "statName": "Sessions",
          "valueName": "max",
          "intervalName": "default"
        }
      },
      {
        "name": "Memory",
        "caption": "Used memory",
        "@minValue": {
          "constant": 0
        },
        "@currentValue": {
          "producerName": "Heap memory",
          "statName": "Heap memory",
          "valueName": "Used Mb",
          "intervalName": "default"
        },
        "@maxValue": {
          "producerName": "JavaRuntimeMax",
          "statName": "JavaRuntimeMax",
          "valueName": "Current Mb",
          "intervalName": "default"
        }
      },
      {
        "name": "Blocked",
        "caption": "Blocked Threads",
        "@minValue": {
          "constant": 0
        },
        "@currentValue": {
          "producerName": "ThreadStates",
          "statName": "BLOCKED",
          "valueName": "Current",
          "intervalName": "1m"
        },
        "@maxValue": {
          "producerName": "ThreadCount",
          "statName": "ThreadCount",
          "valueName": "current",
          "intervalName": "default"
        }
      },
      {
        "name": "Running",
        "caption": "Running Threads",
        "@minValue": {
          "constant": 0
        },
        "@currentValue": {
          "producerName": "ThreadStates",
          "statName": "RUNNABLE",
          "valueName": "Current",
          "intervalName": "1m"
        },
        "@maxValue": {
          "producerName": "ThreadCount",
          "statName": "ThreadCount",
          "valueName": "current",
          "intervalName": "default"
        }
      }
    ],
  "@defaultZones":[
    {
      "color": "orange",
      "left": 0.85,
      "right": 0.9
    },
    {
      "color": "red",
      "left": 0.9,
      "right": 1
    }
  ]

},


Tracers

Tracers allow you to monitor who is executing a place of code, in code. Tracers are typically switched on/off from inspect on Runtime with the Tracer button in SingleProducerView in MoSKito Inspect:

However, there are some configuration options for Tracers too.

Tracers are configured via the element tracingConfig in MoSKito Configuration.

Here an example:

"@tracingConfig": {
  "tracingEnabled": true,
  "loggingEnabled": true,
  "inspectEnabled": true,
  "maxTraces": 50,
  "tracers": [],
  "shrinkingStrategy": "KEEPLONGEST"
}

All tracing configuration options are changeable at Runtime. The options mean in particular:

AttributeValue
tracingEnabledtrue/false. If false tracing won't be active. Tracing can generate some additional load, mainly due to StackTrace creation. So it's wise to switch it off if not needed.
loggingEnabledtrue/false.  If true every trace will be logged out into a Logger called MoSKitoTracer.
inspectEnabledtrue/false. If true support for inspection in MoSKito Inspect is enabled
maxTracesmax number of traces (calls with parameters and stacktraces) per Tracer.To reduce array operations MoSKito will allow Tracers to get 10% more traces than allowed, before cutting them.
tracersPredefined Tracers. This is basically a list of ProducerIds.Actually, the idea of tracers is that you want them dynamically, but you can add them in configuration too.

shrinkingStrategy

"FIFO" or "KEEPLONGEST" - defined by net.anotheria.moskito.core.config.tracing.ShrinkingStrategyWhen amount of tracers exceeds the tolerated amount of traces, MoSKito will start to remove some traces to save memory space. There are two possible strategies here, FIFO -> First in First Out or KEEPLONGEST. Keeplongest sorts the traces by execution duration and keeps those which lasts longer. This is useful in tracking anomalies. 



Plugins

Plugins section allows to load custom software aka plugins.

	"@pluginsConfig": {
		"@plugins": [
			{
				"name": "EmbeddedCentralConnector",
				"configurationName": "none",
				"className": "net.anotheria.moskito.central.connectors.embedded.EmbeddedConnector"
			}
		]
	}

For each plugin, the following values are configured:

AttributeValue
nameThe name of the plugin for plugin view.
configurationNameThe name of the plugin configuration.The configuration is of plugin-special type.
classNameThe name of the plugin class.The class should implement net.anotheria.moskito.core.plugins.Moskitoplugin



Builtin Producers

Builtin Producers section allows to configure which builtin producers should be enabled by default. If you don't set anything, all producers are enabled (default value = true).

Example:

	"@builtinProducersConfig": {
		"javaMemoryProducers": false,
		"javaMemoryPoolProducers": false,
		"osProducer": false
	}


Supported attributes are:

AttributeProducers
javaMemoryProducersMemory based on Runtime.getRuntime().freeMemory
javaMemoryPoolProducersMemory based on GC Memory Pools / Spaces
javaThreadingProducersThreadCountProducer
ThreadStatesProducer 
osProducerOS Stats (on *nix only)
incldung min/max files etc 
runtimeProducerRuntime - process name and uptime

mbeanProducers

Automatical monitoring of all mbeans. Requires additional configuration (MBeanProducerConfig)
gcProducerCreates a gc producer for every garbage collector mbean found in system

Journey

Journey are configured in their own section in the configuration file. 

"@journeyConfig": {
    "parameterLengthLimit": 200,
	"toStringCollections": false,
	"toStringMaps": false
 }

Each journey is configured in following way

AttributeValueDefault
parameterLengthLimit
Limit for the parameter length. If parameter length is more than configured, it will be cut. This also applies to return values.
100
toStringCollections
If true collections are "toStringed", if false, only size is shown.
true
toStringMaps
If true maps are "toStringed", if false, only size is shown.
true


Errorhandling

Errorhandling config defines how MoSKito stores and helps you to handle errors that occur in your application.

Here is a configuration example:

  "@errorHandlingConfig": {
    "autoChartErrors": true,
    "autoChartErrorsInterval": "1m",
    "logErrors": true,
    "@catchers": [
      {
        "clazz": "java.lang.IllegalArgumentException",
        "target": "LOGANDMEMORY",
        "parameter": "IllegalArgExcLog"
      },
      {
        "clazz": "org.springframework.web.util.NestedServletException",
        "target": "MEMORY",
        "parameter": ""
      }
    ],
    "catchersMemoryErrorLimit": 50


AttributeMeaning
autoChartErrors
If true, for every throwable that MoSKito sees an accumulator will be created.
autoChartErrorsInterval
Name of the interval the error accumulators have to use. This is used for the autoChartedErrors (accumulators that have been created if autoChartErrors=true) as well as cumulated errors.
logErrors
If true, all errors will be logged to the log-file named auto-caught-errors.log. The logger name can be changed in the logback.xml (or any other slf4j compartible logging framework you are using).
catchersMemoryErrorLimit
If catchers are configured, they will hold max 10% more last errors, that the value of catchersMemoryErrorLimit. Default is 50.
countRethrows
If countRethrows is enabled MoSKito will try to analyze if errors are rethrown within the execution. Default is false. This is due to the fact, that the rethrows are saved in a ThreadLocal variable within the MoSKitoContext and could lead to memory leak if MoSKitoContext.cleanup() is not called after the execution.
@catchersDefined catchers for specific errors.

Catchers

You can configure one or multiple catchers for specific exceptions you want to investigate. 

AttributeMeaning
clazz
Exception class, for example java.lang.IllegalArgumentException
target

Catch target, is one of: LOG, MEMORY or LOGANDMEMORY.

Memory means that the stacktraces will be held in memory for investigation via console.

Log means that the exceptions will be logged into a specific logfile.

parameter
In case of LOG or LOGANDMEMORY target name of the logger where the exception has to be send. You will need to configure this logger separately in the logback.xml


Catchers will are accessible from the Navigation point: Everything else | Errors and look like this:

Every catcher will container up to catchersMemoryErrorLimit errors:

And you can click on every error to see the stack trace:

Autocharted errors

In case autocharting is enabled two charts will be created for each error, a total and initial value. Initial means errors which were the first in the execution thread, total - all errors, including followup errors.

this allows you to analyse error occurrence visually.