Monitoring module "diagnostics"

Description

The task of the "diagnostics" monitoring module is to monitor different types of input data with regard to defined criteria and then write the resulting alarm information to the smartCORE alarm database.

As a result, this database can be used for further processing of the alarm messages, such as transmission to the cloud.

The types of monitored input data include, among others

Boolean channels
Integer channels with (enumerated) (error) value range
Analog channels with measured values
Two-channel combinations (error streams) consisting of error code and error level

In addition, current values from smartCORE channels are recorded as part of the compilation of alarm messages (so-called snapshots) and user-defined metadata is integrated.

Interfaces & protocols used

smartCORE alarm database

JSON configuration

The following sections list sample configurations and discuss the module parameters involved.

Example configuration (monitoring a Boolean channel)

In this example, a Boolean channel is monitored for the value true.

{
  "module": "diagnostics",
  "factory": "diagnostics",
  "config": {
    "activationMode": "channelvalues",
    "pollingIntervalMs": 1000,
    "messages": [
      {
        "messageLevel": "WARNING",
        "context": "Some WARNING occurred",
        "channel": "someBooleanChannel",
        "activation": "high"
      }
    ]
  }
}

Example configuration (monitoring the exceeding of a channel value with stabilization delays and hysteresis)

In this example, an integer or floating point channel is monitored for exceeding the value of 42.0. In the example, it is necessary for the overshoot to last for at least 5 seconds in order to be triggered or for deactivation that it does not occur for at least 10 seconds and that the value of the channel is below the threshold value minus its hysteresis.

An event-related message is also generated that contains the current value, the previous extremum, i.e. maximum in this case, and the threshold value.

This message is updated both when the value is initially exceeded and when it is deactivated. In addition, this message is also updated if the current value deviates from the last reported extremum by more than the hysteresis.

{
  "module": "diagnostics",
  "factory": "diagnostics",
  "config": {
    "activationMode": "channelvalues",
    "pollingIntervalMs": 1000,
    "messages": [
      {
        "messageLevel": "WARNING",
        "context": "Some WARNING occurred",
        "messageEvent": "Some WARNING occurred (current value ${value} > ${boundary}) (maximum value ${minmax} on ${minmaxDate} at ${minmaxTime})",
        "channel": "someValueChannel",
        "boundary": 42.0,
        "hysteresis": 7.0,
        "activation": "high",
        "stabilizationSecondsRaise": 5,
        "stabilizationSecondsRelease": 10,
      }
    ]
  }
}

Example configuration (monitoring of enumerated channel values)

In this example, an integer channel is monitored, whereby the value ranges (17, 77-99) are interpreted as trigger conditions, the value ranges (31-39, 66, 69-71) as deactivation conditions and all other ranges as invalid alarm conditions.

{
  "module": "diagnostics",
  "factory": "diagnostics",
  "config": {
    "activationMode": "channelvalues",
    "pollingIntervalMs": 1000,
    "messages": [
      {
        "messageLevel": "WARNING",
        "context": "Some WARNING occurred",
        "messageEvent": "Some WARNING occurred",
        "messageFailure": "INVALID error occurred",
        "channel": "someEnumeratedChannel",
        "activation": "enum",
        "valuesHigh": "17.77-99",
        "valuesLow": "31-39,66,69-71"
      }
    ]
  }
}

Example configuration (monitoring an error stream)

In this example, a so-called error stream is monitored. This consists of the two sourceErrorCode and sourceErrorLevel channels, which must be synchronized in time. Both integer and string error code channels are supported, whereas the error level channel must contain integer values.

In the example, both the user-specified error code "47:11" and all unknown error codes are monitored.

{
  "module": "diagnostics",
  "factory": "diagnostics",
  "config": {
    "activationMode": "errorstream",
    "pollingIntervalMs": 1000,
    "sourceErrorCode": "Some.Name.Space.ErrorCodeChannel",
    "sourceErrorLevel": "Some.Name.Space.ErrorLevelChannel",
    "messages": [
      {
        "errorCode": "47:11",
        "messageLevel": "WARNING",
        "context": "WARNING ${errorCode} occurred",
        "messageEvent": "WARNING ${errorCode} occurred"
      },
      {
        "isTemplate": true,
        "messageLevel": "WARNING",
        "context": "UNKNOWN WARNING ${errorCode} occurred",
        "messageEvent": "UNKNOWN WARNING ${errorCode} occurred"
      }
    ]
  }
}

Example configuration (monitoring of a Boolean channel, use of metadata)

In this example, a Boolean channel is monitored for the value true. The aim of this example is to illustrate the addition of user-specific metadata to alarm messages.

Metadata in the form of a JSON object is added for this purpose as part of the compilation of the alarm message, whereby the global metadata is always supplemented by the metadata specified in the message or replaced at the top level of the JSON object.

{
  "module": "diagnostics",
  "factory": "diagnostics",
  "config": {
    "activationMode": "channelvalues",
    "pollingIntervalMs": 1000,
    "globalMetadata": {
      "actionToBePerformed": "some action",
      "consequences":[
        "consequence1",
        "consequence2"
      ]
    },
    "messages": [
      {
        "messageLevel": "WARNING",
        "context": "Some WARNING occurred",
        "channel": "someBooleanChannel",
        "boundary": 0,
        "activation": "high",
        "metadata": {
          "actionToBePerformed": "some CRITICAL action",
          "consequences":[
            "some SEVERE consequence",
            "consequence1",
            "consequence2"
          ],
          "additionalRemarks":[
            "some REMARK"
          ]
        }
      }
    ]
  }
}

Example configuration (monitoring of a Boolean channel, use of snapshot channels)

In this example, a Boolean channel is monitored for the value true. The aim of this example is to illustrate the addition of a user-specified snapshot of channel values to alarm messages.

For this purpose, a snapshot of various smartCORE channels is taken at the time of the initial occurrence of the alarm condition, which consists of the combination of all global and message-related snapshot channels.

{
  "module": "diagnostics",
  "factory": "diagnostics",
  "config": {
    "activationMode": "channelvalues",
    "pollingIntervalMs": 1000,
    "globalSnapshot": [
      "someGps.Location",
      "someOutsideTemperature"
    ]
    "messages": [
      {
        "messageLevel": "WARNING",
        "context": "Some WARNING occurred",
        "channel": "someBooleanChannel",
        "boundary": 0,
        "activation": "high",
        "snapshot": [
          "somePressure",
          "someTemperature",
          "someQuantity",
        ]
      }
    ]
  }
}

Example configuration (monitoring of a Boolean channel, use of snapshot groups)

In this example, a Boolean channel is monitored for the value true. This example also illustrates the use of so-called snapshot groups.

{
  "module": "diagnostics",
  "factory": "diagnostics",
  "config": {
    "activationMode": "channelvalues",
    "pollingIntervalMs": 1000,
    "snapshotGroups": [
      {
        "name": "gpsInfoChannels",
        "channels": [
          "GPS.Location",
          "GPS.Altitude",
          "GPS.SatCount"
        ]
      },
      {
        "name": "EngineOilPTQChannels",
        "channels": [
          "Engine.Oil.Pressure",
          "Engine.Oil.Temperature",
          "Engine.Oil.Quantity"
        ]
      }
    ],
    "globalSnapshot": [
      "gpsInfoChannels",
      "someOutsideTemperature"
    ]
    "messages": [
      {
        "messageLevel": "WARNING",
        "context": "Some WARNING occurred",
        "channel": "someBooleanChannel",
        "boundary": 0,
        "activation": "high",
        "snapshot": [
          "Engine.Revs",
          "EngineOilPTQChannels"
        ]
      }
    ]
  }
}

Global module parameters

All module parameters are discussed in the following section.

parameter name	required	data type	meaningful value range	default value	description
pollingIntervalMs	No	INT	1 -	1000 (1 s)	processing interval [ms]
globalMetadata	No	JSON Object		EMPTY JSON Object	JSON Object with any user-specified metadata
globalSnapshot	No	JSON Array of STRING		EMPTY JSON Array	JSON Array, which contains a global list of channels whose values are to be captured selectively at the time of alerting
snapshotGroups	No	JSON Array of JSON Object		EMPTY JSON Array	see below
activationMode	YES	STRING		NO default value	Activation mode, either channel value monitoring ("channelvalues") or error stream monitoring ("errorstream")
messages	YES	JSON Array of JSON Object		NO default value	see below

Global snapshot groups "snapshotGroups"

Several channels to be recorded as part of a snapshot can be configured in the form of a snapshot group as a JSON object, whose name can then be used as a channel name in the further course of the configuration. It makes sense to name these groups in such a way that existing channel names are not overwritten, as the names of these groups are first resolved into the names of their components.

parameter name	required	data type	meaningful value range	default value	description
name	YES	STRING			Name or alias of the snapshot group
channels	JA	JSON Array of STRING			List of all summarized channel names

Configuration of the "messages" alarm messages

The "messages" alarm messages are configured in the form of JSON objects and in different ways depending on the type of monitoring.

The common configuration parameters of these JSON objects are

Parameter name	Required	Data type	Sensible value range	Default value	Description
messageLevel	YES	STRING	info, action, service, warning, alarm, error, fatal	NO default value	severity of the alarm message
context	YES	STRING			Context of the alarm message
messageEvent	No	STRING			Alarm message when alarm is triggered
needAcknowledge	No	BOOLEAN	false, true	false	an acknowledgement is required on the cloud side
keepAcknowledgedStatus	No	BOOLEAN	false, true	false	should the acknowledged status be retained
stabilizationSecondsRaise	No	INTEGER	1 -	0	Stabilization delay after which the alarm is to be triggered (the initial time of the first occurrence of the alarm condition is reported)
stabilizationSecondsRelease	No	INTEGER	1 -	0	Stabilization delay after which the alarm is to be deactivated (the initial time of the first occurrence of the deactivation condition is reported)
metadata	No	JSON object		EMPTY JSON object	User-defined metadata that can potentially overwrite the global metadata
snapshot	No	JSON Array of STRING		EMPTY JSON Array	Channels to be captured during the initial occurrence of the alarm condition. The global snapshot "globalSnapshot" is combined with the snapshot groups specified and resolved here (from "snapshotGroups") and channels specified individually here.

Configuration of channel value monitoring ("activationMode" = "channelvalues")

As part of the value monitoring of a smartCORE channel, the above-mentioned configuration object is supplemented by the following parameters, whereby the following parameters must be defined for threshold value monitoring

Parameter name	Required	Data type	Sensible value range	Default value	Description
channel	YES	STRING		NO default value	Name of the monitored smartCORE channel
boundary	YES	INTEGER or FLOAT		0	Threshold value, exceeding or falling below which leads to the initial fulfillment of the alarm condition
activation	YES	STRING	low, high, minimum, maximum, positiveEdge, negativeEdge	NO default value	Type of alarm activation. ("low" => undershoot, "high" => overshoot, "minimum" => undershoot with monitoring of the minimum, "maximum" => overshoot with monitoring of the maximum, "positiveEdge" => overshoot (only initial, stateless alarming), "negativeEdge" => undershoot (only initial, stateless alarming)

In the case of range monitoring, i.e. if the value of a channel comes from an enumeration (enum), the following additional parameters can be specified.

Parameter name	Required	Data type	Sensible value range	Default value	Description
channel	YES	STRING		NO default value	Name of the monitored smartCORE channel
valuesLow	SELECTION SELECT	STRING		"0"	Specification of the value ranges corresponding to a deactivated alarm condition
valuesHigh	CHOICE	STRING		"0"	Specification of the value ranges that correspond to a triggered alarm condition
activation	YES	STRING	enum	NO default value	Type of alarm activation. Only enum makes sense in this configuration.

Either one or both of the above-mentioned value range specifications valuesLow or valuesHigh can be used here. If only one specification is used, the other corresponds to the opposite of this specification. If, on the other hand, both specifications are used, the value ranges not covered correspond to an invalid alarm condition. For this purpose, an invalid alarm message can be specified in the form of the following additional parameter

parameter name	required	data type	meaningful value range	default value	description
messageFailure	No	STRING			Alarm message if alarm condition is invalid

Configuration of channel value monitoring ("activationMode" = "errorstream")

A so-called error stream can also be monitored. This generally consists of two synchronized smartCORE channels that contain the error code on the one hand and the error level on the other.

These two channels are configured as global module parameters as follows

Parameter name	Required	Data type	Meaningful value range	Default value	Description
sourceErrorCode	YES	STRING		NO default value	smartCORE channel containing a time-variable error code
sourceErrorLevel	YES	STRING		NO default value	smartCORE channel that contains a synchronous error level

The sourceErrorCode channel is a channel that provides either integer values or strings. The sourceErrorLevel channel, on the other hand, provides integer values.

Furthermore, a neutral error level can be specified in the global module configuration as follows

parameter name	required	data type	meaningful value range	default value	description
neutralErrorCode	No	STRING		0	Neutral error level at which NO alarm is triggered

The individual alarm messages (in this case relating to different error codes) are configured as shown above. The following parameters must also be specified

parameter name	required	data type	meaningful value range	default value	description
errorCode	CHOICE	STRING			Error code monitored by this monitoring unit
isTemplate	CHOICE	BOOLEAN	false, true	false	Is this a monitoring unit for unknown error codes (wildcard)?

If errorCode is specified, the corresponding alarm message is created in response to the error code. A template, on the other hand, configures alarm messages for all unknown error codes.

Module information

Information	Value
Authors	optiMEAS Measurement and Automation Systems GmbH
since smartCORE	2.6
Module type	Consumer
Dependencies	NONE

Description​

Interfaces & protocols used​

JSON configuration​

Example configuration (monitoring a Boolean channel)​

Example configuration (monitoring the exceeding of a channel value with stabilization delays and hysteresis)​

Example configuration (monitoring of enumerated channel values)​

Example configuration (monitoring an error stream)​

Example configuration (monitoring of a Boolean channel, use of metadata)​

Example configuration (monitoring of a Boolean channel, use of snapshot channels)​

Example configuration (monitoring of a Boolean channel, use of snapshot groups)​

Global module parameters​

Global snapshot groups "snapshotGroups"​

Configuration of the "messages" alarm messages​

Configuration of channel value monitoring ("activationMode" = "channelvalues")​

Configuration of channel value monitoring ("activationMode" = "errorstream")​

Module information​