RFC 8193
Information Model for Large-Scale Measurement Platforms (LMAPs)
Pages: 53
Proposed Standard
Proposed Standard
Part 2 of 3 – Pages 19 to 41
4.4. Logging Information
The MA may report on the success or failure of Configuration or Instruction communications from the Controller. In addition, further operational logs may be produced during the operation of the MA, and updates to Capabilities may also be reported. Reporting this information is achieved in exactly the same manner as scheduling any other Task. We make no distinction between a Measurement Task conducting an active or passive network measurement and one that solely retrieves static or dynamic information from the MA such as Capabilities or Logging Information. One or more logging Tasks can be programmed or configured to capture subsets of the Logging Information. These logging Tasks are then executed by Schedules, which also specify that the resultant data is to be transferred over the Controller Channels. The type of Logging Information will fall into three different categories: 1. Success/failure/warning messages in response to information updates from the Controller. Failure messages could be produced due to some inability to receive or parse the Controller communication or if the MA is not able to act as instructed. For example: * "Measurement Schedules updated OK" * "Unable to parse JSON" * "Missing mandatory element: Measurement Timing" * "'Start' does not conform to schema - expected datetime" * "Date specified is in the past" * "'Hour' must be in the range 1..24" * "Schedule A refers to non-existent Measurement Task Configuration" * "Measurement Task Configuration X registry, entry Y not found" * "Updated Measurement Task Configurations do not include M used by Measurement Schedule N"
2. Operational updates from the MA. For example:
* "Out of memory: cannot record result"
* "Collector 'collector.example.com' not responding"
* "Unexpected restart"
* "Suppression timeout"
* "Failed to execute Measurement Task Configuration H"
3. Status updates from the MA. For example:
* "Device interface added: eth3"
* "Supported measurements updated"
* "New IP address on eth0: xxx.xxx.xxx.xxx"
This Information Model document does not detail the precise format of
Logging Information since it is to a large extent protocol and MA
specific. However, some common information can be identified.
4.4.1. Definition of ma-log-obj
object {
uuid ma-log-agent-id;
datetime ma-log-event-time;
int ma-log-code;
string ma-log-description;
} ma-log-obj;
The ma-log-obj models the generic aspects of a logging object and
consists of the following elements:
ma-log-agent-id: A uuid uniquely identifying the Measurement
Agent.
ma-log-event-time: The date and time of the Event reported in
the logging object.
ma-log-code: A machine-readable code describing the
Event.
ma-log-description: A human-readable description of the Event.
4.5. Capability and Status Information
The MA will hold Capability Information that can be retrieved by a Controller. Capabilities include the device interface details available to Measurement Tasks as well as the set of Measurement Tasks/Roles (specified by registry entries) that are actually installed or available on the MA. Status Information includes the times that operations were last performed such as contacting the Controller or producing Reports.4.5.1. Definition of ma-capability-obj
object { string ma-capability-hardware; string ma-capability-firmware; string ma-capability-version; [string ma-capability-tags<0..*>;] [ma-capability-task-obj ma-capability-tasks<0..*>;] } ma-capability-obj; The ma-capability-obj provides information about the Capabilities of the Measurement Agent and consists of the following elements: ma-capability-hardware: A description of the hardware of the device the Measurement Agent is running on. ma-capability-firmware: A description of the firmware of the device the Measurement Agent is running on. ma-capability-version: The version of the Measurement Agent. ma-capability-tags: An optional unordered set of tags that provide additional information about the Capabilities of the Measurement Agent. ma-capability-tasks: An optional unordered set of capability objects for each supported Task.4.5.2. Definition of ma-capability-task-obj
object { string ma-capability-task-name; ma-registry-obj ma-capability-task-functions<0..*>; string ma-capability-task-version; } ma-capability-task-obj;
The ma-capability-task-obj provides information about the capability
of a Task and consists of the following elements:
ma-capability-task-name: A name uniquely identifying a Task.
ma-capability-task-functions: A possibly empty unordered set of
registry entries identifying
functions this Task implements.
ma-capability-task-version: The version of the Measurement Task.
4.5.3. Definition of ma-status-obj
object {
uuid ma-status-agent-id;
[uri ma-status-device-id;]
datetime ma-status-last-started;
ma-status-interface-obj ma-status-interfaces<0..*>;
[ma-status-schedule-obj ma-status-schedules<0..*>;]
[ma-status-suppression-obj ma-status-suppressions<0..*>;]
} ma-status-obj;
The ma-status-obj provides Status Information about the Measurement
Agent and consists of the following elements:
ma-status-agent-id: A uuid uniquely identifying the Measurement
Agent.
ma-status-device-id: A URI identifying the device.
ma-status-last-started: The date and time the Measurement Agent
last started.
ma-status-interfaces: An unordered set of network interfaces
available on the device.
ma-status-schedules: An optional unordered set of status objects
for each Schedule.
ma-status-suppressions: An optional unordered set of status objects
for each Suppression.
4.5.4. Definition of ma-status-schedule-obj
object { string ma-status-schedule-name; string ma-status-schedule-state; int ma-status-schedule-storage; counter ma-status-schedule-invocations; counter ma-status-schedule-suppressions; counter ma-status-schedule-overlaps; counter ma-status-schedule-failures; datetime ma-status-schedule-last-invocation; [ma-status-action-obj ma-status-schedule-actions<0..*>;] } ma-status-schedule-obj; The ma-status-schedule-obj provides Status Information about the status of a Schedule and consists of the following elements: ma-status-schedule-name: The name of the Schedule this status object refers to. ma-status-schedule-state: The state of the Schedule. The value 'enabled' indicates that the Schedule is currently enabled. The value 'suppressed' indicates that the Schedule is currently suppressed. The value 'disabled' indicates that the Schedule is currently disabled. The value 'running' indicates that the Schedule is currently running. ma-status-schedule-storage: The amount of secondary storage (e.g., allocated in a file system) holding temporary data allocated to the Schedule in bytes. This object reports the amount of allocated physical storage and not the storage used by logical data records. Data models should use a 64-bit integer type.
ma-status-schedule-invocations Number of invocations of this
Schedule. This counter does not
include suppressed invocations or
invocations that were prevented
due to an overlap with a previous
invocation of this Schedule.
ma-status-schedule-suppressions Number of suppressed executions
of this Schedule.
ma-status-schedule-overlaps Number of executions prevented
due to overlaps with a previous
invocation of this Schedule.
ma-status-schedule-failures Number of failed executions of
this Schedule. A failed
execution is an execution where
at least one Action failed.
ma-status-schedule-last-invocation: The date and time of the last
invocation of this Schedule.
ma-status-schedule-actions: An optional ordered list of
status objects for each Action of
the Schedule.
4.5.5. Definition of ma-status-action-obj
object {
string ma-status-action-name;
string ma-status-action-state;
int ma-status-action-storage;
counter ma-status-action-invocations;
counter ma-status-action-suppressions;
counter ma-status-action-overlaps;
counter ma-status-action-failures;
datetime ma-status-action-last-invocation;
datetime ma-status-action-last-completion;
int ma-status-action-last-status;
string ma-status-action-last-message;
datetime ma-status-action-last-failed-completion;
int ma-status-action-last-failed-status;
string ma-status-action-last-failed-message;
} ma-status-action-obj;
The ma-status-action-obj provides Status Information about an Action
of a Schedule and consists of the following elements:
ma-status-action-name: The name of the Action of a
Schedule this status object
refers to.
ma-status-action-state: The state of the Action.
The value 'enabled'
indicates that the Action is
currently enabled. The
value 'suppressed' indicates
that the Action is currently
suppressed. The value
'disabled' indicates that
the Action is currently
disabled. The value
'running' indicates that the
Action is currently running.
ma-status-action-storage: The amount of secondary
storage (e.g., allocated in
a file system) holding
temporary data allocated to
the Action in bytes. This
object reports the amount of
allocated physical storage
and not the storage used by
logical data records. Data
models should use a 64-bit
integer type.
ma-status-action-invocations Number of invocations of
this Action. This counter
does not include suppressed
invocations or invocations
that were prevented due to
an overlap with a previous
invocation of this Action.
ma-status-action-suppressions Number of suppressed
executions of this Action.
ma-status-action-overlaps Number of executions
prevented due to overlaps
with a previous invocation
of this Action.
ma-status-action-failures Number of failed executions
of this Action.
ma-status-action-last-invocation: The date and time of the
last invocation of this
Action.
ma-status-action-last-completion: The date and time of the
last completion of this
Action.
ma-status-action-last-status: The status code returned by
the last execution of this
Action.
ma-status-action-last-message: The status message produced
by the last execution of
this Action.
ma-status-action-last-failed-completion: The date and time of the
last failed completion of
this Action.
ma-status-action-last-failed-status: The status code returned by
the last failed execution of
this Action.
ma-status-action-last-failed-message: The status message produced
by the last failed execution
of this Action.
4.5.6. Definition of ma-status-suppression-obj
object {
string ma-status-suppression-name;
string ma-status-suppression-state;
} ma-status-suppression-obj;
The ma-status-suppression-obj provides Status Information about the
status of a Suppression and consists of the following elements:
ma-status-suppression-name: The name of the Suppression this status
object refers to.
ma-status-suppression-state: The state of the Suppression. The
value 'enabled' indicates that the
Suppression is currently enabled. The
value 'active' indicates that the
Suppression is currently active. The
value 'disabled' indicates that the
Suppression is currently disabled.
4.5.7. Definition of ma-status-interface-obj
object {
string ma-status-interface-name;
string ma-status-interface-type;
[int ma-status-interface-speed;]
[string ma-status-interface-link-layer-address;]
[ip-address ma-status-interface-ip-addresses<0..*>;]
[ip-address ma-status-interface-gateways<0..*>;]
[ip-address ma-status-interface-dns-servers<0..*>;]
} ma-status-interface-obj;
The ma-status-interface-obj provides Status Information about network
interfaces and consists of the following elements:
ma-status-interface-name: A name uniquely identifying a
network interface.
ma-status-interface-type: The type of the network
interface.
ma-status-interface-speed: An optional indication of the
speed of the interface
(measured in bits per
second).
ma-status-interface-link-layer-address: An optional link-layer
address of the interface.
ma-status-interface-ip-addresses: An optional ordered list of
IP addresses assigned to the
interface.
ma-status-interface-gateways: An optional ordered list of
gateways assigned to the
interface.
ma-status-interface-dns-servers: An optional ordered list of
DNS servers assigned to the
interface.
4.6. Reporting Information
At a point in time specified by a Schedule, the MA will execute Tasks that communicate a set of measurement results to the Collector. These Reporting Tasks will be configured to transmit Task results over a specified Report Channel to a Collector. It should be noted that the output from Tasks does not need to be sent to communication Channels. It can alternatively, or additionally, be sent to other Tasks on the MA. This facilitates using a first Measurement Task to control the operation of a later Measurement Task (such as first probing available line speed and then adjusting the operation of a video testing measurement) and also to allow local processing of data to output alarms (e.g., when performance drops from earlier levels). Of course, subsequent Tasks also include Tasks that implement the Reporting Protocol(s) and transfer data to one or more Collectors. The Report generated by a Reporting Task is structured hierarchically to avoid repetition of report header and Measurement Task Configuration information. The report starts with the timestamp of the report generation on the MA and details about the MA including the optional Measurement Agent Identifier and Group-ID (controlled by the Configuration Information). Much of the report information is optional and will depend on the implementation of the Reporting Task and any parameters defined in the Task Configuration for the Reporting Task. For example, some Reporting Tasks may choose not to include the Measurement Task Configuration or Action parameters, while others may do so dependent on the Controller setting a configurable parameter in the Task Configuration. It is possible for a Reporting Task to send just the report header (datetime and optional Agent Identifier and/or Group-ID) if no measurement data is available. Whether to send such empty reports again is dependent on the implementation of the Reporting Task and potential Task Configuration parameter. The handling of measurement data on the MA before generating a Report and transfer from the MA to the Collector is dependent on the implementation of the device, MA, and/or scheduled Tasks and not defined by the LMAP standards. Such decisions may include limits to the measurement data storage and what to do when such available storage becomes depleted. It is generally suggested that implementations running out of storage stop executing new Measurement Tasks and retain old measurement data.
No context information, such as line speed or broadband product are included within the report header information as this data is reported by individual Tasks at the time they execute. Either a Measurement Task can report contextual parameters that are relevant to that particular measurement or specific Tasks can be used to gather a set of contextual and environmental data at certain times independent of the Reporting Schedule. After the report header information, the results are reported grouped according to different Measurement Task Configurations. Each Task section optionally starts with replicating the Measurement Task Configuration information before the result headers (titles for data columns) and the result data rows. The Options reported are those used for the scheduled execution of the Measurement Task and therefore include the Options specified in the Task Configuration as well as additional Options specified in the Action. The Action Options are appended to the Task Configuration Options in exactly the same order as they were provided to the Task during execution. The result row data includes a time for the start of the measurement and optionally an end time where the duration also needs to be considered in the data analysis. Some Measurement Tasks may optionally include an indication of the cross-traffic although the definition of cross-traffic is left up to each individual Measurement Task. Some Measurement Tasks may also output other environmental measures in addition to cross-traffic such as CPU utilization or interface speed. Whereas the Configuration and Instruction Information represent information transmitted via the Control Protocol, the Report represents the information that is transmitted via the Report Protocol. It is constructed at the time of sending a report and represents the inherent structure of the information that is sent to the Collector.4.6.1. Definition of ma-report-obj
object { datetime ma-report-date; [uuid ma-report-agent-id;] [string ma-report-group-id;] [string ma-report-measurement-point;] [ma-report-result-obj ma-report-results<0..*>;] } ma-report-obj;
The ma-report-obj provides the metadata of a single report and
consists of the following elements:
ma-report-date: The date and time when the report was
sent to a Collector.
ma-report-agent-id: An optional uuid uniquely identifying
the Measurement Agent.
ma-report-group-id: An optional identifier of the group of
Measurement Agents this Measurement
Agent belongs to.
ma-report-measurement-point: An optional identifier for the
measurement point indicating where the
Measurement Agent is located on a path
(see [RFC7398] for further details).
ma-report-results: An optional and possibly empty
unordered set of result objects.
4.6.2. Definition of ma-report-result-obj
object {
string ma-report-result-schedule-name;
string ma-report-result-action-name;
string ma-report-result-task-name;
[ma-option-obj ma-report-result-options<0..*>;]
[string ma-report-result-tags<0..*>;]
datetime ma-report-result-event-time;
datetime ma-report-result-start-time;
[datetime ma-report-result-end-time;]
[string ma-report-result-cycle-number;]
int ma-report-result-status;
[ma-report-conflict-obj ma-report-result-conflicts<0..*>;]
[ma-report-table-obj ma-report-result-tables<0..*>;]
} ma-report-result-obj;
The ma-report-result-obj provides the metadata of a result report of
a single executed Action. It consists of the following elements:
ma-report-result-schedule-name: The name of the Schedule that
produced the result.
ma-report-result-action-name: The name of the Action in the
Schedule that produced the result.
ma-report-result-task-name: The name of the Task that produced
the result.
ma-report-result-options: An optional ordered joined list of
options provided by the Task object
and the Action object when the Action
was started.
ma-report-result-tags: An optional unordered set of tags.
This is the joined set of tags
provided by the Task object, Action
object, and Schedule object when the
Action was started.
ma-report-result-event-time: The date and time of the Event that
triggered the Schedule of the Action
that produced the reported result
values. The date and time does not
include any added randomization.
ma-report-result-start-time: The date and time of the start of the
Action that produced the reported
result values.
ma-report-result-end-time: An optional date and time indicating
when the Action finished.
ma-report-result-cycle-number: An optional cycle number derived from
ma-report-result-event-time. It is
the time closest to
ma-report-result-event-time that is a
multiple of the
ma-event-cycle-interval of the Event
that triggered the execution of the
Schedule. The value is only present
in an ma-report-result-obj if the
Event that triggered the execution of
the Schedule has a defined
ma-event-cycle-interval. The cycle
number is represented in the format
YYYYMMDD.HHMMSS where YYYY represents
the year, MM the month (1..12), DD
the day of the months (01..31), HH
the hour (00..23), MM the minute
(00..59), and SS the second (00..59).
The cycle number is using Coordinated
Universal Time (UTC).
ma-report-result-status: The status code returned by the
execution of the Action.
ma-report-result-conflicts: A possibly empty set of conflict
Actions that might have impacted the
measurement results being reported.
ma-report-result-tables: An optional and possibly empty
unordered set of result tables.
4.6.3. Definition of ma-report-conflict-obj
object {
string ma-report-conflict-schedule-name;
string ma-report-conflict-action-name;
string ma-report-conflict-task-name;
} ma-report-conflict-obj;
The ma-report-conflict-obj provides the information about a
conflicting Action that might have impacted the measurement results.
It consists of the following elements:
ma-report-result-schedule-name: The name of the Schedule that may
have impacted the result.
ma-report-result-action-name: The name of the Action in the
Schedule that may have impacted the
result.
ma-report-result-task-name: The name of the Task that may have
impacted the result.
4.6.4. Definition of ma-report-table-obj
object {
[ma-registry-obj ma-report-table-functions<0..*>;]
[string] ma-report-table-column-labels<0..*>;]
[ma-report-row-obj ma-report-table-rows<0..*>;]
} ma-report-table-obj;
The ma-report-table-obj represents a result table and consists of the
following elements:
ma-report-table-functions: An optional and possibly empty
unordered set of registry entries
identifying the functions for which
results are reported.
ma-report-table-column-labels: An optional and possibly empty
ordered list of column labels.
ma-report-table-rows: A possibly empty ordered list of
result rows.
4.6.5. Definition of ma-report-row-obj
object {
data ma-report-row-values<0..*>;
} ma-report-row-obj;
The ma-report-row-obj represents a result row and consists of the
following elements:
ma-report-row-values: A possibly empty ordered list of result
values. When present, it contains an
ordered list of values that align to the
set of column labels for the report.
4.7. Common Objects: Schedules
A Schedule specifies the execution of a single or repeated series of
Actions. An Action extends a configured Task with additional
specific parameters. Each Schedule contains basically two elements:
an ordered list of Actions to be executed and an Event object
triggering the execution of the Schedule. The Schedule states what
Actions to run (with what configuration) and when to run the Actions.
A Schedule may optionally have an Event that stops the execution of
the Schedule or a maximum duration after which a Schedule is stopped.
Multiple Actions contained as an ordered list of a single Measurement
Schedule will be executed according to the execution mode of the
Schedule. In sequential mode, Actions will be executed sequentially
and in parallel mode, all Actions will be executed concurrently. In
pipelined mode, data produced by one Action is passed to the
subsequent Action. Actions contained in different Schedules execute
in parallel with such conflicts being reported in the Reporting
Information where necessary. If two or more Schedules have the same
start time, then the two will execute in parallel. There is no
mechanism to prioritize one Schedule over another or to mutex
scheduled Tasks.
As well as specifying which Actions to execute, the Schedule also
specifies how to link the data outputs from each Action to other
Schedules. Specifying this within the Schedule allows the highest
level of flexibility since it is even possible to send the output
from different executions of the same Task Configuration to different
destinations. A single Task producing multiple different outputs is
expected to properly tag the different results. An Action receiving
the output can then filter the results based on the tag if necessary.
For example, a Measurement Task might report routine results to a
data Reporting Task in a Schedule that communicates hourly via the
broadband interface, but it also outputs emergency conditions via an
alarm Reporting Task in a different Schedule communicating
immediately over a General Packet Radio Service (GPRS) Channel. Note
that Task-to-Task data transfer is always specified in association
with the scheduled execution of the sending Task -- there is no need
for a corresponding input specification for the receiving Task.
While it is likely that an MA implementation will use a queue
mechanism between the Schedules or Actions, this Information Model
does not mandate or define a queue. The Information Model, however,
reports the storage allocated to Schedules and Actions so that
storage usage can be monitored. Furthermore, it is recommended that
MA implementations by default retain old data and stop the execution
of new Measurement Tasks if the MA runs out of storage capacity.
When specifying the Task to execute within the Schedule, i.e.,
creating an Action, it is possible to add to the Option parameters.
This allows the Task Configuration to determine the common
characteristics of a Task, while selected parameters (e.g., the test
target URL) are defined within as Option parameters of the Action in
the Schedule. A single Task's Configuration can even be used
multiple times in the same Schedule with different additional
parameters. This allows for efficiency in creating and transferring
the Instruction. Note that the semantics of what happens if an
Option is defined multiple times (in either the Task Configuration,
the Action, or both) is not standardized and will depend upon the
Task. For example, some Tasks may legitimately take multiple values
for a single parameter.
Where Options are specified in both the Action and the Task
Configuration, the Action Options are appended to those specified in
the Task Configuration.
Example: An Action of a Schedule references a single Measurement
Task Configuration for measuring UDP latency. It specifies that
results are to be sent to a Schedule with a Reporting Action.
This Reporting Task of the Reporting Action is executed by a
separate Schedule that specifies that it should run hourly at 5
minutes past the hour. When run, this Reporting Action takes the
data generated by the UDP latency Measurement Task as well as any
other data to be included in the hourly report and transfers it to
the Collector over the Report Channel specified within its own
Schedule.
Schedules and Actions may optionally also be given tags that are included in result reports sent to a Collector. In addition, Schedules can be given Suppression tags that may be used to select Schedules and Actions for Suppression.4.7.1. Definition of ma-schedule-obj
object { string ma-schedule-name; ma-event-obj ma-schedule-start; [ma-event-obj ma-schedule-end;] [int ma-schedule-duration;] ma-action-obj ma-schedule-actions<0..*>; string ma-schedule-execution-mode; [string ma-schedule-tags<0..*>;] [string ma-schedule-suppression-tags<0..*>;] } ma-schedule-obj; The ma-schedule-obj is the main scheduling object. It consists of the following elements: ma-schedule-name: A name uniquely identifying a scheduling object. ma-schedule-start: An Event object indicating when the Schedule starts. ma-schedule-end: An optional Event object controlling the forceful termination of scheduled Actions. When the Event occurs, all Actions of the Schedule will be forced to terminate gracefully. ma-schedule-duration: An optional duration in seconds for the Schedule. All Actions of the Schedule will be forced to terminate gracefully after the duration number of seconds past the start of the Schedule. ma-schedule-actions: A possibly empty ordered list of Actions to invoke when the Schedule starts.
ma-schedule-execution-mode: Indicates whether the Actions should be
executed sequentially, in parallel, or
in a pipelined mode (where data
produced by one Action is passed to the
subsequent Action). The default
execution mode is pipelined.
ma-schedule-tags: An optional unordered set of tags that
are reported together with the
measurement results to a Collector.
ma-schedule-suppression-tags: An optional unordered set of
Suppression tags that are used to
select Schedules to be suppressed.
4.7.2. Definition of ma-action-obj
object {
string ma-action-name;
string ma-action-config-task-name;
[ma-option-obj ma-action-task-options<0..*>;]
[string ma-action-destinations<0..*>;]
[string ma-action-tags<0..*>;]
[string ma-action-suppression-tags<0..*>;]
} ma-action-obj;
The ma-action-obj models a Task together with its Schedule-specific
Task Options and Destination Schedules. It consists of the following
elements:
ma-action-name: A name uniquely identifying an Action
of a scheduling object.
ma-action-config-task-name: A name identifying the configured Task
to be invoked by the Action.
ma-action-task-options: An optional and possibly empty ordered
list of options (name-value pairs) that
are passed to the Task by appending
them to the options configured for the
Task object.
ma-action-destinations: An optional and possibly empty
unordered set of names of Destination
Schedules that consume output produced
by this Action.
ma-action-tags: An optional unordered set of tags that
are reported together with the
measurement results to a Collector.
ma-action-suppression-tags: An optional unordered set of
Suppression tags that are used to
select Actions to be suppressed.
4.8. Common Objects: Channels
A Channel defines a bidirectional communication mechanism between the
MA and a Controller or Collector. Multiple Channels can be defined
to enable results to be split or duplicated across different
Collectors.
Each Channel contains the details of the remote endpoint (including
location and security credential information such as a certificate).
The timing of when to communicate over a Channel is specified by the
Schedule, which executes the corresponding Control or Reporting Task.
The certificate can be the digital certificate associated to the
Fully Qualified Domain Name (FQDN) in the URL, or it can be the
certificate of the Certification Authority that was used to issue the
certificate for the FQDN of the target URL (which will be retrieved
later on using a communication protocol such as Transport Layer
Security (TLS)). In order to establish a secure Channel, the MA will
use its own security credentials (in the Configuration Information)
and the given credentials for the individual Channel endpoint.
As with the Task Configurations, each Channel is also given a text
name by which it can be referenced as a Task Option.
Although the same in terms of information, Channels used for
communication with the Controller are referred to as Control Channels
whereas Channels to Collectors are referred to as Report Channels.
Hence, Control Channels will be referenced from Control Tasks
executed by a Control Schedule, whereas Report Channels will be
referenced from within Reporting Tasks executed by an Instruction
Schedule.
Multiple interfaces are also supported. For example, the Reporting
Task could be configured to send some results over GPRS. This is
especially useful when such results indicate the loss of connectivity
on a different network interface.
Example: A Channel used for reporting results may specify that
results are to be sent to the URL (https://collector.example.org/
report/), using the appropriate digital certificate to establish a
secure Channel.
4.8.1. Definition of ma-channel-obj
object { string ma-channel-name; url ma-channel-target; credentials ma-channel-credentials; [string ma-channel-interface-name;] } ma-channel-obj; The ma-channel-obj consists of the following elements: ma-channel-name: A unique name identifying the Channel object. ma-channel-target: A URL identifying the target Channel endpoint. ma-channel-credentials: The security credentials needed to establish a secure Channel. ma-channel-interface-name: An optional name of the network interface to be used. If not present, the IP protocol stack will select a suitable interface.4.9. Common Objects: Task Configurations
Conceptually, each Task Configuration defines the parameters of a Task that the MA may perform at some point in time. It does not by itself actually instruct the MA to perform them at any particular time (this is done by a Schedule). Tasks can be Measurement Tasks (i.e., those Tasks actually performing some type of passive or active measurement) or any other scheduled activity performed by the MA such as transferring information to or from the Controller and Collectors. Other examples of Tasks may include data manipulation or processing Tasks conducted on the MA. A Measurement Task Configuration is the same in information terms to any other Task Configuration. Both Measurement and non-Measurement Tasks may have registry entries to enable the MA to uniquely identify the Task it should execute and retrieve the schema for any parameters that may be passed to the Task. Registry entries are specified as a URI and can therefore be used to identify the Task within a namespace or point to a web or local file location for the Task information. As mentioned previously, these URIs may be used to identify the Measurement Task in a public namespace such as the to-be-created IPPM registry described in [IPPM-REG].
Example: A Measurement Task Configuration may configure a single
Measurement Task for measuring UDP latency. The Measurement Task
Configuration could define the destination port and address for
the measurement as well as the duration, internal packet timing
strategy, and other parameters (for example, a stream for one hour
and sending one packet every 500 ms). It may also define the
output type and possible parameters (for example, the output type
can be the 95th percentile mean) where the Measurement Task
accepts such parameters. It does not define when the Task starts
(this is defined by the Schedule element), so it does not by
itself instruct the MA to actually perform this Measurement Task.
The Task Configuration will include a local short name for reference
by a Schedule. Task Configurations may also refer to registry
entries as described above. In addition, the Task can be configured
through a set of configuration Options. The nature and number of
these Options will depend upon the Task. These Options are expressed
as name-value pairs, although the 'value' may be a structured object
instead of a simple string or numeric value. The implementation of
these name-value pairs will vary between data models.
An Option that must be present for Reporting Tasks is the Channel
reference specifying how to communicate with a Collector. This is
included in the Task Options and will have a value that matches a
Channel name that has been defined in the Instruction. Similarly,
Control Tasks will have a similar Option with the value set to a
specified Control Channel.
A Reporting Task might also have a flag parameter, defined as an
Option, to indicate whether to send a report without measurement
results if there is no measurement result data pending to be
transferred to the Collector. In addition, many Tasks will receive
(as a parameter) information about which interface to use.
In addition, the Task Configuration may optionally also be given tags
that can carry a Measurement Cycle ID. The purpose of this ID is to
easily identify a set of measurement results that have been produced
by Measurement Tasks with comparable Options. This ID could be
manually incremented or otherwise changed when an Option change is
implemented, which could mean that two sets of results should not be
directly compared.
4.9.1. Definition of ma-task-obj
object { string ma-task-name; ma-registry-obj ma-task-functions<0..*>; [ma-option-obj ma-task-options<0..*>;] [string ma-task-tags<0..*>;] } ma-task-obj; The ma-task-obj defines a configured Task that can be invoked as part of an Action. A configured Task can be referenced by its name, and it contains a possibly empty set of URIs to link to registry entries. Options allow the configuration of Task parameters (in the form of name-value pairs). The ma-task-obj consists of the following elements: ma-task-name: A name uniquely identifying a configured Task object. ma-task-functions: A possibly empty unordered set of registry entries identifying the functions of the configured Task. ma-task-options: An optional and possibly empty ordered list of options (name-value pairs) that are passed to the configured Task. ma-task-tags: An optional unordered set of tags that are reported together with the measurement results to a Collector.4.9.2. Definition of ma-option-obj
object { string ma-option-name; [object ma-option-value;] } ma-option-obj; The ma-option-obj models a name-value pair and consists of the following elements: ma-option-name: The name of the option. ma-option-value: The optional value of the option. The ma-option-obj is used to define Task Configuration Options. Task Configuration Options are generally Task specific. For Tasks associated with an entry in a registry, the registry may define well-
known option names (e.g., the so-called parameters in the to-be- created IPPM metric registry described in [IPPM-REG]). Control and Reporting Tasks need to know the Channel they are going to use. The common option name for specifying the Channel is "channel" where the option's value refers to the name of an ma-channel-obj.4.10. Common Objects: Registry Information
Tasks and Actions can be associated with entries in a registry. A registry object refers to an entry in a registry (identified by a URI), and it may define a set of roles.4.10.1. Definition of ma-registry-obj
object { uri ma-registry-uri; [string ma-registry-role<0..*>;] } ma-registry-obj; The ma-registry-obj refers to an entry of a registry, and it defines the associated role(s). The ma-registry-obj consists of the following elements: ma-registry-uri: A URI identifying an entry in a registry. ma-registry-role: An optional and possibly empty unordered set of roles for the identified registry entry.
(page 41 continued on part 3)