mesh

MODULE

mesh

MODULE SUMMARY

Client API for Mesh.

DESCRIPTION

This module contains the client API to the Measurement Handler application Mesh. Mesh is a distributed global application, which means that clients can access the Mesh functionality from any connected node. There is a globally registered server called mesh_server to which all requests are sent. Currently all functions (except the measurement_report and measurement_terminated functions) are synchronous. This means that the function call fails if no acknowledgment is returned by the server. Should this happen, the client application has to decide what actions to take. (It may, for example, wait a few seconds for another node to take over the Mesh application, and then try again.)

Mesh stores data about measurement types and measurement objects in the Mnesia tables mesh_type and mesh_meas, respectively. They are replicated to disk and RAM on each node that may run the Mesh application.

Mesh uses an EVA functionality to send and to log generated events and alarms. The logs used can be examined by a manager at a later time.
However, the configuration and start of EVA is left to the client application programmer, see section Requirements below. Mesh does not supervise EVA, which essentially means that the client application programmer must be aware of EVA. For performance reasons, it is desired that EVA runs on the same node as the Measurement Handler to reduce internal traffic.

Commonly used statistical functions may be found in the module mesh_lib.

Starting and Stopping Mesh

The Mesh application is controlled through the application module API; Mesh is started by the function call application:start(mesh),
and stopped by the function call
application:stop(mesh).

Requirements

The Mesh application requires the following applications to be started:

• SASL


• Mnesia


• EVA



When starting Mnesia, a schema must be created on each of the nodes where the Mesh application will be running; see for example function mnesia:create_schema/1.

Before EVA is started, the Mnesia tables needed by the basic EVA service and the EVA log service have to be created on each node where the Mesh application will be running; see example function eva_sup:create_tables_log/1.
Also, EVA should be started with a default log, which first must be created, see for example functions disk_log:open/1 and eva:start_link_log/1.

Before Mesh is started, the Mnesia tables needed by the Mesh application have to be created on each of the nodes where the Mesh application is supposed to be will be running; see example function mesh:create_tables/1.

Call back Module Usage

While the Measurement Handler application takes care of common tasks, user dependent, implementation specific issues are handled through the measurement type interface modules. These modules are (through the measurement type registration) associated with a specific measurement type. When Mesh is ordered to perform certain tasks, concerning a certain measurement type, one or more of the functions in the associated interface module may be called.

The functions that have to be present in each interface module are (please also see the section Interface Module Functions):

• init/1


• terminate/1


• create_measurement/3


• delete_measurement/3


• start_measurement/3


• stop_measurement/2


• reset_measurement/3



The following functions are optional for each interface module:

• set_upper_threshold/5


• set_lower_threshold/5


• remove_threshold/3


• enable_threshold/3


• disable_threshold/3



The purpose of these latter functions are to provide the user with the possibility to implement the threshold supervising functionality. For example, a measurement object may just supervise a measurement value, reporting nothing until a threshold has been triggered. The measurement object in question may then report directly to the manager or EVA. Alternatively, the measurement object can send a normal measurement report to Mesh, containing the measurement value that triggered the threshold. In the latter case the threshold set in Mesh will be triggered, and an alarm will be sent to EVA.

The figure below describes how function calls to Mesh result (or may result) in calls to the corresponding measurement type interface.

Sometimes a function may be called more than once, for example, the delete_measurement in the interface module is called for each measurement object. This is not indicated in the figure. Similarly, sometimes a function may not be called, depending on the context; this is also not indicated.

      
Mesh                              Interface Module
----                              ----------------
      
mesh:register_type        ---->   IM:init/1


mesh:unregister_type      ---->   IM:delete_measurement
                                  IM:terminate


mesh:lock_type            ---->   IM:delete_measurement


mesh:create_measurement   ---->   IM:create_measurement


mesh:delete_measurement   ---->   IM:delete_measurement


mesh:revive_measurement   ---->   IM:create_measurement


mesh_start_measurement    ---->   IM:start_measurement


mesh:stop_measurement     ---->   IM:stop_measurement


mesh:reset_measurement    ---->   IM:reset_measurement


mesh:set_upper_threshold  ---->   IM:set_upper_threshold


mesh:set_lower_threshold  ---->   IM:set_lower_threshold


mesh:remove_threshold     ---->   IM:remove_threshold


mesh:enable_threshold     ---->   IM:enable_threshold


mesh:disable_threshold    ---->   IM:disable_threshold

    

Measurement Responsible Processes

A Measurement Responsible Process (MRP) is one or more processes enabling communication between the measurement type interface and the actual processes implementing, eg. measurement objects. Since the measurement type interface is stateless, it has to be supplied with the identifiers of these processes, which is done by the Measurement Handler, whenever it calls a measurement type interface function. The measurement type interface must ensure the correct process is contacted.

Basically, there are two MRP design possibilities:

• each measurement object is its own MRP.


• one process, working as a server, keeps track of one or more measurement objects, forwarding the messages received to the correct measurement object/process.



Whatever alternative has been chosen, an MRP has the following four responsibilities:

• supervise one or more measurement objects.


• map the measurement object identifier to the correct process identifier, thereby enabling communication with measurement objects.


• keep track of the available resources, mapping new measurement objects to the correct resource.


• ensure Mesh that the user supplied supervision scheme is still working. That is, Mesh only supervises the MRP (and the node it resides on); the MRP will supervise the individual measurement objects, reporting to Mesh whenever one of them gets disabled (and order revival, if that is desired).



Should an MRP terminate, Mesh will assume that the corresponding measurement objects will also terminate. This implies that MRPs have to be very robust, ie. they have to trap exits, even internally.

Events and Alarms

The alarms that may be sent to EVA are:

• meshThresholdTriggered. This alarm is sent whenever a threshold has been triggered. The alarm class is qos, and the severity indeterminate. Other fields of interest in the alarm are:

  Field        Value
  -----        -----
  sender       mesh_server
  cause        {upper_threshold_triggered, {value, number()}}  |
               {lower_threshold_triggered, {value, number()}}
  extra        {{meas, MeasId}, {id, ThreshId}}
          



• meshTooManyTypes. This alarm is sent by the watchdog if the total number of registered measurement types exceeds the maximum number allowed. The alarm class is processing, and the severity warning. Other fields of interest in the alarm are:

  Field        Value
  -----        -----
  sender       mesh_server
  cause        {{allowed,number()},{currently,number()}}
  extra        ""
          



• meshTooManyMeasurements. This alarm is sent by the watchdog if the total number of created measurement objects exceeds the maximum number allowed. The alarm class is processing, and the severity warning. Other fields of interest in the alarm are:

  Field        Value
  -----        -----
  sender       mesh_server
  cause        {{allowed,number()}, {currently,number()}} 
  extra        ""
            



• meshTypeCapacityExceeded. This alarm is sent when the number of measurement objects belonging to a certain measurement type exceeds the measurement type capacity. The alarm class is processing, and the severity warning. Other fields of interest in the alarm are:

  Field        Value
  -----        -----
  sender       mesh_server
  cause        {{type,TypeId}, {allowed,number()}, 
                {currently,number()}}
  extra        "Capacity decreased"
            




The events that may be sent to EVA are:

• meshTypeFailure. This event is sent whenever a measurement type MRP has terminated. The extra field in the event contains the following information:
  {MeasId, FailureReason, FailureTime}.


• meshMeasurementTerminated. This event is sent whenever the Measurement Handler has noticed that a measurement object has been disabled. The extra field in the event contains the following information:
  {MeasId, TypeId, TerminationReason, TerminationTime}.


• meshNodeUp. This event is sent whenever a node (where an MRP is residing), comes up again after having been down. The extra field in the event contains the following information:
  {NodeName, ConnectionTime}.


• meshNodeDown. This event is sent whenever a node (where an MRP is residing),goes down. The extra field in the event contains the following information:
  {NodeName, CrashTime}.


• meshTypeUnconnected. This event is sent when the status of an MRP is indeterminate, for example when the connection to the corresponding node has been lost, but no crash report has been received. The extra field in the event contains the following information:
  {TypeId, nodedown, Time}.


• meshMeasurementUnconnected. This event is sent when the status of a measurement object is indeterminate, for example when the connection to the corresponding node has been lost, but no crash report has been received. The extra field in the event contains the following information:
  {MeasId, TypeId, nodedown, Time}.


• meshTypeConnected. This event is sent when a previously unconnected MRP reconnects. For example, if the node where the MRP had resided is reconnected, and the MRP is found to still be present. The extra field in the event contains the following information:
  {TypeId, nodeup, ConnectionTime}.


• meshMeasurementConnected. This event is sent when a previously unconnected measurement object reconnects. For example, if the node where the measurement object resided is reconnected, and the measurement object is found to still be present. The extra field in the event contains the following information:
  {MeasId, TypeId, nodeup, ConnectionTime}.


• meshMeasurementReport. This event is sent whenever the Measurement Handler receives a measurement report from any measurement object. The extra field in the event contains the following information:
  {{name,MeasId}, {value,number()}, {time,Time}, {info,MeasInfo}}.

Adaptations

The Mesh services are management protocol independent. However, for a manager to access the Mesh services, a management protocol is required, ie. adaptations must be written, mapping Mesh services to the desired protocol.

EXPORTS

create_tables(NodeList) -> Result

Types:
NodeList = [NodeName]
NodeName = atom()
Result = ok | {error, Reason}
Reason = term()

Creates the Mnesia tables the Mesh application needs, with disc and RAM replicas on every node specified in NodeList.
This function will only be called once, before starting the Mesh application.

Note: it is important that the schema created is consistent with the specified list of nodes.

register_type(TypeId, Extra, InterfaceMod, NofInst) -> Result
register_type(TypeId, Extra, InterfaceMod, NofInst, AdminState) -> Result

Types:
TypeId = atom()
Extra = term()
InterfaceMod = atom()
NofInst = integer()
AdminState = unlocked | shutting_down | locked
Result = {registered, TypeId} | {reregistered, TypeId} | {error, Reason}
Reason = term()

This function registers (or reregisters) a measurement type in the Measurement Handler. The main purpose of this function is to associate the InterfaceMod interface module with the TypeId identifier. (It should be noted that the TypeId identifier cannot be reused, since it solely identifies a measurement type, and therefore must be unique.)
The Extra argument is used for the benefit of the user, ie. it must contain all information describing the measurement type, but this information will only be used by the manager and never forwarded to any MRP or measurement object.
The registration function will also call the init/1 function in the interface module, thereby enabling the user to perform necessary initializations. (The init function may, for example, start a MRP.)
The NofInst parameter sets the measurement type capacity, i.e., the number of measurement objects (belonging to the specified measurement type) that may be created.
The AdminState sets the initial administrative state of the the measurement type.

It is possible to re-register a measurement type, provided that the same interface module is specified. This allows changes in capacity, e.g., the number of measurement objects that may be created.
However, in the case of a capacity decrease, no measurement objects will be disabled, but an alarm will be sent to EVA.
When re-registration has been approved by Mesh, the init/1 function in the interface module will once again be called to restart possible existing MRPs.

Should the type capacity be exceeded, a meshTypeCapacityExceeded alarm will be sent to EVA. Once the number of existing measurement objects falls below the type capacity, the alarm will be cleared.

unregister_type(TypeId) -> Result
unregister_type(TypeId, StopArgs) -> Result

Types:
TypeId = atom()
StopArgs = [term()]
Result = {unregistered, TypeId} | {error, Reason}
Reason = term()

This function unregisters a measurement type in the Measurement Handler. Any existing measurement objects will be deleted, and the interface module will no longer be associated with the TypeId identifier. For each existing measurement object, the delete_measurement/3 function in the measurement type interface will be called, with StopArgs as one of the arguments. Finally, the terminate1 function in the measurement type interface will be called; this is to enable clean-up actions.
Note: The StopArgs are only passed on to the delete_measurement function, not to the terminate function!

list_types() -> Result

Types:
Result = [TypeInfo] | {error, Reason}
TypeInfo = {TypeId, [{extra,Extra}, {interface_mod,InterfaceMod}, {instances,CurrNofInst}, {max_instances,MaxNofInst}, {administrative_state,CurrAdminState}]}
TypeId = atom()
Extra = term()
InterfaceMod = atom()
CurrNofInst = integer()
MaxNofInst = integer()
CurrAdminState = unlocked | shutting_down | locked
Reason = term()

This function lists all the measurement types currently registered in the Measurement Handler, including information about settings and the current state of each of the types.

lock_type(TypeId) -> Result
lock_type(TypeId, StopArgs) -> Result

Types:
TypeId = atom()
StopArgs = [term()]
Result = {locked, TypeId} | {error, Reason}
Reason = term()

This function locks the specified measurement type, ie. prevents further usage until it becomes unlocked. After locking the measurement type, it will be impossible to create any new measurement objects, and existing measurement objects will be deleted, using the delete_measurement/3 function in the measurement type interface; the StopArgs will be passed on to this latter function, thereby enabling soft measurement object termination. (Unless otherwise stated, StopArgs will be set to the empty list.)

unlock_type(TypeId) -> Result

Types:
TypeId = atom()
Result = {unlocked, TypeId} | {error, Reason}
Reason = term()

This function unlocks the specified measurement type. Once activated, it is possible to create measurement objects (provided that the type capacity is not exceeded).

shut_down_type(TypeId) -> Result

Types:
TypeId = atom()
Result = {shutting_down, TypeId} | {locked, TypeId} | {error, Reason}
Reason = term()

This function shuts down the specified measurement type. Once effective, no measurement objects can be created and measurement objects cannot be revived, once they have been disabled.
Existing measurement objects are allowed to continue to exist, but once all measurement objects (belonging to the specified type) have been disabled or deleted, the measurement type is automatically locked.

create_measurement(MeasId, TypeId, Extra, ResId) -> Result
create_measurement(MeasId, TypeId, Extra, ResId, AdminState) -> Result
create_measurement(MeasId, TypeId, Extra, ResId, AdminState, StartArgs) -> Result

Types:
MeasId = atom()
TypeId = atom()
Extra = term()
ResId = term()
AdminState = started | stopped
StartArgs = [term()]
Result = {created, MeasId} | {error, Reason}

This function creates a new measurement object belonging to the specified measurement type, provided the type capacity is not exceeded. The create_measurement/5 function in the type interface will be called, with some of the supplied arguments, as a result of this function call. Please see below, and the section relating to Interface Module Functions.
The MeasId identifier, during the lifetime of the object, is used to uniquely identify the object. It follows that there can only be one measurement object with a unique measurement identifier.
The TypeId identifier tells the measurement type which interface module to use when creating the object and communicating with it; the TypeId identifier is the same as was given when the measurement type was registered.
The Extra argument is any additional information about the measurement object the user chooses to supply; this information is not forwarded to the measurement object itself.
The ResId argument is any term telling the new measurement object which resources to use; the interpretation of this term is solely a user issue!
The AdminState tells the original administrative state of the new measurement object, ie. whether it should be started or stopped. The default administrative state is started.
StartArgs is any list of terms the user wants to forward to the new measurement object as start arguments, setting the original state, eg. the sampling interval and the algorithm, to use when evaluating samples are collected. Unless specified by the user, StartArgs will be set to the empty list when forwarded to the measurement object.

Note: the StartArgs list has to have the same format in the functions create_measurement, start_measurement and reset_measurement, see the description of function revive_measurement for further information.

delete_measurement(MeasId) -> Result
delete_measurement(MeasId, StopArgs) -> Result

Types:
MeasId = atom()
StopArgs = [term()]
Result = {deleted, MeasId} | {error, Reason}

This function deletes the specified measurement object. As a result of this function call, the delete_measurement/3 function in the measurement type interface will be called, with some of the supplied arguments. Please see below and section Interface Module Functions for further information.
MeasId is the measurement identifier used to identify the measurement object.
StopArgs is any list of terms the user wants to forward to the measurement object, thereby enabling a soft termination; the default is the empty list.
Note: it is the responsibility of the user to ensure that all resources and applications used by the measurement object are terminated and/or freed in a controlled manner when an object is terminated.

measurement_terminated(MeasId, Reason) -> ok

Types:
MeasId = atom()
Reason = term()

This function is used to inform the Measurement Handler about terminated/disabled measurement objects. Since the Measurement Handler only supervises the Measurement Responsible Processes (MRPs), it is strictly necessary that each MRP reports to Mesh about terminated/disabled measurement objects. The operation of the Measurement Handler is not guaranteed, should the MRPs neglect this reporting.
Should the measurement object itself be an MRP, not supervising any other measurement objects, the Measurement Handler will notice automatically (since it is linked to each MRP) if the measurement object terminates, and no specific reporting is needed in this case. In all other cases the MRPs must report each measurement object termination to Mesh, using this function.

list_measurements(TypeId) -> Result

Types:
TypeId = atom()
Result = [MeasInfo] | {error, Reason}
MeasInfo = {MeasId, [{extra,Extra}, {resources,ResId}, {initial_arguments,StartArgs}, {operability_state,CurrOperState}, {administrative_state,CurrAdminState}]}
MeasId = atom()
Extra = term()
ResId = term()
StartArgs = [term()]
CurrOperState = enabled | disabled
CurrAdminState = started | stopped
Reason = term()

This function lists all measurement objects belonging to the specified measurement type. The listing includes information about the resources used, the initial state (ie. the last known start arguments), the current operability state (ie. whether the measurement object is enabled or disabled), and the administrative state (ie. whether the measurement object is started or stopped).

Note: the StartArgs is the list of start arguments as given in any (ie. the latest) of the functions create_measurement, start_measurement and reset_measurement.

revive_measurement(MeasId) -> Result

Types:
MeasId = atom()
Result = {revived, MeasId} | {error, Reason}
Reason = term()

This function tries to revive a disabled measurement object, using the last known settings, including set thresholds.

Please noted that the last known start arguments will be used when trying to revive a measurement object. These start arguments consist of the latest known StartArgs list; this list may be specified in any of these three function calls:

• create_measurement


• start_measurement


• reset_measurement



Therefore, the StartArgs list must have the same format in these three functions.

The last step in the revival procedure, resetting the measurement object, is ordered by Mesh to ensure consistent states in the Measurement Handler and the measurement object.

start_measurement(MeasId) -> Result
start_measurement(MeasId, StartArgs) -> Result

Types:
MeasId = atom()
StartArgs = [term()]
Result = {started, MeasId} | {error, Reason}
Reason = term()

This function orders a specified measurement object to start running (ie. to enter a working state). As a result of this function call, the start_measurement/3 function in the measurement type interface will be called, with some of the supplied arguments. Please see below and section Interface Module Functions for further information. No resetting takes place, with the exception of thresholds set: if previously triggered, they are restored to an un-triggered state. (This applies only to the Measurement Handler, if the user has implemented thresholds in the measurement object, it is their own responsibility to ensure they are set to a consistent state.)

MeasId is the measurement identifier used to identify the measurement object.
StartArgs is any list of terms the user wants to forward to the measurement object, thereby changing its internal state. The default is set to the empty list.


Note: the StartArgs list must have the same format in the functions create_measurement, start_measurement and reset_measurement, see the description of function revive_measurement for further information.

stop_measurement(MeasId) -> Result

Types:
MeasId = atom()
Result = {stopped, MeasId} | {error, Reason}
Reason = term()

This function orders the specified measurement object to stop running and become idle. As a result of this function call, the stop_measurement/2 function in the measurement type interface will be called, please see section Interface Module Functions. No resetting takes place in the Measurement Handler, and all thresholds set remain set. However, no measurement reports will be accepted from a stopped measurement object.

MeasId is the measurement identifier used to identify the measurement object.

reset_measurement(MeasId) -> Result
reset_measurement(MeasId, StartArgs) -> Result

Types:
MeasId = atom()
StartArgs = [term()]
Result = {reset, MeasId} | {error, Reason}
Reason = term()

This function orders the specified measurement object to reset its internal state, and resets in the Measurement Handler all measurement information stored about the measurement object. All thresholds set will remain set, but if previously triggered, they are restored to an un-triggered state.
As a result of this function call, the reset_measurement/2 function in the measurement type interface will be called, please see section Interface Module Functions.

MeasId is the measurement identifier used to identify the measurement object.
StartArgs is any list of terms the user wants to forward to the measurement object, thereby changing its internal state. Default is set to the empty list.


Note: the StartArgs list has to have the same format in the functions create_measurement, start_measurement and reset_measurement, see the description of function revive_measurement for further information.

measurement_report(MeasId, Value, TimeStamp) -> ok
measurement_report(MeasId, Value, TimeStamp, MeasInfo) -> ok

Types:
MeasId = atom()
Value = number()
TimeStamp = term()
MeasInfo = term()

This function is used to report a measurement value, obtained by any measurement object, to the Measurement Handler. The Measurement Handler will update the tidemarks and compare the received value to the thresholds set, and when required, forward the measurement report to EVA. The measurement value will also be stored (internally) in the Measurement Handler, until a new measurement report is received from the same measurement object.

MeasId is the measurement identifier used to identify the measurement object.
Value is the measurement value the measurement object has obtained.
TimeStamp is any (user specified) term describing the time and date the measurement value and/or report was obtained or sent.
MeasInfo is any (user specified) term describing the measurement report and/or providing extra information to the manager.

get_measurement_report(MeasId) -> Result

Types:
MeasId = atom()
Result = {MeasId, Value, TimeStamp, MeasInfo} | {error, Reason}
Value = number()
TimeStamp = term()
MeasInfo = term()
Reason = term

This function gets the most recently reported measurement value from a specified measurement object.

MeasId is the measurement identifier used to identify the measurement object.
Value is the measurement value reported by the measurement object.
TimeStamp is any (user specified) term describing the time and date the measurement value and/or report was obtained or sent.
MeasInfo is any (user specified) term describing the measurement report and/or providing extra information to the manager.

set_upper_threshold(MeasId, ThreshId, Value) -> Result
set_upper_threshold(MeasId, ThreshId, Value, Status) -> Result

Types:
MeasId = atom()
ThreshId = atom()
Value = number() | {ValueHi, ValueLo}
ValueHi = ValueLo = number()
Status = enabled | disabled
Result = {threshold_set, {MeasId,ThreshId}} | {error, Reason}
Reason = term()

This function sets an upper threshold in the Measurement Handler. Thus, when a threshold has been exceeded an alarm will be triggered. The specified measurement object also receives the threshold information, using the measurement type interface function set_upper_threshold/5, to allow the user to implement the threshold functionality on their own. However, it should be noted that the set_upper_threshold function in the measurement type interface is purely optional. The Measurement Handler will not crash, should the function not be present, because, Mesh will not check the return value.

MeasId is the measurement identifier used to identify the measurement object.
ThreshId is the threshold identifier, which is used together with the measurement identifier to uniquely identify a threshold. Therefore, two different measurement objects may use the same threshold identifier.
Value is a single number or a pair of numbers, specifying the threshold level. In the case of a pair of numbers, the first one is assumed to specify the level (value) any measurement value has to exceed in order for the threshold to be triggered. The second number is the value any measurement value has to fall below in order for a previously triggered threshold to be cleared (untriggered).
If only one value is given, the two levels are assumed to be the same.
Status specifies whether the threshold will be enabled or disabled when created. Only enabled thresholds can be triggered.

A triggered threshold will issue a meshThresholdTriggered alarm to EVA. When the threshold becomes untriggered, the alarm is cleared.

set_lower_threshold(MeasId, ThreshId, Value) -> Result
set_lower_threshold(MeasId, ThreshId, Value, Status) -> Result

Types:
MeasId = atom()
ThreshId = atom()
Value = number() | {ValueLo, ValueHi}
ValueHi = ValueLo = number()
Status = enabled | disabled
Result = {threshold_set, {MeasId,ThreshId}} | {error, Reason}
Reason = term()

This function sets a lower threshold in the Measurement Handler. Therefore, an obtained measurement value must fall below the lower threshold in order for the threshold alarm to be triggered. The specified measurement object also receives the threshold information, using the measurement type interface function set_lower_threshold/5, should the user want to implement the threshold functionality on their own. However, it should be noted that the set_lower_threshold function in the measurement type interface is purely optional. The Measurement Handler will not crash, should the function not be present, because, Mesh does not check the return value.

MeasId is the measurement identifier used to identify the measurement object.
ThreshId is the threshold identifier, which is used together with the measurement identifier to uniquely identify a threshold. Thus, two different measurement objects may use the same threshold identifier.
Value is a single number or a pair of numbers, specifying the threshold level. In the case of a pair of numbers, the first one is assumed to specify the level (value) any measurement value has to fall below in order for the threshold to be triggered. The second number is the value any measurement value has to exceed in order for a previously triggered threshold to be cleared (untriggered).
If only one value is given, the two levels are assumed to be the same.
Status specifies whether the threshold will be enabled or disabled when created. Only enabled thresholds can be triggered.

A triggered threshold will activate a meshThresholdTriggered alarm to EVA. When the threshold becomes untriggered, the alarm is cleared.

remove_threshold(MeasId, ThreshId) -> Result

Types:
MeasId = atom()
ThreshId = atom()
Result = {threshold_removed, {MeasId,ThreshId}} | {error, Reason}
Reason = term()

This function removes a specified threshold from the specified measurement object. The specified measurement object also receives the threshold removal order, via the measurement type interface function remove_threshold/3, should the user want to implement the threshold functionality on his own. However, it should be noted that the remove_threshold function in the measurement type interface is purely optional. The Measurement Handler will not crash, should the function not be present because, Mesh does not check the return value.

MeasId is the measurement identifier used to identify the measurement object.
ThreshId is the threshold identifier, which is used together with the measurement identifier to uniquely identify a threshold.

remove_thresholds(MeasId) -> Result

Types:
MeasId = atom()
Result = {thresholds_removed, MeasId} | {error, Reason}
Reason = term()

This function removes all existing thresholds from the specified measurement object. The specified measurement object also receives the threshold removal order, via (repetitive calls to) the measurement type interface function remove_threshold/3, should the user want to implement the threshold functionality on their own. However, it should be noted that the remove_threshold function in the measurement type interface is purely optional. The Measurement Handler will not crash, should the function not be present because, Mesh will not even check the return value.

MeasId is the measurement identifier used to identify the measurement object.

list_thresholds(MeasId) -> Result

Types:
MeasId = atom()
Result = {MeasId, {upper_thresholds,[ThreshInfo]}, {lower_thresholds,[ThreshInfo]}} | {error, Reason}
ThreshInfo = {ThreshId, Status, Value}
ThreshId = atom()
Status = enabled | disabled
Value = number() | {number(), number()}
Reason = term()

This function lists all existing thresholds set for the specified measurement object. The thresholds are divided into the two categories upper thresholds and lower thresholds. For each threshold, the current status is specified (enabled or disabled), as well as the threshold value(s) set.

MeasId is the measurement identifier used to identify the measurement object.

enable_threshold(MeasId, ThreshId) -> Result

Types:
MeasId = atom()
ThreshId = atom()
Result = {threshold_enabled, {MeasId,ThreshId}} | {error, Reason}
Reason = term()

This function enables the specified threshold. Only enabled thresholds may be triggered. The specified measurement object also receives the enable threshold order, via the measurement type interface function enable_threshold/3, should the user want to implement the threshold functionality on his own. However, it should be noted that the enable_threshold function in the measurement type interface is purely optional. The Measurement Handler will not crash, should the function not be present because, Mesh will not even check the return value.

MeasId is the measurement identifier used to identify the measurement object.
ThreshId is the threshold identifier, which is used together with the measurement identifier to uniquely identify a threshold.

disable_threshold(MeasId, ThreshId) -> Result

Types:
MeasId = atom()
ThreshId = atom()
Result = {threshold_disabled, {MeasId,ThreshId}} | {error, Reason}
Reason = term()

This function disables a specified threshold. Disabled thresholds cannot be triggered. The specified measurement object also receives the disable threshold order, via the measurement type interface function disable_threshold/3, should the user want to implement the threshold functionality on his own. However, it should be noted that the disable_threshold function in the measurement type interface is purely optional The Measurement Handler will not crash, should the function not be present because, Mesh will not even check the return value.

MeasId is the measurement identifier used to identify the measurement object.
ThreshId is the threshold identifier, which is used together with the measurement identifier to uniquely identify a threshold.

report_tidemarks(MeasId) -> Result

Types:
MeasId = atom()
Result = {MeasId, TypeId, MaxTideMark, MinTideMark} | {error, Reason}
TypeId = atom()
MaxTideMark = {max_tidemark, [{current,CurrValue}, {previous,PrevValue}, {reset,ResetTime}]}
MinTideMark = {min_tidemark, [{current,CurrValue}, {previous,PrevValue}, {reset,ResetTime}]}
CurrValue = PrevValue = number()
ResetTime = {Date, Time}
Date = {Year, Month, Day}
Time = {Hour, Minute, Second}
Year = Month = Day = Hour = Minute = Second = int()
Reason = term()

This function reports the current values of the maximum and minimum tide-marks associated with the specified measurement object.
Each tide-mark contains the maximum (or minimum) value reached since the last time the tide-mark was reset, and also the maximum (or minimum) value reached in the period prior to the last reset.

MeasId is the measurement identifier used to identify the measurement object.
TypeId is the measurement type identifier.

Note: the time is given using the Universal Coordinated Time time zone (sometimes denoted Greenwich Mean Time or GMT).

reset_tidemarks(MeasId) -> Result

Types:
MeasId = atom()
Result = {tidemarks_reset, MeasId} | {error, Reason}
Reason = term()

This function resets the maximum and minimum tide-marks associated with a specified measurement object. Resetting consists of storing the current value as the previous current value, replacing the current value with the atom 'undefined', and noting the reset time.

MeasId is the measurement identifier used to identify the measurement object.

watchdog_setup(NofTypes, NofMeas) -> Result

Types:
NofTypes = NofMeas = int()
Result = ok | {error, Reason}
Reason = term()

This functions handles the set-up of the Measurement Handler watchdog. The purpose of the watchdog is to keep track of the total number of measurement types registered, as well as the total number of measurement objects created. Should the number of types exceed the number specified using this function, the alarm meshTooManyTypes is sent to EVA, however, the alarm meshTooManyMeasurements is sent if the number of allowed measurement objects is exceeded.
It should be noted that the alarms issued are just warnings and it is still possible to register new measurement types, and also to create new measurement objects (provided that the associated measurement type capacity is not exceeded).

Functions used to control the various logs

Mesh uses three logs:

• alarms are logged in the mesh_alarms log.


• events are logged in the mesh_events log.


• measurement reports are logged in the mesh_measurements log.



The user may freely choose to replace the filter function used by each log, using a user defined filter function instead, or to restore the original filter function.

EXPORTS

set_alarm_filter(Func) -> Result

Types:
Func = {Mod, Fcn, Args}
Mod = Fcn = atom()
Args = [term()]
Result = ok | {error, Reason}
Reason = term()

This function replaces the default filter with the user specified. (The default filter ensures that only alarms are recorded in this log, but does not perform any other action.)

set_event_filter(Func) -> Result

Types:
Func = {Mod, Fcn, Args}
Mod = Fcn = atom()
Args = [term()]
Result = ok | {error, Reason}
Reason = term()

This function replaces the default filter with a user specified filter. The default filter ensures that only events, with the exception of measurement report events, are logged in this log, but will not perform any other action.

set_measurement_filter(Func) -> Result

Types:
Func = {Mod, Fcn, Args}
Mod = Fcn = atom()
Args = [term()]
Result = ok | {error, Reason}
Reason = term()

This function replaces the default filter with the user specified filter. The default filter ensures that only measurement report events are recorded in this log, but will not perform any other action.

reset_alarm_filter() -> Result

Types:
Result = ok | {error, Reason}
Reason = term()

This function restores the filter used to the default one.

reset_event_filter() -> Result

Types:
Result = ok | {error, Reason}
Reason = term()

This function restores the filter used to the default one.

reset_measurement_filter() -> Result

Types:
Result = ok | {error, Reason}
Reason = term()

This function restores the filter used to the default one.

Interface Module Functions

The Measurement Handler application calls a number of functions in each measurement type interface module. Only if explicitly stated below is it optional to export a specific function.
The absence of a required function will not cause the Measurement Handler to crash, but it will severely limit the possibilities when handling the corresponding measurement types and measurement objects.

EXPORTS

InterfaceMod:init(TypeId) -> Result

Types:
TypeId = atom()
Result = MRP | {error, Reason}
MRP = pid() | undefined
Reason = term()

This function takes care of the user application specific initialization. Should there be an MRP responsible for a number of measurement objects, it has to be started by this function, in which case the PID of the MRP will have the return value of the function. If no MRP is started, the atom 'undefined' will be returned.

InterfaceMod:terminate(MRP) -> Result

Types:
MRP = pid() | undefined
Result = ok | {error, Reason}
Reason = term()

This function is responsible for user specific termination and clean-up. If resources have to be freed, and/or applications terminated, this function has to handle it.

The MRP argument is the identifier once returned from the InterfaceMod:init function.

InterfaceMod:create_measurement(MRP1, TypeId, MeasId, ResId, StartArgs) -> Result

Types:
MRP1 = pid() | undefined
TypeId = atom()
MeasId = atom()
ResId = term()
StartArgs = [term()]
Result = MRP2 | {error, Reason}
MRP2 = pid()
Reason = term()

This function handles the actual creation of a measurement object. It is the user's responsibility to make sure that the created object uses the correct resources, and performs measurements as intended.

The MRP1 argument is the identifier once returned from the InterfaceMod:init function. This identifier may be a pid, or it may be the atom 'undefined'. However, the return value of the function has to be a PID, namely the process identifier of the process supervising the measurement object (which actually may be the measurement object itself).

InterfaceMod:start_measurement(MRP, MeasId, StartArgs) -> Result

Types:
MRP = pid()
MeasId = atom()
StartArgs = [term()]
Result = ok | {error, Reason}
Reason = term()

This function handles a measurement object start.

The MRP argument is the identifier returned from the InterfaceMod:create_measurement function.

InterfaceMod:stop_measurement(MRP, MeasId) -> Result

Types:
MRP = pid()
MeasId = atom()
Result = ok | {error, Reason}
Reason = term()

This function handles a measurement object stop.

The MRP argument is the identifier returned from the InterfaceMod:create_measurement function.

InterfaceMod:reset_measurement(MRP, MeasId, StartArgs) -> Result

Types:
MRP = pid()
MeasId = atom()
StartArgs = [term()]
Result = ok | {error, Reason}
Reason = term()

This function is responsible for the resetting of a measurement object.

The MRP argument is the identifier returned from the InterfaceMod:create_measurement function.

InterfaceMod:delete_measurement(MRP, MeasId, StopArgs) -> Result

Types:
MRP = pid()
MeasId = atom()
StopArgs = [term()]
Result = ok | {error, Reason}
Reason = term()

This function deletes the specified measurement object.

The MRP argument is the identifier returned from the InterfaceMod:create_measurement function.

InterfaceMod:set_upper_threshold(MRP, MeasId, ThreshId, Value, Status) -> Result

Types:
MRP = pid()
MeasId = atom()
ThreshId = atom()
Value = number() | {ValueHi, ValueLo}
ValueHi = ValueLo = number()
Status = enabled | disabled
Result = ok | {error, Reason}
Reason = term()

This function sets an upper threshold in a measurement object.

The MRP argument is the identifier returned from the InterfaceMod:create_measurement function.

Note: the existence of this function is optional!

InterfaceMod:set_lower_threshold(MRP, MeasId, ThreshId, Value, Status) -> Result

Types:
MRP = pid()
MeasId = atom()
ThreshId = atom()
Value = number() | {ValueLo, ValueHi}
ValueLo = ValueHi = number()
Status = enabled | disabled
Result = ok | {error, Reason}
Reason = term()

This function sets a lower threshold in a measurement object.

The MRP argument is the identifier returned from the InterfaceMod:create_measurement function.

Note: the existence of this function is optional.

InterfaceMod:remove_threshold(MRP, MeasId, ThreshId) -> Result

Types:
MRP = pid()
MeasId = atom()
ThreshId = atom()
Result = ok | {error, Reason}
Reason = term()

This function removes a specified threshold in a measurement object.

The MRP argument is the identifier returned from the InterfaceMod:create_measurement function.

Note: the existence of this function is optional.

InterfaceMod:enable_threshold(MRP, MeasId, ThreshId) -> Result

Types:
MRP = pid()
MeasId = atom()
ThreshId = atom()
Result = ok | {error, Reason}
Reason = term()

This function enables a specified threshold in a measurement object.

The MRP argument is the identifier returned from the InterfaceMod:create_measurement function.

Note: the existence of this function is optional.

InterfaceMod:disable_threshold(MRP, MeasId, ThreshId) -> Result

Types:
MRP = pid()
MeasId = atom()
ThreshId = atom()
Result = ok | {error, Reason}
Reason = term()

This function disables a specified threshold in a measurement object.

The MRP argument is the identifier returned from the InterfaceMod:create_measurement function.

Note: the existence of this function is optional.

SEE ALSO

mesh_lib(3), mesh_snmp(3), application(3), disk_log(3), eva(3), eva_log(3), eva_sup(3), mnesia(3)

AUTHORS

Fredrik Gustafson - support@erlang.ericsson.se