Collecting performance metrics
Functions for performance metrics are available via perfmon library. There are several aspects of configuring it:
- what objects are to be scanned and collected;
- how collected metrics should be preprocessed and described;
- how often metrics should be collected;
Some parts of perfmon library are also used for other purposes, for example Zabbix discovery functions.
Querying JMX object graph
JMX object graph query consists of JMX object name mask, list of object name attributes to be fetched and sets of rules defining how to traverse fetched objects. Query result is a list of objects containing finally reached object (or value) and map of all attributes (explicitly) fetched while traversing object graph. Query definition objects are immutable but offer some methods that create altered variants.
Simplest query object can be created using zorka.query() function:
zorka.query(mbsName, objectName, attr1, attr2, ....)Query rule that will descend into selected attribute of a method (and optionally remember its name) can be added using get() method:
query = query.get(attr)
query = query.get(attr, name)First variant of this method will simply descend into objects, second one will also add attribute name to query result. When interpreting get() rule, agent will use ObjectInspector.get() method to descend.
Query rule that will list object attributes and descend into matching ones can be defined using list() method:
query = query.list(regex)
query = query.list(regex, name)When interpreting list() fule, agent will use ObjectInspector.list() method to list all attributes and then ObjectInspector.get() method to descend into matching attributes. For each matching attribute, separate result is created and (optionally) attribute name is stored.
Metric templates are used by permon scanners and can be assigned to queries using metric() method:
query = query.metric(template)Created (and configured) query objects can be supplied to metrics scanners or discovery functions (eg. for zabbix).
Defining metric templates
Metric templates define how metrics should be preprocessed and how should metrics present themselves. There are several kinds of metrics:
perfmon.metric(name, units)Creates metric that will simply pass obtained values without preprocessing. Metric name will be visible in trace viewer and can contain macros referring to attributes attached to query results (in usual form ${attributeName}). Second parameters describes measurement units as displayed in trace viewer.
perfmon.delta(name, units)Creates metric that will calculate simple delta of obtained values. Supplied parameters have the same meaning as above.
perfmon.timedDelta(name, units)Creates metric that will calculate delta per second of obtained values. Supplied parameters have the same meaning as above.
perfmon.rate(name, units, nom, div)This metric tracks two attributes of obtained object at once and calculates rate as delta of nom attribute divided by delta of div attribute.
Metric template objects created by above functions are immutable objects that can be altered in the following ways:
template = template.multiply(multiplier)This causes metric results to be multiplied by given multiplier.
template = template.dynamicAttrs(attr, attr, ...)Marks some query result attributes as dynamic. Dynamic attributes are passed with each metric instance and do not impose stress on symbol registry nor metric registry.
Defining metric scanners
scanner = perfmon.scanner(name, query1, query2, ...)Creates scanner object that will periodically execute all queries and process their results accordingly. All resulting metrics are grouped under single scanner name. Note that queries that have no metric templates assigned will be ignored.
Scanner objects implement Runnable interface and can be supplied to all kinds of schedulers of executors (eg. using zorka.schedule() function).