HSMDataCollector is a .Net library for collecting monitoring data and sending it to the running HSM Server. You just create a C# object for a new sensor and call a method to pass new values. Current guide can be applied to versions from 1.3.13 and higher, some features may not have appeared in previous yet.

Supported versions

HSMDataCollector currently supports .Net Framework4.6.1 and higher, and also .Net Core3.0 and higher.

Installation

You can visit the NuGet page to learn about the different ways of installing the package, or simply use visual studio to add it.

From version 1.3.13 HSMDataCollector.HSMDataCollector is the only package you need to install, if you want to use previous versions (which is not recommended), you also need to install HSMDataCollector.HSMSensorDataObjects (we recommend to use same version, as HSMDataCollector).

Usage

HSMDataCollector is currently a C# library, so you need to add HSMDataCollector.HSMDataCollector to your project. To start using DataCollector, create an instance of IDataCollector intreface:

IDataCollector collector = new DataCollector("2201cd7959dc87a1dc82b8abf29f48", "https://localhost", 44330);
collector.Initialize();

The first parameter is a product key, go here to learn more about product keys. Second parameter is your HSM server address, and the third parameter is HSM server swagger port, which is usually 44330 if there is no other port routing configuration. Method Initialize() must be called before any other method you use.

IDataCollector is derived from IDisposable interface, which means that IDataCollector can be applied inside the 'using' clause. Method IDataCollector.Stop() must be called at the end of the program. You may skip calling this method if use 'IDataCollector' inside' using.

Standard sensors

IDataCollector provides standard groups of sensors. They monitor current working process and operating system. Add the following lines to initialize this sensors:

collector.InitializeSystemMonitoring(true, true);
collector.InitializeProcessMonitoring(true, true, true);
collector.MonitorServiceAlive();

InitializeSystemMonitoring() creates sensors, which collect information about free RAM and common CPU usage. The data is stored in five minute bars. InitializeProcessMonitoring() creates three sensors: current process thread count, current process CPU usage, and current process RAM usage. MonitorServiceAlive creates one sensor, which sends boolean 'true' values every 15 seconds. PLEASE NOTE, that system and process monitoring are currently not supported on non-Windows operating systems, however the HSMDataCollector library is compatible with .Net Core3.0-5.0 projects as well as with .Net Framework4.7.2 and higher. Visit this page to learn more about standard sensors.

Common sensor types

IDataCollector supports creating different sensors of 6 common types: boolean, int, double, string, intBar and doubleBar. Every sensor has a 'comment' field, so the comment can be added to every value. There is also a 'status' field, which can be set to make pre-server value validation. Statuses and comments are displayed on the client side if they exist, passing no values is also possible. The types below represent different data types. HSM sensors may also have different functionality, visit this page to learn more.

Boolean sensor

Sensor value has boolean type, which means it can be true or false only. The data is passed to a sending queue immediately. The usage is the following:

var boolSensor = collector.CreateBoolSensor("sensors/Boolean");
boolSensor.AddValue(true);
boolSensor.AddValue(true, "True value");
boolSensor.AddValue(false, SensorStatus.Error, "False value comment");

Integer sensor

The value is an integer number, which is 'int' type from C# language. The value is also sent immediately, values history is a graph on the client side. Sensor creation is similar to creation boolean sensor:

var intSensor = collector.CreateIntSensor("sensors/Integer");
intSensor.AddValue(823);
intSensor.AddValue(0, "Zero value");
intSensor.AddValue(-1, SensorStatus.Error, "Error: negative values are not allowed!");

Double sensor

Double sensor is very similar to integer sensor, besides the fact, that the value field has 'double' type. The following code snippet demonstrates usage of double sensor:

var doubleSensor = collector.CreateDoubleSensor("sensors/Double");
doubleSensor.AddValue(34.42341341);
doubleSensor.AddValue(1.60934, "Kilometers in one mile");
doubleSensor.AddValue(0.44, SensorStatus.Warning, "The probability is lower than 0.5");

String sensor

String sensor has a 'string' value field. You still can add comment and status for string sensors, we recommend to use it in combination with other sensors. For example, create boolean sensor to determine whether some action starts or not, and pass launch error to string sensor if such an error occurs. Usage of string sensor:

var stringSensor = collector.CreateStringSensor("sensors/String");
stringSensor.AddValue("Hello world!");
stringSensor.AddValue("The process launched successfully", "Automatically created message.");
stringSensor.AddValue(new Exception().ToString(), SensorStatus.Error, "Error occurred!");

Bar sensors

Bar sensors give you more opportunities, because they collect data in a "analyzable way". Basically, the bar sensor is a list, which collects all the values within the given period (defaults to 5 minutes), and then sends the following info: values count, last value, min, max, median, average value, and some precentiles. Now the percentiles are the first and the third quartiles, the ability to configure percentiles will be added in later versions. The sensor also sends intermediate values to be displayed in clients, intermediate values interval is 15 seconds by default.

Integer Bar sensor

Integer bar sensor collects values of integer type. There are methods for creating with default bar time values 1 minute, 5 minutes, 10 minutes, 30 minutes, and an hour. Creation and usage examples:

var intMinute = collector.Create1MinIntBarSensor("sensors/IntOneMinute");
var intFiveMinutes = collector.Create5MinIntBarSensor("sensors/IntFiveMinute");
var intTenMinutes = collector.Create10MinIntBarSensor("sensors/IntTenMinute");
var intHalfAnHour = collector.Create30MinIntBarSensor("sensors/IntHalfAnHour");
var intHour = collector.Create1HrIntBarSensor("sensors/IntHour");
var intBarCustomTime = collector.CreateIntBarSensor("sensors/CustomTime", 700000, 40000);
intBarCustomTime.AddValue(31);

Double Bar sensors

Double Bar sensor collects data of double type, creation methods are same as for Integer Bar Sensor. Double Bar sensor also allows to specify precision for all values and calculations. Default precision value is 2, which means two decimal digits. The following code snippet demonstrates creation sensor instances and sensor objects usage:

var doubleBarMinute = collector.Create1MinDoubleBarSensor("sensors/DoubleBarOneMinute");
var doubleBarFiveMinutes = collector.Create1MinDoubleBarSensor("sensors/DoubleBarFiveMinutes", 4);
var doubleBarTenMinutes = collector.Create1MinDoubleBarSensor("sensors/DoubleBarTenMinutes", 10);
var doubleBarThirtyMinutes = collector.Create1MinDoubleBarSensor("sensors/DoubleBarThirtyMinutes");
var doubleBarHour = collector.Create1MinDoubleBarSensor("sensors/DoubleBarHour");
var doubleBarCustomTime = collector.CreateDoubleBarSensor("sensors/CustomTimeDouble", 800000, 20000, 1);
doubleBarCustomTime.AddValue(876.42567);