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)

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 -- ruxit.package_utils.plugin_updater.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 -- ruxit.entity_resolver.EntityResolver exposes additional methods for querying snapshot
  • logger -- plugin: specific logger for plugin development, set to None only in unit tests
class AgentVersion(major, minor, revision, build)

Bases: tuple

Create new instance of AgentVersion(major, minor, revision, build)

build
major
minor
revision
BasePlugin.agent_version

return -- Agent version as AgentVersion = NamedTuple('AgentVersion', [('major', int), ('minor', int), ('revision', int), ('build', str)])

BasePlugin.close(**kwargs)

Abstract method called when plugin is deactivated.

Parameters:**kwargs -- see BasePlugin for keyword args reference
BasePlugin.find_all_process_groups(predicate)

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
BasePlugin.find_all_processes(process_predicate)

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 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
BasePlugin.find_single_process(process_predicate)

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, an exception is raised. Only processes of types associated with plugin are searched.

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

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:list of process snapshot entries
BasePlugin.get_monitored_entities(me_type=None) → typing.List[]

Gets the list of MonitoredEntities related to the plugin based on the entity type defined in plugin.json or given type as argument. By default, the type is taken from plugin.json - entity field. If a type other than the type defined in the entity field is required, the me_type must be given as an argument. A typical example is the plugin reporting most data on the process group instance level, where the entity is PROCESS_GROUP_INSTANCE, but some metrics are on the process group (cluster) level. Then the me_type PROCESS_GROUP should be given as an argument and the corresponding group ID will be returned.

Parameters:me_type -- optional monitored entity type. One of: process, group, host
Returns:MonitoredEntity object containing: id, type, snapshot_entry
BasePlugin.initialize(**kwargs)

Abstract method for custom plugin initialization. Called after __init__. Override if additional initialization (for example, acquiring connections once instead of on every query method execution) is needed.

Parameters:**kwargs -- see BasePlugin for keyword args reference
BasePlugin.query(**kwargs)

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

Parameters:**kwargs -- see BasePlugin for keyword args reference
class ruxit.api.base_plugin.ExternalFunctions(agent_version)

Bases: tuple

Create new instance of ExternalFunctions(agent_version,)

agent_version
class ruxit.api.base_plugin.MonitoredEntities(result_builder, activation_context, plugin_info)

Bases: object

MonitoredEntities class for plugins provides the list of MonitoredEntity objects related to the activation context. Each MonitoredEntity contains such properties as: ID, type, snapshot and all the methods for sending plugin data.

get(snapshot_complete, me_type: ruxit.api.selectors.EntityType = None) → typing.List[]
class ruxit.api.base_plugin.MonitoredEntity(result_builder, id, type, snapshot)

Bases: object

MonitoredEntity class for plugins.

absolute(key, value, dimensions=None)

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

Parameters:
  • key -- metric key.
  • value -- metric value
  • dimensions -- optional dictionary of 2 strings {'key', 'value'}
event_availability(description: str = None, title: str = None, properties: typing.Dict[] = {})

Reports an availability event.

Parameters:
  • description -- default None, Event description as string of max 10240 characters long.
  • title -- Event title as string of max 1024 characters long.
  • properties -- Event properties as dictionary of 2 strings. Max key length is 100 characters, max value length is 1000 characters. Max number of elements in the dictionary is 100.
event_custom_annotation(description: str = None, annotation_type: str = None, source: str = None, properties: typing.Dict[] = {})

Reports a custom annotation event.

Parameters:
  • description -- Event description as string of max 10240 characters long.
  • annotation_type -- Event annotation_type as string of max 10240 characters long.
  • source -- Event source as string of max 10240 characters long.
  • properties -- Event properties as dictionary of 2 strings. Max key length is 100 characters, max value length is 1000 characters. Max number of elements in the dictionary is 100.
event_custom_deployment(source: str = None, project: str = None, version: str = None, ci_link: str = None, remediation_action_link: str = None, deployment_name: str = None, properties: typing.Dict[] = {})

Reports a custom deployment event.

Parameters:
  • source -- Event source as string of max 10240 characters long.
  • project -- Event project as string of max 10240 characters long.
  • version -- Event version as string of max 10240 characters long.
  • ci_link -- Event link as string of max 10240 characters long.
  • remediation_action_link -- Event remediation action link as string of max 10240 characters long.
  • deployment_name -- Event deployment name as string of max 10240 characters long.
  • properties -- Event properties as dictionary of 2 strings. Max key length is 100 characters, max value length is 1000 characters. Max number of elements in the dictionary is 100.
event_custom_info(description: str = None, title: str = None, properties: typing.Dict[] = {})

Reports a custom info event.

Parameters:
  • description -- default None, Event description as string of max 10240 characters long.
  • title -- Event title as string of max 1024 characters long.
  • properties -- Event properties as dictionary of 2 strings. Max key length is 100 characters, max value length is 1000 characters. Max number of elements in the dictionary is 100.
event_error(description: str = None, title: str = None, properties: typing.Dict[] = {})

Reports an error event.

Parameters:
  • description -- default None, Event description as string of max 10240 characters long.
  • title -- Event title as string of max 1024 characters long.
  • properties -- Event properties as dictionary of 2 strings. Max key length is 100 characters, max value length is 1000 characters. Max number of elements in the dictionary is 100.
event_performance(description: str = None, title: str = None, properties: typing.Dict[] = {})

Reports a performance event.

Parameters:
  • description -- default None, Event description as string of max 10240 characters long.
  • title -- Event title as string of max 1024 characters long.
  • properties -- Event properties as dictionary of 2 strings. Max key length is 100 characters, max value length is 1000 characters. Max number of elements in the dictionary is 100.
event_resource_contention(description: str = None, title: str = None, properties: typing.Dict[] = {})

Reports a resource contention event.

Parameters:
  • description -- default None, Event description as string of max 10240 characters long.
  • title -- Event title as string of max 1024 characters long.
  • properties -- Event properties as dictionary of 2 strings. Max key length is 100 characters, max value length is 1000 characters. Max number of elements in the dictionary is 100.
id

The identifier of the monitored entity. :return: str

per_second(key, value, dimensions=None)

Adds per second result. Use for metrics that increase monotonically (such as counters) After gathering the second result, the difference between the current and previous results is 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 the measurements, nothing is sent.

Parameters:
  • key -- metric key.
  • value -- metric value
  • dimensions -- optional dictionary of two strings {'key', 'value'}
process_name

Name of the process group. This is assigned in a manner specific to each process type. :return:

property(key, value)

Adds entity property. PluginProperty object is constructed implicitly in the method.

Parameters:
  • key -- key of the measurement. Must be a string.
  • value -- value of the measurement. Must be convertible to float.
relative(key, value, dimensions=None)

Adds a relative result. Use for metrics that increase monotonically (such as counters) After gathering the second result, the difference between the current and previous results is sent to the server (if it is non-negative). If there is a negative difference between measurements, nothing is sent.

Parameters:
  • key -- metric key.
  • value -- metric value
  • dimensions -- optional dictionary of two strings {'key', 'value'}
snapshot

Process snapshot containing all processes related to the activation context. :return: List of ProcessGroupInstance

state_metric(key, value, dimensions=None)

Adds state metric. PluginStateMetric object is constructed implicitly in the method.

Parameters:
  • 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.
type

The type of the monitored entity. Possible values -- EntityType.HOST, EntityType.PROCESS_GROUP_INSTANCE, EntityType.PROCESS_GROUP :return:

class ruxit.api.base_plugin.ProcessGroupInstance

Bases: tuple

Contains information about a single process group. It contains the entity of the group that should be used to report measurements associated with processes in the group.

Create new instance of ProcessGroupInstance(group_id, node_id, group_instance_id, process_type, group_name, processes, properties)

group_id
group_instance_id
group_name
node_id
process_type
processes
properties
technologies

Technologies recognized for the process, often used for plugin activation. Please refer to Plugin.json reference for the full list of available technologies. :return: List of strings.

class ruxit.api.base_plugin.ProcessInfo(pid, name, properties)

Bases: tuple

Create new instance of ProcessInfo(pid, name, properties)

name
pid
properties
class ruxit.api.base_plugin.RemoteBasePlugin(**kwargs)

Bases: ruxit.api.base_plugin.BasePlugin

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[] = {}, entity_selector=FromPluginSelector())

Bases: object

PID_KEY = 'rx_pid'
dimensions

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

dimensions_keys_tuple
key

Key of the measurement. Must be a string.

value

Value of the measurement. Must be convertible to float.

class ruxit.api.data.MEAttribute

Bases: enum.IntEnum

Enumerates types of properties to report.

CONTRIBUTED_NAME = <MEAttribute.CONTRIBUTED_NAME: 4>
CUSTOM_DEVICE_METADATA = <MEAttribute.CUSTOM_DEVICE_METADATA: 6>
CUSTOM_HOST_METADATA = <MEAttribute.CUSTOM_HOST_METADATA: 7>
CUSTOM_PG_METADATA = <MEAttribute.CUSTOM_PG_METADATA: 5>
DOCKER_CONTAINER_PROPS = <MEAttribute.DOCKER_CONTAINER_PROPS: 2>
INTERNAL_DEBUG_PROPERTY = <MEAttribute.INTERNAL_DEBUG_PROPERTY: 1>
PROCESS_GROUP_TECHS = <MEAttribute.PROCESS_GROUP_TECHS: 3>
class ruxit.api.data.PluginMeasurement(key: str, value: float, dimensions: typing.Dict[] = None, entity_selector=FromPluginSelector())

Bases: ruxit.api.data.BaseMetric

Single plugin measurement.

Use of this class is optional. ResultsBuilder exposes methods that handle 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.PluginMeasurementList(timestamp=None, measurements=None)

Bases: object

Collection of PluginMeasurements. Used internally.

class ruxit.api.data.PluginMeasurementStorage(topx_data: typing.Dict[] = {})

Bases: object

MAX_DIMENSIONS_PER_METRIC = 1000
clear_results_only()
flush()
items() → typing.List[]
load(pm: ruxit.api.data.PluginMeasurement) → ruxit.api.data.PluginMeasurement
overflow_info
size
store(pm: ruxit.api.data.PluginMeasurement) → bool
topx_overflow
class ruxit.api.data.PluginMeasurementV3(*args, **kwargs)

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.PluginProperty(key=None, value=None, entity_selector=FromPluginSelector(), me_attribute=<MEAttribute.INTERNAL_DEBUG_PROPERTY: 1>)

Bases: object

A text property a plugin can gather.

Parameters:
  • key -- str: property key
  • value -- str: property value
  • entity_selector -- plugin's entity selector FromPluginSelector by default
  • me_attribute(MEAttribute) -- property type
classmethod is_allowed_for_pa(attribute: ruxit.api.data.MEAttribute) → bool
Returns:true if property with attribute could be directly created from custom plugin (PA case)
classmethod is_custom(attribute: ruxit.api.data.MEAttribute) → bool
Returns:true if property attribute is a custom property (with limits)
key

Key of property.

me_attribute

Property type

value

Value of property

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

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.

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

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

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

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.topology_builder module

TopologyBuilder module provides an API for the plugins to send the information about the topology.

class ruxit.api.topology_builder.MetricSink(results_builder: ruxit.api.results_builder.ResultsBuilder)

Bases: object

absolute(key: str, value: float, dimensions: typing.Dict[] = None)

Reports an absolute value for a metric, for a given Device or Group entity.

Parameters:
  • key -- The metric key.
  • value -- The metric value to send
  • dimensions -- An optional dictionary of pairs (dimension key, dimension value)
Example:
>>> e = g.create_device(...)
>>> e.absolute('my_metric_key', 42)
>>> e.absolute('my_metric_key_with_dim', 42, {'my_dim': 'my_dim_val'})
relative(key: str, value: float, dimensions: typing.Dict[] = None)

Reports a relative value for a metric, for a given Device or Group entity.

Parameters:
  • key -- The metric key.
  • value -- The metric value to send
  • dimensions -- An optional dictionary of pairs (dimension key, dimension value)
Example:
>>> e = g.create_device(...)
>>> e.relative('my_metric_key', 42)
>>> e.relative('my_metric_key_with_dim', 42, {'my_dim': 'my_dim_val'})
per_second(key: str, value: float, dimensions: typing.Dict[] = None)

Adds per second result. Use for metrics that increase monotonically (such as counters). After gathering the second result, the difference between the current and previous results is 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:
  • key -- The metric key.
  • value -- The metric value to send
  • dimensions -- An optional dictionary of pairs (dimension key, dimension value)
Example:
>>> e = g.create_device(...)
>>> e.per_second('my_metric_key', 42)
>>> e.per_second('my_metric_key_with_dim', 42, {'my_dim': 'my_dim_val'})
report_property(key: str, value: str)

Reports a custom property for an entity property.

Parameters:
  • key -- Property key as string.
  • value -- Property value as string.
Example:
>>> e = e.report_property("my_prop", "my_prop_val")
state_metric(key: str, value: str, dimensions: typing.Dict[] = None)

Reports a state metric.

Parameters:
  • key -- Mandatory state metric name as string.
  • value -- Mandatory state metric value as string.
  • dimensions -- optional metric dimensions as dictionary of 2 strings.
class ruxit.api.topology_builder.Device(name: str, entity_id: int, technology: str, results_builder: ruxit.api.results_builder.ResultsBuilder) → None

Bases: ruxit.api.topology_builder.MetricSink

Class used to store device data reported from the plugin. For the reference of the metric API, see the base class.

add_endpoint(ip: str, port: int = None, dnsNames: typing.List[] = None, port_list: typing.List[] = None, range_list: typing.List[] = None) → None

Add an endpoint to the Device. Total number of ports cannot exceed 100. Adding more ports causes ConfigException. :param ip: Valid IP address as string :param port: Optional single port number :param dnsNames: Optional list of domains bound to the address as a list of strings :param port_list: Optional list of port numbers :param range_list: Optional list of tuples with (range_from, range_to) numbers in range (1, 65535) :raises ConfigException: :return:

Example:
>>> add_endpoint(ip="1.1.1.1")
>>> add_endpoint(ip="1.1.1.1", port=80)
>>> add_endpoint(ip="1.1.1.1", port=80, dnsNames=["name.com"])
>>> add_endpoint(ip="1.1.1.1", port=80, dnsNames=["name.com"], port_list=[88,8080], range_list=[(680, 690), (880, 900)])
>>> add_endpoint(ip="1.1.1.1", port=None, dnsNames=["name.com"], port_list=None, range_list=[(80, 88), (447, 450)])
report_performance_event(description: str = None, title: str = None, properties: typing.Dict[] = {})

Reports a performance event.

Parameters:
  • description -- Event description as string (default = None, max length = 10240 characters).
  • title -- Event title as string (max length = 10240 characters).
  • properties -- Event properties as dictionary of two strings (max key length = 100 characters, max value length = 1000 characters, max number of elements in dictionary = 100).
report_error_event(description: str = None, title: str = None, properties: typing.Dict[] = {})

Reports an error event.

Parameters:
  • description -- default None, Event description as string (default = None, max length = 10240 characters).
  • title -- Event title as string (max length = 10240 characters).
  • properties -- Event properties as dictionary of 2 strings (max key length = 100 characters, max value length = 1000 characters, max number of elements in dictionary = 100).
report_availability_event(description: str = None, title: str = None, properties: typing.Dict[] = {})

Reports an availability event.

Parameters:
  • description -- default None, Event description as string (default = None, max length = 10240 characters).
  • title -- Event title as string (max length = 10240 characters).
  • properties -- Event properties as dictionary of 2 strings (max key length = 100 characters, max value length = 1000 characters, max number of elements in dictionary = 100).
report_resource_contention_event(description: str = None, title: str = None, properties: typing.Dict[] = {})

Reports a resource contention event.

Parameters:
  • description -- default None, Event description as string (default = None, max length = 10240 characters).
  • title -- Event title as string (max length = 10240 characters).
  • properties -- Event properties as dictionary of 2 strings. (max key length = 100 characters, max value length = 1000 characters, max number of elements in dictionary = 100).
report_custom_info_event(description: str = None, title: str = None, properties: typing.Dict[] = {})

Reports a custom info event.

Parameters:
  • description -- default None, Event description as string of (default = None, max length = 10240 characters).
  • title -- Event title as string (max length = 10240 characters).
  • properties -- Event properties as dictionary of 2 strings. (max key length = 100 characters, max value length = 1000 characters, max number of elements in dictionary = 100).
report_custom_deployment_event(source: str = None, project: str = None, version: str = None, ci_link: str = None, remediation_action_link: str = None, deployment_name: str = None, properties: typing.Dict[] = {})

Reports a custom deployment event.

Parameters:
  • source -- Event source as string (max length = 10240 characters).
  • project -- Event project as string (max length = 10240 characters).
  • version -- Event version as string (max length = 10240 characters).
  • ci_link -- Event link as string (max length = 10240 characters).
  • remediation_action_link -- Event remediation action link as string (max length = 10240 characters).
  • deployment_name -- Event deployment name as string (max length = 10240 characters).
  • properties -- Event properties as dictionary of 2 strings. Max key length is 100 characters, max value length is 1000 characters. Max number of elements in the dictionary is 100.
report_custom_annotation_event(description: str = None, annotation_type: str = None, source: str = None, properties: typing.Dict[] = {})

Reports a custom annotation event.

Parameters:
  • description -- Event description as string (max length = 10240 characters).
  • annotation_type -- Event annotation_type as string (max length = 10240 characters).
  • source -- Event source as string (max length = 10240 characters).
  • properties -- Event properties as dictionary of 2 strings. Max key length is 100 characters, max value length is 1000 characters. Max number of elements in the dictionary is 100.
class ruxit.api.topology_builder.Group(entity_id: int, name: str, technologies: typing.List[], results_builder: ruxit.api.results_builder.ResultsBuilder) → None

Bases: ruxit.api.topology_builder.MetricSink

Class used to store group data reported from the plugin. For the reference of the metric API, see the base class.

create_device(identifier: str, display_name: str = None) → ruxit.api.topology_builder.Device

Adds a new device to the device group. Also calculates its unique ID based on identifier. This method is available since ver. 159.

Parameters:
  • identifier -- String parameter used for unique device ID calculation. To create two different devices, you need to provide two different identifiers.
  • display_name -- Optional string to define the device display name. If not provided, the identifier parameter will be used instead.
Returns:

The created device object.

Example:
>>> grp = self.topology_builder.create_group("my_group_id", "my_group_name")
>>> device = grp.create_device("my_device_id", "my_device_name")
create_element(identifier: str, element_name: str) → ruxit.api.topology_builder.Device

Adds a new element to the reported topology. Also calculates its ID based on element name and identifier.

This method is deprecated since ver. 159 and will be removed. use create_device() instead.

Parameters:
  • element_name -- The name of the entity.
  • identifier -- Identifier used for element id calculation.
Returns:

The created element object.

Example:
>>> grp = self.topology_builder.create_group("my_group_id", "my_group_name")
>>> elem = grp.create_element("my_elem_id", "my_elem_name")
class ruxit.api.topology_builder.Topology(group, config_id)

Bases: tuple

Create new instance of Topology(group, config_id)

config_id
group
class ruxit.api.topology_builder.TopologyBuilder(config_id: int, plugin_name: str, tenant_id: str, technologies: typing.List[], results_builder: ruxit.api.results_builder.ResultsBuilder)

Bases: object

Class storing topology data reported by plugins.

create_group(identifier: str, group_name: str) → ruxit.api.topology_builder.Group

Creates a new group to the reported topology. Also calculates its ID based on identifier and group name.

Parameters:
  • identifier -- Mandatory identifier used for group ID calculation.
  • group_name -- Mandatory name of the group.
Returns:

The created group object.

Module contents