Überwachungsmodul "diagnostics"

Beschreibung

Aufgabe des Überwachungsmoduls "diagnostics" ist es, unterschiedliche Arten von Eingangsdaten bezüglich festgelegter Kriterien zu überwachen und die hieraus resultierenden Alarminformationen anschließend in die smartCORE Alarmdatenbank zu schreiben.

Diese Datenbank kann infolgedessen zur weiteren Verarbeitung der Alarmmeldungen, wie z.B. einer Übertragung in die Cloud, herangezogen werden.

Zu den Arten überwachter Eingangsdaten zählen unter anderem

Boolesche Kanäle
ganzzahlige Kanäle mit (enumeriertem) (Fehler-)Wertebereich
analoge Kanäle mit Messwerten
zweikanalige Kombinationen (Error Streams) bestehend aus Fehlercode und Fehlerlevel

Darüberhinaus werden im Rahmen der Zusammenstellung von Alarmmeldungen aktuelle Werte von smartCORE Kanälen erfasst (sogenannte Snapshots) sowie benutzerdefinierte Metadaten integriert.

Verwendete Schnittstellen & Protokolle

smartCORE Alarmdatenbank

JSON-Konfiguration

In den folgenden Abschnitten werden Beispielkonfigurationen aufgelistet sowie hieran beteiligte Modulparameter diskutiert.

Beispielkonfiguration (Überwachung eines Booleschen Kanals)

In diesem Beispiel wird ein Boolescher Kanal auf den Wert true hin überwacht.

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

Beispielkonfiguration (Überwachung der Überschreitung eines Kanalwerts mit Stabilisierungsverzögerungen und Hysterese)

In diesem Beispiel wird ein ganzzahliger oder Fließkomma-Kanal auf die Überschreitung des Wertes von 42.0 hin überwacht. Im Beispiel ist es zur Auslösung notwendig, dass die Überschreitung mindestens 5 Sekunden lang andauert bzw. zur Deaktivierung, dass diese mindestens 10 Sekunden lang nicht vorliegt und hierfür der Wert des Kanals unterhalb des Schwellwerts minus seiner Hysterese liegt.

Es wird zudem eine ereignisbezogene Meldung generiert, die den aktuellen Wert, das bisherige Extremum, d.h. in diesem Fall Maximum, sowie den Schwellwert beinhaltet.

Diese Meldung wird sowohl bei initialer Überschreitung als auch bei Deaktivierung aktualisiert. Außerdem wird diese Meldung bei Abweichungen des aktuellen Werts vom zuletzt gemeldeten Extremum, die größer als die Hysterese sind, ebenfalls aktualisiert.

{
  "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,
      }
    ]
  }
}

Beispielkonfiguration (Überwachung enumerierter Kanalwerte)

In diesem Beispiel wird ein ganzzahliger Kanal überwacht, wobei die Wertebereiche (17, 77-99) als Auslösebedingung, die Wertebereiche (31-39, 66, 69-71) als Deaktivierungsbedingung sowie sämtliche anderen Bereiche als ungültige Alarmbedingung interpretiert werden.

{
  "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"
      }
    ]
  }
}

Beispielkonfiguration (Überwachung eines Error Streams)

In diesem Beispiel wird ein sogenannter Error Stream überwacht. Dieser besteht aus den beiden sourceErrorCode und sourceErrorLevel Kanälen, die zeitlich synchron sein müssen. Es werden hierbei sowohl ganzzahlige als auch String Fehlercode-Kanäle unterstützt, wohingegen der Fehlerlevel-Kanal ganzzahlige Werte beinhalten muss.

Im Beispiel werden sowohl der benutzerspezifizierte Fehlercode "47:11" als auch sämtliche unbekannten Fehlercodes überwacht.

{
  "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"
      }
    ]
  }
}

Beispielkonfiguration (Überwachung eines Booleschen Kanals, Verwendung von Metadaten)

In diesem Beispiel wird ein Boolescher Kanal auf den Wert true überwacht. Ziel dieses Beispiels ist es, die Ergänzung von Alarmmeldungen um benutzerspezifizierte Metadaten zu veranschaulichen.

Es werden hierfür im Rahmen der Zusammenstellung der Alarmmeldung Metadaten in Form eines JSON-Objekts hinzugefügt, wobei immer die globalen Metadaten um die im Rahmen der Message spezifizierten Metadaten ergänzt bzw. auf oberster Ebene des JSON-Objekts ersetzt werden.

{
  "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"
          ]
        }
      }
    ]
  }
}

Beispielkonfiguration (Überwachung eines Booleschen Kanals, Verwendung von Snapshot-Kanälen)

In diesem Beispiel wird ein Boolescher Kanal auf den Wert true überwacht. Ziel dieses Beispiels ist es, die Ergänzung von Alarmmeldungen um einen benutzerspezifizierten Snapshot von Kanalwerten zu veranschaulichen.

Es wird hierfür zum Zeitpunkt des initialen Auftretens der Alarmbedingung eine Momentaufnahme diverser smartCORE Kanäle angefertigt, die aus der Vereinigung aller globalen und meldungsbezogenen Snapshot-Kanäle besteht.

{
  "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",
        ]
      }
    ]
  }
}

Beispielkonfiguration (Überwachung eines Booleschen Kanals, Verwendung von Snapshot-Gruppen)

In diesem Beispiel wird ein Boolescher Kanal auf den Wert true überwacht. Dieses Beispiel veranschaulicht zusätzlich die Verwendung sogenannter Snapshot-Gruppen.

{
  "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"
        ]
      }
    ]
  }
}

Globale Modulparameter

Im folgenden Abschnitt werden sämtliche Parameter des Moduls diskutiert.

Parametername	Erforderlich	Datentyp	sinnvoller Wertebereich	Default-Wert	Beschreibung
pollingIntervalMs	Nein	INT	1 -	1000 (1 s)	Verarbeitungsintervall [ms]
globalMetadata	Nein	JSON Object		EMPTY JSON Object	JSON Objekt mit beliebigen benutzerspezifizierten Metadaten
globalSnapshot	Nein	JSON Array of STRING		EMPTY JSON Array	JSON Array, welches eine globale Liste mit Kanälen beinhaltet, deren Werte zum Zeitpunkt der Alarmierung punktuell erfasst werden sollen
snapshotGroups	Nein	JSON Array of JSON Object		EMPTY JSON Array	siehe unten
activationMode	JA	STRING		KEIN Default-Wert	Aktivierungsmodus, entweder Kanalwertüberwachung ("channelvalues") oder Error-Stream-Überwachung ("errorstream")
messages	JA	JSON Array of JSON Object		KEIN Default-Wert	siehe unten

Globale Snapshot Gruppen "snapshotGroups"

Mehrere im Rahmen eines Snapshots zu erfassende Kanäle können in Form einer Snapshot-Gruppe als JSON-Objekt konfiguriert werden, deren Name dann im weiteren Verlauf der Konfiguration wie ein Kanalname verwendet werden kann. Sinnvollerweise sollten diese Gruppen so benannt werden, dass keine Überschreibung existierender Kanalnamen erfolgt, da die Namen dieser Gruppen zunächst in die Namen ihrer Bestandteile aufgelöst werden.

Parametername	Erforderlich	Datentyp	sinnvoller Wertebereich	Default-Wert	Beschreibung
name	JA	STRING			Name bzw. Alias der Snapshot-Gruppe
channels	JA	JSON Array of STRING			Liste aller zusammengefassten Kanalnamen

Konfiguration der Alarmmeldungen "messages"

Die Alarmmeldungen "messages" werden hierbei in Form von JSON Objekten und je nach Art der Überwachung unterschiedlich konfiguriert.

Gemeinsame Konfigurationsparameter dieser JSON Objekte sind hierbei

Parametername	Erforderlich	Datentyp	sinnvoller Wertebereich	Default-Wert	Beschreibung
messageLevel	JA	STRING	info, action, service, warning, alarm, error, fatal	KEIN Default-Wert	Schweregrad der Alarmmeldung
context	JA	STRING			Kontext der Alarmmeldung
messageEvent	Nein	STRING			Alarmmeldung, wenn Alarm ausgelöst wird
needAcknowledge	Nein	BOOLEAN	false, true	false	ist eine Quittierung auf Cloud-Seite erforderlich
keepAcknowledgedStatus	Nein	BOOLEAN	false, true	false	soll quittierter Status beibehalten werden
stabilizationSecondsRaise	Nein	INTEGER	1 -	0	Stabilisierungsverzögerung, nach der der Alarm ausgelöst werden soll (es wird der initiale Zeitpunkt des ersten Auftretens der Alarmbedingung gemeldet)
stabilizationSecondsRelease	Nein	INTEGER	1 -	0	Stabilisierungsverzögerung, nach der der Alarm deaktiviert werden soll (es wird der initiale Zeitpunkt des ersten Auftretens der Deaktivierungsbedingung gemeldet)
metadata	Nein	JSON Object		EMPTY JSON Object	Benutzerdefinierte Metadaten, die die globalen Metadaten potentiell überschreiben können
snapshot	Nein	JSON Array of STRING		EMPTY JSON Array	während des initialen Auftretens der Alarmbedingung zu erfassende Kanäle. Es wird der globale Snapshot "globalSnapshot" mit den hier spezifizierten und aufgelösten Snapshot-Gruppen (aus "snapshotGroups") sowie hier individuell spezifizierten Kanälen vereinigt.

Konfiguration der Kanalwertüberwachung ("activationMode" = "channelvalues")

Im Rahmen der Wertüberwachung eines smartCORE Kanals wird das o.g. Konfigurationsobjekt durch folgende Parameter ergänzt, wobei folgende Parameter für eine Schwellwertüberwachung festzulegen sind

Parametername	Erforderlich	Datentyp	sinnvoller Wertebereich	Default-Wert	Beschreibung
channel	JA	STRING		KEIN Default-Wert	Name des überwachten smartCORE Kanals
boundary	JA	INTEGER oder FLOAT		0	Schwellwert, dessen Überschreitung bzw. Unterschreitung zur initialen Erfüllung der Alarmbedingung führt
activation	JA	STRING	low, high, minimum, maximum, positiveEdge, negativeEdge	KEIN Default-Wert	Art der Alarmaktivierung. ("low" => Unterschreitung, "high" => Überschreitung, "minimum" => Unterschreitung mit Überwachung des Minimums, "maximum" => Überschreitung mit Überwachung des Maximums, "positiveEdge" => Überschreitung (nur initiale, zustandslose Alarmierung), "negativeEdge" => Unterschreitung (nur initiale, zustandslose Alarmierung)

Im Fall der Bereichsüberwachung , d.h. wenn der Wert eines Kanals aus einer Aufzählung (enum) stammt, können folgende zusätzliche Parameter spezifiziert werden.

Parametername	Erforderlich	Datentyp	sinnvoller Wertebereich	Default-Wert	Beschreibung
channel	JA	STRING		KEIN Default-Wert	Name des überwachten smartCORE Kanals
valuesLow	WAHLWEISE	STRING		"0"	Spezifikation der Wertebereiche, die einer deaktivierten Alarmbedingung korrespondieren
valuesHigh	WAHLWEISE	STRING		"0"	Spezifikation der Wertebereiche, die einer ausgelösten Alarmbedingung korrespondieren
activation	JA	STRING	enum	KEIN Default-Wert	Art der Alarmaktivierung. In dieser Konfiguration ist lediglich enum sinnvoll.

Es kann hier wahlweise eine bzw. beide der o.g. Wertebereichsspezifikationen valuesLow bzw. valuesHigh verwendet werden. Wird lediglich eine Spezifikation verwendet, so entspricht die andere dem Gegenteil dieser Spezifikation. Werden hingegen beide Spezifikationen verwendet, so entsprechen die nicht abgedeckten Wertebereiche einer ungültigen Alarmbedingung. Hierfür kann eine ungültige Alarmmeldung in Form folgenden zusätzlichen Parameters spezifiziert werden

Parametername	Erforderlich	Datentyp	sinnvoller Wertebereich	Default-Wert	Beschreibung
messageFailure	Nein	STRING			Alarmmeldung, wenn Alarmierungsbedingung ungültig ist

Konfiguration der Kanalwertüberwachung ("activationMode" = "errorstream")

Es kann ebenso ein sogenannter Error Stream überwacht werden. Dieser besteht i.A. aus zwei zeitlich synchronen smartCORE Kanälen, die einerseits den Fehlercode und andererseits das Fehlerlevel beinhalten.

Diese beiden Kanäle werden als globale Modulparameter wie folgt konfiguriert

Parametername	Erforderlich	Datentyp	sinnvoller Wertebereich	Default-Wert	Beschreibung
sourceErrorCode	JA	STRING		KEIN Default-Wert	smartCORE Kanal, der einen zeitlich variablen Fehlercode beinhaltet
sourceErrorLevel	JA	STRING		KEIN Default-Wert	smartCORE Kanal, der ein hierzu synchrones Fehlerlevel beinhaltet

Der sourceErrorCode Kanal ist hierbei ein Kanal, der entweder ganzzahlige Werte oder Strings bereitstellt. Der sourceErrorLevel Kanal hingegen stellt ganzzahlige Werte bereit.

Weiterhin kann in der globalen Modulkonfiguration ein neutraler Fehlerlevel wie folgt spezifiziert werden

Parametername	Erforderlich	Datentyp	sinnvoller Wertebereich	Default-Wert	Beschreibung
neutralErrorCode	Nein	STRING		0	Neutraler Fehlerlevel, bei dem KEIN Alarm ausgelöst wird

Die einzelnen Alarmmeldungen "messages" (in diesem Fall bezüglich unterschiedlicher Fehlercodes) werden wie oben dargestellt konfiguriert. Es sind außerdem folgende Parameter zu spezifizieren

Parametername	Erforderlich	Datentyp	sinnvoller Wertebereich	Default-Wert	Beschreibung
errorCode	WAHLWEISE	STRING			Fehlercode, der von dieser Überwachungseinheit überwacht wird
isTemplate	WAHLWEISE	BOOLEAN	false, true	false	handelt es sich um eine Überwachungseinheit für unbekannte Fehlercodes (Wildcard)?

Ist errorCode spezifiziert, wird die entsprechende Alarmmeldung in Reaktion auf den Fehlercode erstellt. Ein Template hingegen konfiguriert Alarmmeldungen für sämtliche unbekannten Fehlercodes.

Modul-Informationen

Information	Wert
Autoren	optiMEAS Measurement and Automation Systems GmbH
seit smartCORE	2.6
Modultyp	Consumer
Abhängigkeiten	KEINE

Beschreibung​

Verwendete Schnittstellen & Protokolle​

JSON-Konfiguration​

Beispielkonfiguration (Überwachung eines Booleschen Kanals)​

Beispielkonfiguration (Überwachung der Überschreitung eines Kanalwerts mit Stabilisierungsverzögerungen und Hysterese)​

Beispielkonfiguration (Überwachung enumerierter Kanalwerte)​

Beispielkonfiguration (Überwachung eines Error Streams)​

Beispielkonfiguration (Überwachung eines Booleschen Kanals, Verwendung von Metadaten)​

Beispielkonfiguration (Überwachung eines Booleschen Kanals, Verwendung von Snapshot-Kanälen)​

Beispielkonfiguration (Überwachung eines Booleschen Kanals, Verwendung von Snapshot-Gruppen)​

Globale Modulparameter​

Globale Snapshot Gruppen "snapshotGroups"​

Konfiguration der Alarmmeldungen "messages"​

Konfiguration der Kanalwertüberwachung ("activationMode" = "channelvalues")​

Konfiguration der Kanalwertüberwachung ("activationMode" = "errorstream")​

Modul-Informationen​