ruxit.api package

Submodules

ruxit.api.base_plugin module

Defines the base class for other plugins to use.

class ruxit.api.base_plugin.BasePlugin(**kwargs)[source]

Bases: object

Base class for plugins.

__init__ should not be overridden without a call to super.

Parameters:
  • config (Dict[str, str]) -- plugin configuration
  • results_builder (ResultsBuilder) -- instance for this plugin,
  • json_config -- parsed plugin.json contents,
  • plugin_info (PluginInfo) -- json data of the plugin exposed in a more convenient way,
  • associated_entity -- monitored entity associated with the plugin, if any (deprecated).
  • activation_context -- activation context for the plugin,
  • process_snapshot (ProcessSnapshot) -- latest available at method call,
  • entity_resolver (EntityResolver) -- exposes additional methods for querying snapshot
  • logger -- plugin specific logger for plugin development, set to None only in unit tests
initialize(**kwargs)[source]

Abstract method for custom plugin initialization.

Called after __init__. Override if additional initialization (e.g.: aquiring connections once instead of on every query method execution) is needed.

Parameters:**kwargs -- see BasePlugin for keyword args reference
query(**kwargs)[source]

Abstract method called to gather measurements. Every plugin should override this method.

Parameters:**kwargs -- see BasePlugin for keyword args reference
close(**kwargs)[source]

Abstract method called when plugin is deactivated.

Parameters:**kwargs -- see BasePlugin for keyword args reference
find_all_process_groups(predicate)[source]

Searches the latest process snapshot for all process groups matching the predicate

Parameters:predicate -- One parameter function returning bool if snapshot entry meets predicate conditions
Returns:list of process snapshot entries
find_single_process_group(predicate)[source]

Searches the latest process snapshot for a process group matching the predicate

Parameters:predicate -- One parameter function returning bool if snapshot entry meets predicate conditions
Returns:One instance of process snapshot entry
Raises:ruxit.api.exceptions.ConfigException -- if not exactly 1 matching pgi found
find_all_processes(process_predicate)[source]

Searches the latest process snapshot for a process and associated process group that match the criteria passed in arguments.

Only processes of types associated with plugin are being searched.

Parameters:process_predicate -- one parameter function which takes process info as input, and returns bool
Returns:list of tuple(PGI, process) that matched predicate
find_single_process(process_predicate)[source]

Searches the latest process snapshot for a process and associated process group that match the criteria passed in arguments.

If more than one process matching the criteria is found, exception is raised.

Only processes of types associated with plugin are being searched.

Parameters:process_predicate -- one parameter function which takes process info as input, and returns bool
Returns:tuple(PGI, process)
Raises:ruxit.api.exceptions.ConfigException -- if not exactly 1 matching process found

ruxit.api.data module

Structures for holding data gathered by plugins. They enforce types so that a plugin cannot accidentally report a number as a string.

class ruxit.api.data.BaseMetric(key, value, dimensions: typing.Dict[str, str] = None, entity_selector=FromPluginSelector())[source]

Bases: object

key

Key of the measurement. Must be a string.

value

Value of the measurement. Must be convertible to float.

dimensions

Dimensions of the measurement. A Dictionary with string keys and string values.

class ruxit.api.data.PluginMeasurement(key: str, value: float, dimensions: typing.Dict[str, str] = None, entity_selector=FromPluginSelector())[source]

Bases: ruxit.api.data.BaseMetric

Single plugin measurement.

Use of this class is optional. ResultsBuilder exposes methods that handles this type directly and those that abstract them away.

key

Key of the measurement. Must be a string.

value

Value of the measurement. Must be convertible to float.

class ruxit.api.data.PluginStateMetric(key: str, value: str, dimensions: typing.Dict[str, str] = None, entity_selector=FromPluginSelector())[source]

Bases: ruxit.api.data.BaseMetric

State measurement.

States are string described in plugin json as statetimeseries

key

Key of the measurement. Must be a string.

value

Value of the measurement. Must be convertible to float.

class ruxit.api.data.PluginMeasurementV3(key: int, value: float, dimensions: typing.Dict[str, str] = None, entity_selector=FromPluginSelector())[source]

Bases: ruxit.api.data.BaseMetric

Not allowed for Custom Plugin

key

Key of the measurement. Must be a string.

value

Value of the measurement. Must be convertible to float.

class ruxit.api.data.MEAttribute[source]

Bases: enum.Enum

Enumerates types of properties to report.

ID_CALCULATION_INPUT = <MEAttribute.ID_CALCULATION_INPUT: 1>
INTERNAL_DEBUG_VALUE = <MEAttribute.INTERNAL_DEBUG_VALUE: 2>
INTERNAL_DEBUG_PROPERTY = <MEAttribute.INTERNAL_DEBUG_PROPERTY: 3>
PROCESS_GROUP_INSTANCE_MODULES = <MEAttribute.PROCESS_GROUP_INSTANCE_MODULES: 4>
DOCKER_CONTAINER_PROPS = <MEAttribute.DOCKER_CONTAINER_PROPS: 5>
PROCESS_GROUP_TECHS = <MEAttribute.PROCESS_GROUP_TECHS: 6>
AUTO_TAGS = <MEAttribute.AUTO_TAGS: 7>
AGENT_SEC_SETTINGS = <MEAttribute.AGENT_SEC_SETTINGS: 8>
LOG_PATH_SIZES = <MEAttribute.LOG_PATH_SIZES: 9>
AGENT_INSTRUMENTATION_INFO = <MEAttribute.AGENT_INSTRUMENTATION_INFO: 10>
FILE_STATUS = <MEAttribute.FILE_STATUS: 11>
AUTO_TAGS_V2 = <MEAttribute.AUTO_TAGS_V2: 12>
LOGS_SAVED_IN_STORAGE = <MEAttribute.LOGS_SAVED_IN_STORAGE: 13>
CONTRIBUTED_NAME = <MEAttribute.CONTRIBUTED_NAME: 14>
class ruxit.api.data.PluginProperty(key=None, value=None, entity_selector=FromPluginSelector(), me_attribute=<MEAttribute.INTERNAL_DEBUG_PROPERTY: 3>)[source]

Bases: object

A text property a plugin can gather.

Parameters:
  • key (string) -- property key
  • value (string) -- property value
  • entity_selector -- plugin's entity selector FromPluginSelector by default
  • me_attribute (MEAttribute) -- property type
key

Key of property.

value

Value of property

me_attribute

Property type

class ruxit.api.data.PluginMeasurementList(timestamp=None, measurements=None)[source]

Bases: object

Collection of PluginMeasurements. Used internally.

timestamp
measurements
is_empty
length

ruxit.api.exceptions module

Exceptions hierarchy usable by plugins. Those errors are not raised automatically, but plugin developers can use them to hint certain categories of errors.

exception ruxit.api.exceptions.AuthException[source]

Bases: Exception

Should be raised when problems with getting required access are detected and identified as being caused by insufficient/invalid permissions (e.g. wrong db password)

exception ruxit.api.exceptions.ConfigException[source]

Bases: Exception

Should be used when a general configuration error is detected (e.g. no reponse when trying to connect to an endpoint specified by the user. Messages from this exception are passed in plugin status.

exception ruxit.api.exceptions.NothingToReportException[source]

Bases: Exception

Should be used when a plugin detects a situation where it was activated, but has no data to report, e.g.

  • A plugin is using broad activation triggers - all Java processes - but is interested only in a specific application e.g elasticsearch
  • A plugin monitors a process that report new stats on an infrequent basic - like once every hour.
  • Monitored process is not configured to expose any metrics

ruxit.api.results_builder module

Data reporting API for plugins.

class ruxit.api.results_builder.ResultsBuilder(logger)[source]

Bases: object

Class storing data gathered by plugins. An instance of this class is associated with each plugin instance.

The builder can store intermittent results and perform calculations on them when they need to be sent away. Those include computing the difference between subsequent measurement, providing per second rates etc.

Measurements can be passed in the form of manually created PluginMeasurement objects (via add_*_result methods), or via absolute/relative/per_second methods which construct the measurement instances themselves.

CUSTOM_PLUGIN_MEASUREMENTS_LIMIT
add_relative_result(plugin_measurement)[source]

Adds a relative result. Use for metrics that increase monotonically (counters etc.) After gathering 2nd result, difference between current and previous one will be sent to the server, if it is non-negative. If there is a negative difference between measurements - nothing is sent.

Parameters:plugin_measurement (PluginMeasurement) -- measurement
add_absolute_result(plugin_measurement)[source]

Adds an absolute results. Absolute results are sent unmodified - no additional calculations are performed.

Parameters:plugin_measurement (PluginMeasurement) -- measurement
add_per_second_result(plugin_measurement)[source]

Adds per second result. Use for metrics that increase monotonically (counters etc.) After gathering 2nd result, difference between current and previous one will be sent to the server, if it is non-negative. It will be divided by the time difference between measurements in seconds - resulting in a per second rate. If there is a negative difference between measurements - nothing is sent.

Parameters:plugin_measurement (PluginMeasurement) -- measurement
absolute(**kwargs)[source]

Adds absolute result. PluginMeasurement object is constructed implicitly in the method. Keyword arguments correspond to PluginMeasurement class keyword with the addition of:

Parameters:
add_event(event)[source]

Adds a event

Parameters:event (Event) -- event
relative(**kwargs)[source]

Adds relative result, with PluginMeasurement object constructed implicitly. Accepts arguments identical to absolute()

per_second(**kwargs)[source]

Adds per second result, with PluginMeasurement object constructed implicitly. Accepts arguments identical to absolute()

add_property(plugin_property)[source]

Adds a property to the results :param plugin_property: the property. :type plugin_property: PluginProperty

set_timestamp(timestamp)[source]

Allows explicit setting of timestamp for all gathered measurements.

Parameters:timestamp -- timestamp
flush_result()[source]

Prepares gathered data to be sent out to the server. Computes values for relative and per_second results.

Returns:measurements and properties gathered during the most recent data collection period.

ruxit.api.selectors module

Selectors available for plugins. The idea of selectors is to abstract away the process snapshot and allow plugin authors to submit results without explicitly knowing what the entity id is.

class ruxit.api.selectors.EntityType[source]

Bases: enum.Enum

An enumeration.

ME_TYPE_UNKNOWN = <EntityType.ME_TYPE_UNKNOWN: 0>
HOST = <EntityType.HOST: 1>
PROCESS_GROUP_INSTANCE = <EntityType.PROCESS_GROUP_INSTANCE: 2>
DOCKER_CONTAINER_GROUP_INSTANCE = <EntityType.DOCKER_CONTAINER_GROUP_INSTANCE: 3>
PROCESS_GROUP = <EntityType.PROCESS_GROUP: 4>
class ruxit.api.selectors.MeId(metype, meid)

Bases: tuple

Create new instance of MeId(metype, meid)

meid
metype
class ruxit.api.selectors.HostSelector[source]

Bases: tuple

Selector binding data with host entity id.

class ruxit.api.selectors.FromPluginSelector[source]

Bases: tuple

Selector binding data with entity id associated with plugin.

The resulting entity id depends on the plugin type, e.g. it might be process group instance id if the plugin is associated with one process group instance, it might be host_id if plugin is associated with host. Some plugins do not have well defined associated entity id (e.g. plugins activated as Singletons)

class ruxit.api.selectors.ListenPortSelector[source]

Bases: tuple

Selector binding data with entity id of process listening on a specified port.

For improved performance, snapshot entries of a given type (which is usually known by plugin) can be scanned for the selected port, before proceeding to all process group instances.

me_type

itemgetter(item, ...) --> itemgetter object

Return a callable object that fetches the given item(s) from its operand. After f = itemgetter(2), the call f(r) returns r[2]. After g = itemgetter(2, 5, 3), the call g(r) returns (r[2], r[5], r[3])

technologies

itemgetter(item, ...) --> itemgetter object

Return a callable object that fetches the given item(s) from its operand. After f = itemgetter(2), the call f(r) returns r[2]. After g = itemgetter(2, 5, 3), the call g(r) returns (r[2], r[5], r[3])

name_pattern

itemgetter(item, ...) --> itemgetter object

Return a callable object that fetches the given item(s) from its operand. After f = itemgetter(2), the call f(r) returns r[2]. After g = itemgetter(2, 5, 3), the call g(r) returns (r[2], r[5], r[3])

class ruxit.api.selectors.DockerSelector[source]

Bases: tuple

Selector binding data with entity id of docker container with specified docker_id.

class ruxit.api.selectors.ExplicitPgiSelector[source]

Bases: tuple

Selector binding data with explicitly specified entity id.

ruxit.api.snapshot module

Utilities used to facilitate interfacing with process snapshot

ruxit.api.snapshot.python_module(module_name)[source]

Predicate used to search process snapshot for a group containing Python module e.g: python -m http.server

Parameters:module_name -- python module name to find
ruxit.api.snapshot.command_line_regex(pattern)[source]

Predicate used to search process snapshot for a group that has process with command line matching a specified regex pattern

Parameters:pattern -- regex pattern to find.
ruxit.api.snapshot.pgi_name(name)[source]

Predicate to find process group of a given name.

Parameters:name -- name of the group
ruxit.api.snapshot.parse_port_bindings(entity)[source]

Searches entity processes for a process port bindings data

Returns:list of tuple(string of binded IP address, port integer)

Module contents