System Diagnostics

class activelogic.SysDiag

This is the resource that governs the System Diagnostics on an ActiveLogic system.

System Diagnostics are divided into different zones, where each zone defines a set of values. New zones can be registered at any time, and there is no need to commit the transaction afterwards, since system diagnostics are only saved in memory.

Values can be read in two different ways:

  1. get_aggregated_values(): Reads the top-level values from a given zone. This corresponds to the Zone View in ActiveLogic client.

  2. get_values(): Reads the value tree for a specific value from a given zone. This is the same as drilling down into the value in the Zone View in ActiveLogic client.

set_system_name() must be called before any value updates are sent.

Updates are usually sent at a regular basis, using update_values(), where each update contains a snapshot of the values at the time when they were sent.

There is a possibility to configure alerts on any value in the level tree. Changes to alerts have to be committed, since these are saved to database.

async SysDiag.list(cls, **kwargs)

Generic list function for all kind of data that belongs to this resource.

Parameters:

cls – Object type that determines what kind of data to get.

Returns:

A list of given dataclass type.

Raises:

  • ValueError – Invalid dataclass type.

  • PLDBNewDataCommitted – Conflict with new data committed by an other session.

The following data can be listed from this resource:

  • SysDiagZone: Lists all system diagnostics zones.

  • SysDiagAlert: Lists all configured alerts.

  • SysDiagLogEntry: Lists all log entries. Optional parameters are:

    • only_new (bool): Lists only new logs that have not yet been acked.

    • min_id (int): Lists logs starting from a given ID.

  • SysDiagMallocUsageZone: List all malloc usage zones.

List may or may not be cached, depending on if cache_enabled is set.

>>> sd.list(SysDiagZone)
[SysDiagZone(oid='1.3.6.1.4.1.15397.2.1.28', name='Ethernet'), ...]
>>> sd.list(SysDiagAlert)
[SysDiagAlert(zone_oid='1.3.6.1.4.1.15397.2.1.8', id=10, levels=[], min_value=11000), ...]
>>> sd.list(SysDiagLogEntry, only_new=True)
[SysDiagLogEntry(id=3, is_new=True, title='Title')]
>>> sd.list(SysDiagMallocUsageZone)
[SysDiagMallocUsageZone(systemname='Undefined', zonename='Session Context Daemon'), ...]

The result can be filtered using Python’s list comprehension syntax. For example, to list all new unacked logs:

>>> [l for l in sd.list(SysDiagLogEntry) if l.is_new]
[SysDiagLogEntry(id=3, is_new=True, title='Title')]
class activelogic.SysDiagType

Defines a set of constants for available system diagnostics types:

Variables:

  • MOMENT – Ever increasing counter of events.

  • SIZE – Current size of something.

  • SPEED – Ever increasing byte counter.

  • TIMESPAN – Time duration.

  • PERCENT – Percentage.

  • TIME – Absolute timepoint.

  • BITMASK – Bitset.

  • MEMORY – Current size of something.

  • ENUM – Number with corresponding string values.

  • UNFORMATTED – Unformatted numeric value.

  • STRING – Dynamic string value.

  • TEMPERATURE – Degrees Celcius at 1/256 resolution.

  • VOLTAGE – Volts at 1e-4 resolution.

  • CURRENT – Milliamperes at 2e-3 resolution.

  • POWER – Milliwatts at 1e-4 resolution.

class activelogic.SysDiagZone

Object representing a system diagnostics zone.

Parameters:

  • oid (str) – Zone oid.

  • name (str) – Name of the zone.

  • functional_area (str) – Functional area of the zone.

  • valuedefs (dict) – Dictionary of value definitions.

class activelogic.SysDiagValueDefinition

Object representing a system diagnostics value definition.

Parameters:

  • name (str) – Name of the value.

  • sysdiag_type (SysDiagType) – Value type.

  • flags (int) – Behavioural value flags, read-only.

class activelogic.SysDiagValue

Object representing a system diagnostics value.

Parameters:

  • id (int) – Value id.

  • level_names (list) – Value level.

  • systemid (str) – Value systemid, if any.

  • value (int) – Numeric value.

  • raw_value (int) – Raw numeric value before reset.

  • rate (int) – Value rate, if value definition supports rates.

  • min_value (int) – Minimum value seen.

  • min_timestamp_epoch (int) – Epoch/Unix timestamp when minimum value was seen.

  • min_timestamp (datetime) – Date/time in UTC when minimum value was seen.

  • max_value (int) – Maximum value seen.

  • max_timestamp_epoch (int) – Epoch/Unix timestamp when maximum value was seen.

  • max_timestamp (datetime) – Date/time in UTC when maximum value was seen.

  • string_value (str) – String representation of value.

  • alert_flags (SysDiagAlertFlag) – Alert flags.

class activelogic.SysDiagAggregatedValue

Object representing an aggregated (top-level) system diagnostics value.

Parameters:

  • id (int) – Value id.

  • value (int) – Numeric value.

  • raw_value (int) – Raw numeric value before reset.

  • rate (int) – Value rate, if value definition supports rates.

  • min_value (int) – Minimum value seen.

  • min_timestamp_epoch (int) – Epoch/Unix timestamp when minimum value was seen.

  • min_timestamp (datetime) – Date/time in UTC when minimum value was seen.

  • max_value (int) – Maximum value seen.

  • max_timestamp_epoch (int) – Epoch/Unix timestamp when maximum value was seen.

  • max_timestamp (datetime) – Date/time in UTC when maximum value was seen.

  • string_value (str) – String representation of value.

  • alert_flags (SysDiagAlertFlag) – Alert flags.

class activelogic.SysDiagAlertFlag

Defines a set of flags that tells if a value crosses any limits.

Variables:

  • NONE – Value crosses no limits.

  • MIN – Value crosses a min_value limit.

  • MAX – Value crosses a max_value limit.

  • MIN_RATE – Rate crosses a min_rate limit.

  • MAX_RATE – Rate crosses a max_rate limit.

Reading Values and Zones

async SysDiag.get_aggregated_values(zone_oid)

Retreives all aggregated (top-level) values for a given zone.

Parameters:

zone_oid (SysDiagZone or str) – The zone or oid of the zone to get values from.

Raises:

KeyError – The zone oid was not found.

Returns:

A list of SysDiagAggregatedValue

>>> sd.get_aggregated_values("1.3.6.1.4.1.15397.2.1.133")
[SysDiagAggregatedValue(id=1, value=23, ...), SysDiagAggregatedValue(id=2, value=1996427264, ...), ...
async SysDiag.get_values(zone_oid, value_id)

Retreives the value tree for a value within a given zone.

Parameters:

  • zone_oid (SysDiagZone or str) – The zone or oid of the zone where the value belongs.

  • value_id (int) – The id of the value from which to get the value tree.

Raises:

  • KeyError – Zone oid was not found.

  • PLDBError – Zone oid does not contain given value id.

Returns:

A list of SysDiagValue

>>> sd.get_values("1.3.6.1.4.1.15397.2.1.133", 1)
[SysDiagValue(id=1, level_names=['CPU load'], ...), SysDiagValue(id=1, level_names=['CPU load', '001122334455'], ...),  ...]

Updating Values

async SysDiag.set_system_name(systemid, name)

Sets the systemid and name used for updating zone values.

Parameters:

  • systemid (str) – System id used for updating zone values.

  • name (str) – System name used for updating zone values.

async SysDiag.update_values(zone_oid, elapsed_ms, values, levels)

Sends value updates to a given zone at a certain level.

Parameters:

  • zone_oid (SysDiagZone or str) – The zone or oid of the zone where the value belongs.

  • elapsed_ms (int) – Elapsed time since last update, in milliseconds.

  • values (dict) – Dictionary of values to send.

  • levels (list) – Level where each item represents a sublevel in the tree.

Raises:

  • KeyError – The zone oid was not found or the zone does not contain the value id.

  • PLDBError – Failed to update values

set_system_name() must be called before this method can be used.

Separate updates are sent for each level.

Values are passed as a dictionary of { id: value, id: value, … }, where id is the value id and value is an integer. If the value definition that corresponds to id is a SysDiagType.STRING, value should be a string.

The following example uses the zone that was created in example under Zone Registration:

sd = await async_conn.sysdiag()

await sd.set_system_name(systemid="001122334455", name="My system")

for i in range(10):
            updated_values = {
                        0: i,  # Value 0
                        1: 5,  # Value 1
                        2: 1,  # Enum
                        3: "Update %d" % i # String
            }

            await sd.update_values(oid, 5000, updated_values, ['Level1'])
            await asyncio.sleep(5)
async SysDiag.reset_value(zone_oid, value_id, levels)

Resets the value of a specific level and the id within a given zone. Only values that actually contain values can be reset.

Parameters:

  • zone_oid (SysDiagZone or str) – The zone or oid of the zone in which to reset the value.

  • value_id (int) – The id of the value to reset.

  • levels (list) – Level where each item represents a sublevel in the tree.

Raises:

  • KeyError – The zone oid was not found or zone does not contain the value id.

  • PLDBError – Failed to reset zone value

Only MOMENT and SPEED values can be reset.

>>> sd.reset_value("1.3.6.1.4.1.15397.2.1.299", 2, ["My system", "level1", "level2"])
async SysDiag.remove_level(zone_oid, levels)

Removes a level for a given zone.

Parameters:

  • zone_oid (SysDiagZone or str) – The zone or oid of the zone from which to remove the level.

  • levels (list) – Level where each item represents a sublevel in the tree.

Raises:

  • KeyError – The zone oid was not found.

  • PLDBError – Failed to remove the level

set_system_name() must be called before this method can be used. Only levels created in the current session can be removed.

>>> sd.remove_level("1.3.6.1.4.1.15397.2.1.299", ["level1", "level2"])

Zone Registration

async SysDiag.register_zone(oid, name, valuedefs, functional_area='', debug_ids=None)

Registers a new zone.

Parameters:

  • oid (str) – Zone oid.

  • name (str) – Name of the zone.

  • valuedefs (dict) – Dictionary of value definitions.

  • functional_area (str) – Functional area of the zone.

  • debug_ids (list) – List containing ids of the values that should be flagged as debug values (hidden in AL Client).

Raises:

  • ValueError – Value id exceeds maximum number of allowed ids.

  • ValueError – Incomplete value definitions.

  • PLDBError – Failed to register zone.

Value definitions are passed as a dictionary of { id: valuedef, id: valuedef }, where id is the value id and valuedef is ( name, type ).

If type is SysDiagType.ENUM, valuedef also should contain enum values and description as a dict: ( name, type, { val0: desc0, val1: desc1 }).

await sd = conn.sysdiag()

await sd.set_system_name(systemid="001122334455", name="My system")

vdefs = {
    0: ("Value 0", SysDiagType.MOMENT),
    1: ("Value 1", SysDiagType.SPEED),
    2: ("Enum", SysDiagType.ENUM, {0: "First", 1: "Second", 2: "Third"}),
    3: ("String", SysDiagType.STRING)
}

await sd.register_zone(oid, "My zone", vdefs, "Demo zones")
async SysDiag.enum_names(zone_oid)

Retreives all enum names for a given zone.

Parameters:

zone_oid (SysDiagZone or str) – The zone or oid of the zone from which to get values.

Raises:

KeyError – The zone oid was not found.

Returns:

A dict of {id: names}

>>> sd.enum_names("1.3.6.1.4.1.15397.2.1.299")
{1: {0: 'First', 1: 'Second', 2: 'Third'}}

Alerts

class activelogic.SysDiagAlert

Object representing a set of limits for a system diagnostics value.

Parameters:

  • zone_oid (str) – Oid of the zone that contains the value.

  • id (int) – Value id.

  • levels (list) – Level to trigger on.

  • min_value (int) – Minimum value required to trigger the alert.

  • max_value (int) – Maximum value required to trigger the alert.

  • min_rate (int) – Mininum rate required to trigger the alert.

  • max_rate (int) – Maximum rate required to trigger the alert.

  • comment (str) – Alert comment or description.

  • trigger (str) – Trigger script to run when the first alert criteria is met.

  • severity (SysDiagAlertSeverity) – Severity level of alert.

  • stable_time (int) – Stable time in seconds required to trigger the alert.

class activelogic.SysDiagAlertSeverity

Defines a set of constants for available sysdiag alert severity levels:

Variables:

  • INVALID – Invalid level.

  • CLEARED – Cleared level.

  • INDETERMINATE – Indeterminate level.

  • CRITICAL – Critical level.

  • MAJOR – Major level.

  • MINOR – Minor level.

  • WARNING – Warning level.

async SysDiag.update_alert(zone_oid, value_id, levels=None, min_value=- 1, max_value=- 1, min_rate=- 1, max_rate=- 1, comment=None, trigger=None, severity=SysDiagAlertSeverity.INDETERMINATE, stabletime=0)

Creates, updates or removes an alert.

Parameters:

  • zone_oid (SysDiagZone or str) – The zone or oid of the zone where the value belongs.

  • value_id (int) – The id of the value to alert on.

  • levels (list) – Level where each item represents a sublevel in the tree.

  • min_value (int) – Minimum value.

  • max_value (int) – Maximum value.

  • min_rate (int) – Minimum rate.

  • max_rate (int) – Maximum rate.

  • comment (str) – Comment or description.

  • trigger (str) – Trigger script to run when the first alert criteria is met.

  • severity (SysDiagAlertSeverity) – Severity level of alert.

  • stabletime (int) – Time in seconds required to trigger the alert.

Raises:

  • KeyError – Zone oid is not found or does not contain given value id.

  • PLDBError – Failed to update alert.

Calling this method with just zone_oid, value_id and levels will remove the alert. Otherwise the alert will be updated with the parameters that are given. Omitted numeric limitations will be cleared.

Changes to alerts have to be committed to take effect.

>>> sd.update_alert("1.3.6.1.4.1.15397.2.1.299", 10, min_value=300)

Log

class activelogic.SysDiagLogEntrySeverity

Defines a set of constants for available sysdiag log severity levels:

Variables:

  • INFO – Information level.

  • WARNING – Warning level.

  • CRITICAL – Critical level.

class activelogic.SysDiagLogEntry

Object representing an sysdiag log entry.

Parameters:

  • id (int) – Id.

  • system (str) – Name of system.

  • systemid (str) – System id.

  • tstamp (datetime) – Timestamp of entry.

  • is_new (bool) – Indicates if this entry is acked or not.

  • severity (SysDiagLogEntrySeverity) – Severity level of entry.

  • title (str) – Title of entry. A short summary.

  • body (str) – Body of entry. The full log entry.

async SysDiag.log_post(title, body, severity=SysDiagLogEntrySeverity.INFO)

Post a system diagnostics log

Parameters:

  • title (str) – Title of log.

  • body (str) – Body of the log.

  • severity (SysDiagLogEntrySeverity) – Severity of the log.

Raises:

PLDBError – Failed to post log.

set_system_name() must be called before this method can be used.

async SysDiag.log_ack(event_id)

Ack a system diagnostics log event

Parameters:

event_id (int) – Id of event to ack

async SysDiag.log_clear()

Clear all system diagnostics log events

Malloc Statistics

class activelogic.SysDiagMallocUsageZone

Object representing a system diagnostics malloc usage zone.

Parameters:

  • systemname (str) – Name of the system where the zone is collected from.

  • zonename (str) – Zone name.

class activelogic.SysDiagMallocUsageValue

Object representing malloc usage statistics for one value.

Parameters:

  • name (str) – Name of the value.

  • cur_bytes (int) – Number of currently allocated bytes.

  • tot_allocs (int) – Total number of allocations ever done.

  • cur_allocs (int) – Number of allocations currently in use.

async SysDiag.malloc_usage_get(zone)

Retreives the malloc usage statistics for a given (systemname, zonename) or zone.

Parameters:

zone (tuple or SysDiagMallocUsageZone) – The zone to get values from.

Raises:

  • TypeError – Zone is of incorrect type.

  • ValueError – Given zone does not exist.

Returns:

A list of SysDiagMallocUsageValue

>>> z = [z for z in sd.list(SysDiagMallocUsageZone) if z.zonename == "Database Daemon"][0]
>>> sd.malloc_usage_get(z)
[('pl_ringbuf_chunk_t', 19401098, 74, 74), ('MEMPOOL: pl_msg_t', 8392992, 2, 2), ... ]