[Erlang Systems]

2 Services

The purpose of this document is to give an understanding of how the Measurement Handler works, and how to build applications to interact with MESH. The intention is not to give all details about the functions making up the MESH API; for a complete description of this API, please see the mesh Reference Manual.

For a description of the statistical functions that are available through the Measurement Handler application, please see the mesh_lib Reference Manual.

The main purpose of the Measurement Handler is to provide the user with a simplified and uniform way of handling measurement data, as well as managing the applications and processes generating the data. To accomplish this, the Measurement Handler application takes care of common tasks, such as creation and control of measurement applications/processes, node and measurement application supervision, threshold checking and notification, tide-mark handling, and so on. A model is available to the user when implementing the applications and processes performing the actual measurements.

2.1 Services Offered by the Measurement Handler

The following is a complete list of the services the Measurement handler currently offers:

2.2 Basic Concepts

A Measurement Object is a user provided application or process collecting and filtering measurement samples provided by one or more resource objects, see below. Measurement objects are grouped together in Measurement Types.

A Measurement Type may be regarded as a container, holding all the code needed when dealing with the associated measurement objects. Specifically, the measurement type shall provide an interface, which is used by the Measurement Handler to create, delete, and control the measurement objects.

A Resource Object is a user or operating system provided application or device producing measurement samples.

Measurement types and objects exhibit three groups of states that are supported by the Measurement Handler:

2.3 Implementation of Measurement Objects

Basically a measurement object consists of a server, polling one or more resource objects for measurement samples, which are filtered and reported to the Measurement Handler. However,if supervision is desired, parts of the supervision scheme have to be implemented by the user. This leads us to the concept of Measurement Responsible Processes, MRPs.

A Measurement Responsible Process may be regarded as the gateway between the measurement type interface and the individual measurement objects (belonging to that specific measurement type). There may be many measurement objects, but we want to access all of them with the same function in the measurement type interface, meaning that we have to provide the (state-less) interface with information about how to contact a certain measurement object. There are basically two ways of doing this:

The above alternatives are a matter of choice, depending on the supervision required; this is explained in greater detail below. MESH supports both alternatives, provided the user follows some basic rules. The first one is to ensure that the MRP fulfills the following four requirements:

Secondly, should an MRP terminate, MESH assumes that the corresponding measurement objects also terminates! In short, an MRP has to be very robust, i.e., it has to trap exits, even internally (for example by letting the inner loop be surrounded by a catch-statement, where run-time errors may be caught and the inner loop re-entered).

Finally, when MESH calls functions in the measurement type interface, the MRP process identifier should be supplied as one of the arguments. The measurement type interface forwards the order to the MRP, e.g., by sending a message to the MRP, which in turn performs the order, or forwards it to the correct measurement object. For this to work, it is required that the measurement type interface (when the creation of a new measurement object is ordered), returns the process identifier to the MRP responsible for the new object.

Three suggested MRP models are described extensively below, in section "MRP Models".

2.4 MRP Models

As seen previously, in the section "Implementation of Measurement Objects", it is required that all measurement objects are linked to a Measurement Responsible Process. The Measurement Responsible Process must also fulfill some requirements.

There are three main implementation cases:

mrp
MRP Models. (R=Resource Object, SV=Supervisor, MO=Measurement Object)

Each of the three cases is described in depth below.

2.4.1 Case I - applications and OTP supervision

In this case the measurement objects are part of an application. The OTP mechanisms for supervision are fully used, and the OTP mechanisms for changing code in runtime may be used.

When the application is started, it registers the corresponding measurement type in MESH. This causes MESH to call the init function in the measurement type interface; this function will return (to MESH) the Process Identifier of the MRP (it may even start the MRP). Note:A registered name is not adequate, since MESH uses the PID to get the node where the MRP resides!

Now that the measurement type has been registered, measurement objects may be created. This causes MESH to call the create_measurement function in the measurement type interface. It is required that this function returns the process identifier of the associated MRP (the one mentioned above), which MESH will supervise. MESH will also supervise the node where the MRP is residing.

When MESH wants to communicate with any measurement object, using the measurement type interface, it is the responsibility of the MRP to map the measurement object identifier to the process identifier in question, and to forward the order/message to that process. (The MRP may for example internally keep a list of tuples {MeasurementID, PID}.

Should a measurement object terminate, the MRP will notify MESH (and also decide if it should request revival of the object).

Should the MRP itself terminate, e.g., due to a node crash, MESH will use EVA to notify the manager about the disabled measurement objects (or unconnected, depending on the type of crash). MESH will then wait for the node to be restarted. If just the connection to the node was lost MESH will try to re-connect to the MRP. If the attempt is successful, the manager will be informed (via EVA) about the measurement type and the measurement objects being reconnected, otherwise MESH will wait for the application to be restarted, the type re-registered and the measurement objects revived.

Should the application restart, it will once again try to register the measurement type, whereupon it will be informed (using the return value of the registration function) by MESH that the type has already been registered. The application may now choose to ask MESH to restart the measurement objects it is aware of (i.e., those measurement objects that haven't been explicitly deleted by the manager or the application). It shall be noted that the registration attempt will cause MESH to once again call the init function in the measurement interface, since it has to get the process identifier of the new MRP!

2.4.2 Case II - no applications, and simplified supervision

In this case the measurement objects are not part of an application, and the OTP mechanisms for supervision are not fully utilized. Instead, the MRP supervises the measurement objects it has started, restarting them (or requesting MESH to restart them) when necessary. MRP itself is not supervised by any other process than MESH. MESH, in turn, only notifies the manager if the MRP terminates. Therefore, the MRP is not restarted unless the manager explicitly orders MESH to re-register the measurement type (more about this below).

A process, or the manager, registers the measurement type in MESH. As previous, this will cause MESH to call the init function in the measurement type interface; this function will return the process identifier of the MRP.

Now that the measurement type has been registered, measurement objects may be created. MESH will then call the create_measurement function in the measurement type interface. This function returns the process identifier of the associated MRP (the one mentioned above), which MESH will supervise. MESH will also supervise the node where the MRP is residing.

As in the previous case, the MRP will handle the mapping of measurement object identifiers to the correct corresponding process identifier, forwarding messages and orders to the correct recipient. Should a measurement object terminate, MRP shall notify MESH, and decide if MESH should revive the measurement object.

Should the MRP itself terminate, for example, due to a node crash, MESH will use EVA to notify the manager about the corresponding measurement objects being disabled (or unconnected, depending on the type of crash). MESH will then wait for the node to be started again. In instances where only the connection to the node is lost MESH will try to re-connect to the MRP. Should the attempt succeed, the manager will (via EVA) be informed about the measurement type and the measurement objects being reconnected. Otherwise MESH will wait for the application to be restarted, the measurement type re-registered and the measurement objects revived. Note: Should the manager directly order revival of the measurement objects (mesh:revive_measurement), the attempt will fail and the return value will inform the manager the cause of the previous termination of the MRP.

When re-registration has been ordered and completed, MESH may be ordered to revive the objects it is aware of (i.e., those measurement objects that haven't been explicitly deleted by the manager or the application). Note: Even in this case the registration attempt will again causes MESH to call the init function in the measurement interface, since it has to get the process identifier of the new MRP!

It should be noted that the OTP mechanisms for changing code in runtime cannot be used in this case.

2.4.3 Case III - each measurement object is its own MRP

In this case each measurement object also functions as an MRP. This means that if the measurement objects are terminated they won't be restarted, unless MESH is explicitly ordered by the manager to revive them.

A process, or the manager, will register the measurement type in MESH. This causes MESH to call the init function in the measurement type interface; unlike Case I and II, this function will return the atom undefined (since there is no common MRP here).

Now measurement objects may be created. As above, this results in the create_measurement function in the measurement type interface being called. It is required that this function returns the MRP PID associated with the measurement object, i.e., the PID of the measurement object itself! MESH will supervise this process, and also the node where it's residing.

Should a measurement object terminate, MESH will, using EVA, notify the manager of this, whereupon MESH will wait for further orders. Provided the node in question is up, the manager may order MESH to revive the measurement objects. Once again, when the create_measurement function in the measurement type interface is called, and will return the PID of the MRP/measurement object.

Should it be unclear whether a measurement object/MRP has actually terminated (for example, if the connection to a node has been lost), MRP will wait for the node to be connected once again. MESH will then check whether or not the measurement object/MRP still exists. If it does, the manager will be informed (via EVA) that it still exists or that the the measurement object has been disabled.

It should be noted that the OTP mechanisms for changing code in runtime cannot be used in this case.

2.5 Working with the Measurement Handler

In the following example we will take a close look at how to start and work with the Measurement Handler. This example demonstrates the functionality of the Measurement Handler, it is run on only one node and is extremely simplified and therefore may not show the optimal way to configure the system and the different applications required.

We will be using the simple interface module below, diversity.erl. This module uses the "Case II" model described in section "MRP Models", as described in the previous chapter.

-module(diversity).

%% Necessary type interface functions!
-export([init/1,
         terminate/1,
         create_measurement/5,
         delete_measurement/3,
         start_measurement/3,
         stop_measurement/2,
         reset_measurement/3]).

-export([mrp/0,
         meas/2]).


%% A simple measurement type interface.

init(TypeName) ->
    spawn(?MODULE, mrp, []).

terminate(undefined) ->
    ok;
terminate(MRP) ->
    MRP ! terminate,
    ok.

create_measurement(undefined, _Type, _Meas, _Res, _Args) ->
    {error, no_mrp};
create_measurement(MrpInit, TypeName, MeasName, ResId, InitArgs) ->
    MrpInit ! {create_measurement, self(), MeasName, InitArgs},
    receive 
        {Pid,MrpInit} ->
            MrpInit
    end.

start_measurement(MRP, MeasName, Args) ->
    MRP ! {start, MeasName, Args},
    ok.

stop_measurement(MRP, MeasName) ->
    MRP ! {stop, MeasName},
    ok.

reset_measurement(MRP, MeasName, Args) ->
    MRP ! {reset, MeasName, Args},
    ok.

delete_measurement(MRP, MeasName, Args) ->
    MRP ! {delete_measurement, MeasName, Args},
    ok.


%% The code implementing a Measurement Responsible Process.

mrp() ->
    process_flag(trap_exit, true),
    catch mrp_loop([]),
    mrp().

mrp_loop(MeasList) ->
    receive
        {create_measurement, Sender, MeasId, InitArgs} ->
            Pid = spawn_link(?MODULE, meas, [self(), MeasId]),
            Sender ! {Pid, self()},
            mrp_loop([{MeasId, Pid} | MeasList]);
        {delete_measurement, MeasId, InitArgs} ->
            case lists:keysearch(MeasId, 1, MeasList) of
                false ->
                    done;
                {value, {MeasId,Pid}} ->
                    exit(Pid, kill)
            end,
               % We remove the measurement from the list when the 
               % exit signal is received.
            mrp_loop(MeasList);
        {start, MeasId, Args} ->
            send_to_meas(MeasId, MeasList, {start,Args}),
            mrp_loop(MeasList);
        {stop, MeasId} ->
            send_to_meas(MeasId, MeasList, stop),
            mrp_loop(MeasList);
        {reset, MeasId, Args} ->
            send_to_meas(MeasId, MeasList, {reset,Args}),
            mrp_loop(MeasList);
        {'EXIT', Pid, Reason} ->
            case lists:keysearch(Pid, 2, MeasList) of
                false ->
                    mrp_loop(MeasList);
                {value, {MeasId,Pid}} ->
                    mesh:measurement_terminated(MeasId, Reason),
                    mrp_loop(lists:keydelete(Pid, 2, MeasList))
            end;
        Other ->
            mrp_loop(MeasList)
    end.

send_to_meas(MeasName, MeasList, Msg) ->
    case lists:keysearch(MeasName, 1, MeasList) of
        false ->
            done;
        {value,{Meas,Pid}} ->
            Pid ! Msg
    end.


%% The code implementing a measurement object.

meas(MRP, Name) ->
    process_flag(trap_exit, true),
    meas_loop(MRP, Name, []).

meas_loop(MRP, Name, Args) ->
       % A simple measurement object loop where we ignore
       % start, stop and reset orders!
    receive
        {start,NewArgs} ->
            meas_loop(MRP, Name, NewArgs);
        stop ->
            meas_loop(MRP, Name, Args);
        {reset,NewArgs} ->
            meas_loop(MRP, Name, NewArgs);
        {'EXIT', MRP, Reason} ->
            done;
        _Other ->
            meas_loop(MRP, Name, Args)
    end.
    

2.5.1 Preparation and Start of MESH

In order to start MESH the applications MESH requires must first be started:

First we make sure SASL is started:

1> application:start(sasl).
ok
      

Next, we prepare for and start Mnesia (running on a single node only). Mnesia is used by MESH to persistently store data about measurement types and measurement objects, see chapter _______ for further information.
First of all, a schema must be created on each node where the MESH application may run (in this example - one node).

2> mnesia:create_schema([]).
ok

3> application:start(mnesia).
ok
      

We now proceed by preparing for and starting EVA, which is used by MESH to send and log events and alarms. It should be noted that MESH doesn't supervise EVA, meaning that normally this has to be taken care of by the client application programmer.
It should also be noted that in the most cases, when EVA runs on the same node as MESH internal communication is reduced improving performance.

The first step in the EVA preparations consists of creating the Mnesia tables needed by the basic EVA service and the EVA log service, on each of the nodes where the MESH application is supposed to be running.

4> eva_sup:create_tables_log([]).
ok
      
5> disk_log:open([{name,"default_log"},{format,internal},{type,wrap},{size,{10000,10}}]).
{ok,"default_log"}

6> eva_sup:start_link_log("default_log").
{ok,<0.153.0>}

7> application:start(eva).               
ok
      

NOTE: If we intend to use the MESH SNMP adaptation, the previous commands shall instead be:

4> eva_sup:create_tables_log_snmp([]).
ok

5> disk_log:open([{name,"default_log"},{format,internal},{type,wrap},{size,{10000,10}}]).
{ok,"default_log"}

6> eva_sup:start_link_log_snmp("default_log", LogDir, MaxDirSize)
{ok,<0.153.0>}

7> application:start(eva).
ok      
      

We may now finally start MESH. Firstly, we must create the Mnesia tables needed by MESH. (Currently two tables are used by MESH, mesh_type and mesh_meas. They are replicated to disk and RAM on each node that may run the MESH application.)

8> mesh:create_tables([]).
ok

9> application:start(mesh).
ok
      

NOTE: if we want the MESH SNMP adaptation to be started, the environment variable snmp_adapted must be set to true!

2.5.2 Registering Measurement Types

Now all preparations are finished, and we can start registering measurement types. We begin by registering a type called diversity1, using the diversity interface module. Specify the number of measurement objects, belonging to this type, that may be created (up to ten). The argument containing any optional description of the type should be set to the string "A simple measurement type".

10> mesh:register_type(diversity1,"A simple measurement type",diversity,5).
{registered,diversity1}
      

We register one more type, from which it may be possible to create 10 measurement objects:

11> mesh:register_type(diversity2,"Another measurement type",diversity,10).      
{registered,diversity2}
      

When we register a type, MESH will call the init function in the interface module. In our example, this function spawns an MRP process, and returns the process identifier. MESH links itself to the new MRP, and stores the PID for further usage - it will be used whenever operations are performed on, or associated with, the measurement type.

We may ask the Measurement handler for types currently registered:

12> mesh:list_types().
[{diversity1,[{extra,"A simple measurement type"},
              {interface_mod,diversity},
              {instances,0},
              {max_instances,5},
              {administrative_state,unlocked}]},
 {diversity2,[{extra,"Another measurement type"},
              {interface_mod,diversity},
              {instances,0},
              {max_instances,10},
              {administrative_state,unlocked}]}]
      

In the listing we see that the administrative state of both types is unlocked, and that the number of instances, i.e., the number of measurement objects created, is zero.

2.5.3 Creating Measurement Objects

Now that we have registered measurement types, we may start creating measurement objects. We call this first measurement object div11, specifying it belongs to the type diversity1. Since we don't have any resource objects in this example, we may let the resource argument contain a zero. The argument containing any optional description of the measurement object should be set to the string "A simple measurement object". We set the original administrative state to started, and specify the initial arguments to be the list [1,2,3].

13> mesh:create_measurement(div11,diversity1,"A simple measurement object",0,started,[1,2,3]).
{created,div11}
      

When we create a measurement object, MESH will call the create_measurement function in the interface module. However, in this example the two measurement types diversity1 and diversity2 share the same interface module. Note:It is possible to have unique types sharing the same module.
As shown above each type has a corresponding MRP - and when MESH calls the create_measurement function, one of the arguments is the process identifier of the correct MRP. The interface forwards the create order to this MRP, which in turn spawns a process implementing the measurement object div11. When the type interface finally returns, the return value shall contain the process identifier of the process (ie. Measurement Responsible Process for div11). From now on, when managing div11, every function call MESH does will contain the MRP PID returned when div11 was created. This is illustrated in the code above.

In Cases I & II the MRP PID must return the same value as when registering the type. In Case III a PID value will be returned which cannot be the same as the returned value (undefined) when registering the type. In all cases, the only requirement is that the MRP fulfills the responsibilities that were listed previously
MESH will ensure that it is linked to the MRP, and store the PID for further usage. As mentioned above, it will be used whenever we want to use the measurement object.

At any time it is possible to ask the Measurement Handler for a list of the measurement objects created:

17> mesh:list_measurements(diversity1).
[{div11,[{extra,"A simple measurement object"},
         {resources,0},
         {initial_arguments,[1,2,3]},
         {operability_state,enabled},
         {administrative_state,started}]}]
      

2.5.4 Measurement Type and Object Administration

This section outlines how the registered measurement types and the created measurement objects may be controlled.

Measurement objects may be started, stopped and reset. Each time we start or reset a measurement object, we may specify a new list of arguments, manipulating the internal state of the measurement object. It is important that these argument lists have the same format as the argument list specified when the measurement object was created. This is due to the revival procedure, which will use the last known argument list when re-creating the measurement object; we will take a closer look at this later on in this document.

18> mesh:stop_measurement(div11).
{stopped,div11}

19> mesh:list_measurements(diversity1).
[{div11,[{extra,"A simple measurement object"},
         {resources,0},
         {initial_arguments,[1,2,3]},
         {operability_state,enabled},
         {administrative_state,stopped}]}]

20> mesh:start_measurement(div11, [4,5,6]).
{started,div11}

21> mesh:list_measurements(diversity1).    
[{div11,[{extra,"A simple measurement object"},
         {resources,0},
         {initial_arguments,[4,5,6]},
         {operability_state,enabled},
         {administrative_state,started}]}]

22> mesh:reset_measurement(div11,[7,8,9]).
{reset,div11}

23> mesh:list_measurements(diversity1).   
[{div11,[{extra,"A simple measurement object"},
         {resources,0},
         {initial_arguments,[7,8,9]},
         {operability_state,enabled},
         {administrative_state,started}]}]
      

For each of these orders, MESH calls the corresponding function in the measurement type interface, with one argument being the PID of the MRP associated with measurement object div11. It should be noted, that it is the measurement type interface, via the MRP, that actually performs the orders, while MESH in this case has a book-keeping functionality.
In the list of functions above, we can also see that the initialization arguments MESH keeps record of changes when we reset and start the measurement object. (MESH itself doesn't interpret this list of arguments, that is up to the measurement object itself to do.)

When a measurement object is reset, MESH will internally reset the measurement reports received from the object, as well as the tide-marks associated with the object. If there are any thresholds set, they will remain set, but in such a way that triggered thresholds may once again be triggered (i.e. through the reset operation they become UT-triggered).
The measurement object is also ordered to reset itself, via the measurement type interface function reset_measurement, using the supplied arguments mentioned above (see also the section regarding thresholds and tide-marks).

Measurement types may be locked, unlocked and shut down. Below the locking capabilities and consequences are illustrated:

24> mesh:lock_type(diversity1).
{locked,diversity1}

25> mesh:list_types().         
[{diversity1,[{extra,"A simple measurement type"},
              {interface_mod,diversity},
              {instances,0},
              {max_instances,5},
              {administrative_state,locked}]},
 {diversity2,[{extra,"Another measurement type"},
              {interface_mod,diversity},
              {instances,0},
              {max_instances,10},
              {administrative_state,unlocked}]}]

26> mesh:list_measurements(diversity1).
[]

27> mesh:create_measurement(div11,diversity1,"",0).
{error,{type_locked,diversity1}}
      

The locking of a measurement type results in the deletion of all existing measurement objects belonging to that very same type, as shown above. We also see that it is impossible to create a new measurement object, since the administrative state of the measurement type doesn't allow this operation.

We now unlock the measurement object:

28> mesh:unlock_type(diversity1).
{unlocked,diversity1}
        
29> mesh:create_measurement(div11, diversity1, "", 0).
{created,div11}             

30> mesh:create_measurement(div12, diversity1, "", 0).
{created,div12}             
      

Having unlocked the measurement type we may once again create measurement objects.

Finally, let us take a look at the third administrative state, shutting down:

28> mesh:shut_down_type(diversity1).                  
{shutting_down,diversity1}

29> mesh:list_types().                                
[{diversity1,[{extra,"A simple measurement type"},
              {interface_mod,diversity},
              {instances,2},
              {max_instances,5},
              {administrative_state,shutting_down}]},
 {diversity2,[{extra,"Another measurement type"},
              {interface_mod,diversity},
              {instances,0},
              {max_instances,10},
              {administrative_state,unlocked}]}]

30> mesh:create_measurement(div13, diversity1, "", 0).
{error,{type_shutting_down,diversity1}}

31> mesh:delete_measurement(div12).                   
{deleted,div12}

32> mesh:create_measurement(div12, diversity1, "", 0).
{error,{type_shutting_down,diversity1}}

33> mesh:delete_measurement(div11).                   
{deleted,div11}

34> mesh:list_types().                                
[{diversity1,[{extra,"A simple measurement type"},
              {interface_mod,diversity},
              {instances,0},
              {max_instances,5},
              {administrative_state,locked}]},
 {diversity2,[{extra,"Another measurement type"},
              {interface_mod,diversity},
              {instances,0},
              {max_instances,10},
              {administrative_state,unlocked}]}]
      

Note that all existing measurement objects continue to exist when shut down has been ordered, but that no new measurement objects may be created. Also, old measurement objects may not be re-created, once they have been deleted.
When the last measurement object, belonging to the type in question, has been deleted, the measurement type automatically enters state locked.

2.5.5 Deleting Measurement Objects

A measurement object is regarded as "existing" (ie. the Measurement Handler is aware of it), until it is explicitly deleted. Should the process/application implementing the measurement object crash, MESH regards the object as being disabled - but it still exists.
Below is an example of this, assume there is a previously created a measurement object div11, that unfortunately has crashed (i.e., the process implementing div11 has crashed).

35> mesh:list_measurements(diversity1).
[{div11,[{extra,[]},
         {resources,0},
         {initial_arguments,[]},
         {operability_state,disabled},
         {administrative_state,started}]}]

36> mesh:create_measurement(div11, diversity1, "", 0).
{error,{already_created,div11}}

37> mesh:delete_measurement(div11, [4,5]).
{deleted,div11}

38> mesh:list_measurements(diversity1).               
[]
      

When deleting a measurement object, MESH will call the delete_measurement function in the interface module. The stop arguments specified in the call to MESH (in our example, the list [4,5]) will be forwarded to this function. This enables a controlled and graceful termination of the measurement object (eg.leaving no open files).

2.5.6 Unregistering Measurement Types

Measurement types are unregistered in the following way:

39> mesh:unregister_type(diversity1, [4,5]).
{unregistered,diversity1}
      

Any existing measurement objects will be deleted, following the scheme described in the section above, "Deleting Measurement Objects". In this case, to enable a controlled termination of measurement objects, stop arguments must be specified, for example [4,5]. These arguments will only be forwarded to the delete_measurement function in the measurement type interface.

Once all measurement objects are deleted, the terminate function in the measurement type interface is called, enabling a graceful and complete clean-up, should that be desired. This function shall terminate the MRP (if there is any), but may also be used to free common resources used by the measurement type and objects.
After this process is complete the user is free to re-use the measurement type name/identifier to associate it with another interface module.

2.6 Revival of Measurement Objects

If a measurement object becomes disabled, e.g., due to a crash in the process/application implementing it, the user may request the object revival, using the function revive_measurement. MESH will then order the measurement type interface to once again create the measurement function. Thecreate_measurement function in the measurement type interface will be called. The arguments will be implemented according to the information MESH previously stored about the measurement object in question. The previously stored information will include the last known administration state, the last known start argument list, the resources used, the thresholds set, and so on. Provided the creation doesn't fail, the measurement object revived will be as close as possible to a copy of the old measurement object, prior to it disabling.
Note: the revival procedure is finished with an explicit order, issued by MESH itself, to reset the measurement object. This is to ensure identical states in the Measurement Handler and the measurement object. Even thresholds and tide-marks are reset, see description of the reset procedure.

Should revival, using the settings stored in MESH, not be wanted, the user may choose to first delete the measurement object, and then create a completely new object, using the old measurement object identifier.

2.7 Measurement Object Operation and Measurement Value Reporting

Generally, a measurement object collects a number of samples, from one or more resources and samples which later one shall be filtered using an algorithm (presumably one found in the mesh_lib support library). It is the sole responsibility of the user to decide when each sample shall be collected.

The start arguments make it possible to specify when creating, starting and resetting of measurement objects may be used to tell the measurement object when to start sampling, and the sampling interval.

In some situations it may also be desirable to dynamically tell the measurement object which filtering algorithm shall be used. However, whatever the start arguments are used for, the onus is on the user to decide how the list of arguments shall be interpreted by the measurement object.

When the measurement object has obtained a filtered measurement value, a value is reported to the Measurement Handler, using the measurement_report function. When the Measurement Handler receives such a measurement value report, it compares the received value with the thresholds set, sending an alarm to EVA if any threshold is triggered. It also updates the tide-marks associated with the measurement object, stores the measurement value internally, and finally sends a meshMeasurementReport event to EVA. This event containing the measurement value is received among other measurement specific information. (All measurement report events are recorded in a log of their own. The user/manager may later on check this log to find out the history of a certain measurement. The user may also, using the get_measurement_report function, ask MESH for the last measurement value received from a certain measurement).

A measurement object may also choose to report to MESH only in certain circumstances, e.g., if the user wants to specify a measurement object that just supervises a critical threshold value; this case is described in more detail below, in the section "Threshold and Tide-mark Support".

The log used to log meshMeasurementReport events (and also the other logs used by MESH) is described below, in the section "Alarms, Events and Logs".

2.8 Threshold and Tide-mark Support

2.8.1 Thresholds

The Measurement Handler supports threshold setting and control. Thresholds are a mechanism used for generation notifications, caused by changes in measured values. To avoid repeated triggering of notifications, there should be small oscillations around a threshold value, the Measurement Handler supports a so-called hysteresis mechanism.

thresh
An upper threshold.

From the Measurement Handler point of view, there are two kinds of thresholds: upper thresholds and lower thresholds, the difference being whether the notification shall be triggered when the measurement value exceeds the threshold value or when it falls below the threshold value.

Regardless of type, each threshold consists of two values, in this document they are denoted Thresh1 and Thresh2. On a time-scale, Thresh1 shall be the value first encountered, as seen in the figure above.

For each measurement object, an infinite number of thresholds may be set. To distinguish between different thresholds within a given measurement object, each threshold has to have a unique identifier, assigned by the user. (An identifier may be re-used for another measurement object, and it is only within the measurement object the identifier has to be unique!)

When setting a threshold, the user may decide whether it shall be disabled or enabled. Only enabled thresholds can generate threshold notifications.

When the Measurement Handler receives a measurement value report, it compares the measurement value to each set threshold value. If the received value exceeds (or falls below, in the lower threshold case) the Thresh1 value, an alarm is sent to EVA.
Should the received value fall below (or exceed, in the lower threshold case) the Thresh2 value, and this threshold previously has generated an alarm, this alarm in EVA will be cleared.

When reseting a measurement object, all threshold alarms (concerning this measurement object) sent to EVA will be cleared; the next received measurement value will then be compared to the thresholds set, according to the above description.

The user may also choose to personally implement the threshold handling. For that purpose, all threshold handling functions (with the exception of the list_thresholds function) will cause MESH to call a corresponding function in the measurement type interface (see the mesh Reference Manual for complete details) and forward the same information it received. The user may then choose to silently compare measurement values to the thresholds set internally in the measurement object, and not take any action until a threshold has been triggered. The measurement object may then either send a notification directly to the manager, or just send a measurement report to MESH. The same threshold will then be triggered in MESH, resulting in an alarm being sent to EVA.

2.8.2 Tide-marks

A tide-mark is a mechanism that records the maximum or minimum value reached during a measurement period. A tide-mark is read-only, however it may be reset, as we will see below.

There are two kinds of tide-marks:

The Measurement Handler supports, for each measurement object, both a maximum and a minimum tide-mark.

There are three components in each tide-mark:

If reset of a measurement object is ordered, both the maximum and minimum tide-mark associated with the measurement object will be reset. This is done in the following way:

The tide-marks may be read using the report_tidemarks function.

2.9 The Watchdog

The Measurement Handler supports a "watchdog", that supervises the total number of measurement types registered, and the total number of created measurement objects. If any of these numbers exceed the maximum allowed number, a meshTooManyTypes or meshTooManyMeasurements alarm is sent to EVA (see also below).

Initially an infinite number of measurement types and measurement objects are allowed, but the user may alter this, using the set_watchdog function, see the mesh Reference Manual for complete details.

2.10 Alarms, Events and Logs

2.10.1 Alarms

The following alarms may be sent to EVA:

2.10.2 Events

The following events may be sent to EVA:

2.10.3 Logs

The following logs are used by the Measurement Handler:

Should any of the logs mentioned above not be available, the default log (that EVA is started with) will be used instead.

By default, each log has a filter that ensures that only the required elements are logged. MESH supports the switching of logs, should the user want to use their own filter function (for extended functionality). The functions available are set_alarm_filter, set_event_filter and set_measurement_filter, please see the mesh Reference Manual for further details. We recommend cross referencing with the eva Reference Manual.
(Should the user decide later to reset the filters to the original settings, the functions reset_alarm_filter, reset_event_filter and reset_measurement_filter are available.)


Copyright © 1991-98 Ericsson Telecom AB