.. Copyright 2017 AT&T Intellectual Property, All rights reserved
.. Copyright 2017-2018 Huawei Technologies Co., Ltd.
-===================================
+.. _ves_event_registration_3_2:
+
Service: VES Event Registration 3.2
-===================================
-
-+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| **Legal Disclaimer** |
-| |
-| Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at |
-| |
-| http://www.apache.org/licenses/LICENSE-2.0 |
-| |
-| Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. |
-+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+------------------------------------
+
++-----------------------------------------------------------------------------+
+| **Legal Disclaimer** |
+| |
+| Licensed under the Apache License, Version 2.0 (the "License"); you may not |
+| use this file except in compliance with the License. You may obtain a copy |
+| of the License at |
+| |
+| http://www.apache.org/licenses/LICENSE-2.0 |
+| |
+| Unless required by applicable law or agreed to in writing, software |
+| distributed under the License is distributed on an "AS IS" BASIS, WITHOUT |
+| WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the |
+| License for the specific language governing permissions and limitations |
+| under the License. |
++-----------------------------------------------------------------------------+
+-------------------+--------------------------+
| Document Number | VES Event Registration |
+-----------------+------------------------------+
Introduction
-============
+^^^^^^^^^^^^
This document specifies a YAML format for the registration of VES
Events. The YAML format enables both human designers and applications to
eventNames.
Audience
---------
+~~~~~~~~
This document is intended to support the following groups:
Service Provider applications at design time.
Goal
-----
+~~~~
The goal of the YAML is to completely describe the processing of VNF
events in a way that can be compiled or interpreted by applications
across a Service Provider’s infrastructure.
Relation to the Common Event Format
------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The Common Event Format described in the VES Event Listener service
specification defines the structure of VES events including optional
allowed by the Common Event Format (e.g., ‘MINOR’ or ‘NORMAL’).
Relation to Service Design and Creation
----------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Event registration for a VNF (or other event source) is provided to the
Service Provider’s Service Creation and Design Environment (e.g., ASDC)
for any manual, VNF-specific development.
YAML Files
-==========
+^^^^^^^^^^
YAML Specification Conformance
-------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
YAML files should conform to version 1.2 of the YAML specification
available at: http://yaml.org/spec/1.2/spec.html.
Filename
---------
+~~~~~~~~
YAML file names should conform to the following naming convention:
- {AsdcModel}\_{AsdcModelType}\_{v#}.yml
+ ``{AsdcModel}\_{AsdcModelType}\_{v#}.yml``
The ‘#’ should be replaced with the current numbered version of the
file.
For example:
-- vMRF\_Vnf\_v1.yml
+- ``vMRF\_Vnf\_v1.yml``
-- vMRF\_Service\_v1.yml
+- ``vMRF\_Service\_v1.yml``
-- vIsbcSsc\_VfModule\_v1.yml
+- ``vIsbcSsc\_VfModule\_v1.yml``
File Structure
---------------
+~~~~~~~~~~~~~~
Each eventType is registered as a distinct YAML ‘document’.
YAML files consist of a series of YAML documents delimited by ‘---‘ and
‘…’ for example:
- ---
+.. code-block:: ruby
- # Event Registration for eventName ‘name1’
+ Some Ruby code.
+ ---
- # details omitted
+ # Event Registration for eventName ‘name1’
- ...
+ # details omitted
- ---
+ ...
- # Event Registration for eventName ‘name2’
+ ---
- # details omitted
+ # Event Registration for eventName ‘name2’
- ...
+ # details omitted
- ---
+ ...
- # Event Registration for eventName ‘name3’
+ ---
- # details omitted
+ # Event Registration for eventName ‘name3’
- ...
+ # details omitted
+
+ ...
YAML Syntax and Semantics
-=========================
+^^^^^^^^^^^^^^^^^^^^^^^^^
YAML registration documents show each relevant VES Common Event Model
object and field (i.e., each element) for the eventName being
pairs).
Qualifiers
-----------
+~~~~~~~~~~
Each object or field name in the eventName being registered is followed
by a ‘qualifier’, which consists of a colon and two curly braces, for
example:
- “objectOrFieldName: { }”
+ ``“objectOrFieldName: { }”``
The curly braces contain meta-information about that object or field
name (also known as the ‘element’), such as whether it is required to be
within the curly braces:
Action
-~~~~~~
+++++++
The ‘action’ keyword may be applied to field values or to the event as a
whole. The ‘action’ keyword specifies a set of actions that should be
Examples:
-- event: { action: [ any, any, null, rebootVm ] }
+.. code-block:: yaml
+
+ event: {
+ action: [
+ any, any, null, rebootVm
+ ]
+ }
# whenever the above event occurs, the VM should be rebooted
-- fieldname: { action: [ 80, up, null, null, tcaUpEventName ], action:
- [ 60, down, overcapacity, null ] }
+ fieldname: {
+ action: [ 80, up, null, null, tcaUpEventName ],
+ action: [ 60, down, overcapacity, null ]
+ }
# when the value of fieldname crosses 80 in an up direction,
- tcaUpEventName
-
- should be published; if the fieldname crosses 60 in a down direction
- an
-
- ‘overCapacity’ named-condition is asserted.
+ # tcaUpEventName should be published; if the fieldname crosses 60
+ # in a down direction an ‘overCapacity’ named-condition is asserted.
AggregationRole
-~~~~~~~~~~~~~~~
++++++++++++++++
The ‘aggregationRole’ keyword is applied to the value keyword in a field
of a name-value pair.
it must have key name1 and name1’s value should be interpreted as an
index:
-- additionalMeasurements: {presence: optional, array: [
-
- {
-
- name: {presence: required},
-
- arrayOfFields: {presence: required, array: [
-
- {
-
- name: {presence: required, value: name1},
-
- value: {presence: required, aggregationRole: index}
-
+.. code-block:: yaml
+
+ additionalMeasurements: {
+ presence: optional, array: [
+ {
+ name: {presence: required},
+ arrayOfFields: {
+ presence: required, array: [
+ {
+ name: {presence: required, value: name1},
+ value: {presence: required, aggregationRole: index}
+ }
+ ]
}
-
- ] }
-
- }
-
- ] }
+ }
+ ]
+ }
Example 2:
- The first three columns would be sent through VES as follows:
-.. code-block:: text
+.. code-block:: yaml
additionalMeasurements: {presence: required, array: [
-
{
-
name: {presence: required, value: TunnelTraffic},
-
arrayOfFields: {presence: required, array: [
-
{
-
name: {presence: required, value: TunnelName},
-
value: {presence: required, aggregationRole: index},
-
},
-
{
-
name: {presence: required, value: TunnelType},
-
value: {presence: required, aggregationRole: reference}
-
},
-
{
-
name: {presence: required, value: TotalOutputBytes},
-
value: {presence: required, aggregationRole: gauge, castTo:number }
-
}
-
]}
-
}
-
]}
Array
-~~~~~
++++++
The ‘array’ keyword indicates that the element is an array; ‘array:’ is
following by square brackets which contain the elements of the array.
Examples:
-- element: { array: [
+.. code-block:: yaml
- firstArrayElement: { },
+ element: { array: [
- secondArrayElement: { }
+ firstArrayElement: { },
- ] }
+ secondArrayElement: { }
+
+ ]}
CastTo
-~~~~~~
+++++++
The ‘castTo’ keyword is applied to ‘value’ keywords. It tells the
receiving event processor to cast (or interpret) the supplied value from
Example:
-- fieldname: { value: [ x, y, z ], castTo: number } # only values ‘x’,
+.. code-block:: yaml
+
+ fieldname: { value: [ x, y, z ], castTo: number } # only values ‘x’,
‘y’, or ‘z’ allowed
# each must be cast to a number
-- additionalMeasurements: {presence: optional, array: [
+.. code-block:: yaml
+ additionalMeasurements: {presence: optional, array: [
{
-
name: {presence: required},
-
arrayOfFields: {presence: required, array: [
-
{
-
name: {presence: required, value: name1},
-
value: {presence: required, castTo: number}
-
}
-
] }
-
}
-
] }
- For another example, see the second example under AggregationRole.
+
+**For another example, see the second example under AggregationRole.**
Comment
-~~~~~~~
++++++++
The ‘comment’ keyword enables event registrations to communicate
additional information, in the form of a quoted string, to designers
Examples:
-- fieldname: { range: [ 1, unbounded ], default: 5, comment: “needs
- further diagnosis; call the TAC” }
+.. code-block:: yaml
-- fieldname: { value: [ red, white, blue ], default: blue, comment:
- “red indicates degraded quality of service” }
+ fieldname: {
+ range: [ 1, unbounded ],
+ default: 5,
+ comment: “needs further diagnosis; call the TAC”
+ }
-- event: { presence: required, comment: “this event only occurs in
- conditions when the ipq has stopped operating; manual reset may
- be required”, structure: { . . . } }
+.. code-block:: yaml
+
+ fieldname: {
+ value: [ red, white, blue ],
+ default: blue,
+ comment: “red indicates degraded quality of service”
+ }
+
+.. code-block:: yaml
+
+ event: {
+ presence: required,
+ comment: “this event only occurs in conditions when the
+ ipq has stopped operating; manual reset may be required”,
+ structure: { . . . }
+ }
Default
-~~~~~~~
++++++++
The ‘default’ keyword specifies a default field value. Note: the default
value must be within the range or enumeration of acceptable values.
Examples:
-- fieldname: { range: [ 1, unbounded ], default: 5 }
+.. code-block:: yaml
+
+ fieldname: { range: [ 1, unbounded ], default: 5 }
+
+.. code-block:: yaml
+
+ fieldname: { value: [ red, white, blue ], default: blue }
-- fieldname: { value: [ red, white, blue ], default: blue }
HeartbeatAction
-~~~~~~~~~~~~~~~
+++++++++++++++++
The ‘heartbeatAction’ keyword is provided on the ‘event’ objectName for
heartbeat events only. It provides design time guidance to the service
Examples:
-- event: { heartbeatAction: [ 3, vnfDown, RECO-rebootVnf, tcaEventName
- ] }
+.. code-block:: yaml
+
+ event: { heartbeatAction: [ 3, vnfDown, RECO-rebootVnf, tcaEventName] }
# whenever the above event occurs, a vnfDown condition is asserted
- and the vnf should be rebooted, plus the indicated tca should be
- generated.
+ # and the vnf should be rebooted, plus the indicated tca should be
+ # generated.
keyValuePairString
-~~~~~~~~~~~~~~~~~~
+++++++++++++++++++
The ‘keyValuePairString’ keyword describes the key-value pairs to be
communicated through a string (e.g., in the VES Syslog Fields
‘syslogSData’ or ‘additionalFields’ strings). This keyword takes three
parameters:
-- the first parameter specifies the character used to delimit (i.e., to
+- The first parameter specifies the character used to delimit (i.e., to
separate) the key-value pairs. If a space is used as a delimiter,
it should be communicated within single quotes as ‘ ‘; otherwise,
the delimiter character should be provided without any quotes.
with ‘key=value’ pairs delimited by the pipe (‘\|’) symbol as in
(“key1=value1\|key2=value2\|key3=value3…”).
- additionalFields: {presence: required, keyValuePairString: {\|, =, keyValuePairs: [
-
- keyValuePair: {presence: required, structure: {
-
- key: {presence: required, value: someKeyName},
-
- value: {presence: required, range: [0, 100]}
-
- } },
-
- keyValuePair: {presence: optional, structure: {
+.. code-block:: yaml
- key: {presence: required, value: someOtherKeyName},
-
- value: {presence: required, value [red, white, blue]}
-
- } }
-
-] } }
+ additionalFields: {
+ presence: required, keyValuePairString: {\|, =, keyValuePairs: [
+ keyValuePair: {
+ presence: required, structure: {
+ key: {presence: required, value: someKeyName},
+ value: {presence: required, range: [0, 100]}
+ }
+ },
+ keyValuePair: {
+ presence: optional, structure: {
+ key: {presence: required, value: someOtherKeyName},
+ value: {presence: required, value [red, white, blue]}
+ }
+ }
+ ]}
+ }
Presence
-~~~~~~~~
++++++++++
The ‘presence’ keyword may be defined as ‘required’ or ‘optional’. If
not provided, the element is assumed to be ‘optional’.
-Examples
+Examples:
+
+.. code-block:: yaml
+
+ element: { presence: required } # element must be present
-- element: { presence: required } # element must be present
+.. code-block:: yaml
-- element: { presence: optional } # element is optional
+ element: { presence: optional } # element is optional
-- element: { value: blue } # by omitting a presence definition, the element is assumed to be optional
+.. code-block:: yaml
+
+ element: { value: blue }
+ # by omitting a presence definition, the element is assumed to be optional
Range
-~~~~~
++++++++
The ‘range’ keyword applies to fields (i.e., simpleTypes); indicates the
value of the field is a number within a specified range of values from
Examples:
-- fieldname: { range: [ 1, unbounded ] }
+.. code-block:: yaml
-- fieldname: { range: [ 0, 3.14 ] }
+ fieldname: { range: [ 1, unbounded ] }
+
+.. code-block:: yaml
+
+ fieldname: { range: [ 0, 3.14 ] }
Structure
-~~~~~~~~~
+++++++++++
The ‘structure’ keyword indicates that the element is a complexType
(i.e., an object) and is followed by curly braces containing that
Example:
-- objectName: { structure: {
-
- element1: { },
-
- element2: { },
-
- anotherObject: { structure: {
+.. code-block:: yaml
- element3: { },
-
- element4: { }
-
- } }
-
- } }
+ objectName: {
+ structure: {
+ element1: { },
+ element2: { },
+ anotherObject: {
+ structure: {
+ element3: { },
+ element4: { }
+ }
+ }
+ }
+ }
Units
-~~~~~
++++++++
The ‘units’ qualifier may be applied to values provided in VES Common
Event Format extensible field structures. The ‘units’ qualifier
Example:
-- field: { structure: {
-
- name: { value: pilotNumberPoolSize },
-
- value: { units: megabytes } # the value will be expressed in
- megabytes
+.. code-block:: yaml
- } }
+ field: {
+ structure: {
+ name: { value: pilotNumberPoolSize },
+ value: { units: megabytes } # the value will be expressed in megabytes
+ }
+ }
Value
-~~~~~
++++++++
The ‘value’ keyword applies to fields (i.e., simpleTypes); indicates a
single value or an enumeration of possible values. If not provided, it
Examples:
-- fieldname: { value: x } # the value is ‘x’
+.. code-block:: yaml
+
+ fieldname: { value: x } # the value is ‘x’
+
+.. code-block:: yaml
-- fieldname: { value: [ x, y, z ] } # the value is either ‘x’, ‘y’, or
- ‘z’
+ fieldname: { value: [ x, y, z ] }
+ # the value is either ‘x’, ‘y’, or ‘z’
-- fieldname: { presence: required } # the value will be provided at
- runtime
+.. code-block:: yaml
-- fieldname: { value: ‘error state’ } # the value is the string within
- the single quotes
+ fieldname: { presence: required }
+ # the value will be provided at runtime
+
+.. code-block:: yaml
+
+ fieldname: { value: ‘error state’ }
+ # the value is the string within the single quotes
Rules
------
+~~~~~
Rules Document
-~~~~~~~~~~~~~~
+++++++++++++++
After all events have been defined, the YAML file may conclude with a
final YAML document delimited by ‘---‘ and ‘…’, which defines rules
based on the named ‘conditions’ asserted in action qualifiers in the
preceding event definitions. For example:
+.. code-block:: yaml
+
---
# Event Registration for eventName ‘name1’
- event: {presence: required, action: [any, any, A, null], structure:
- {
-
- # details omitted
-
- }}
-
+ event: {
+ presence: required,
+ action: [any, any, A, null],
+ structure: {# details omitted}
+ }
...
-
---
# Event Registration for eventName ‘name2’
-
- event: {presence: required, structure: {
-
- commonEventHeader: {presence: required, structure: {
-
- # details omitted
-
- }}
-
- measurements: {presence: required, structure: {
-
- cpuUsageArray: {presence: required, array: {
-
- cpuUsage: {presence: required, structure: {
-
- cpuIdentifier: {presence: required},
-
- percentUsage: {presence: required, action: [90, up, B, null]}
-
- }}
-
- }},
-
-# details omitted
-
- }}
-
- }}
-
+ event: {
+ presence: required,
+ structure: {
+ commonEventHeader: {
+ presence: required,
+ structure: {# details omitted}
+ }
+ measurements: {
+ presence: required,
+ structure: {
+ cpuUsageArray: {
+ presence: required,
+ array: {
+ cpuUsage: {
+ presence: required,
+ structure: {
+ cpuIdentifier: {
+ presence: required
+ },
+ percentUsage: {
+ presence: required,
+ action: [90, up, B, null]
+ }
+ }
+ }
+ }
+ }, # details omitted
+ }
+ }
+ }
+ }
...
-
---
# Rules
rules: [
-
- # defined based on conditions ‘A’ and ‘B’ - details omitted
-
+ # defined based on conditions ‘A’ and ‘B’ - details omitted
]
...
Rules Syntax and Semantics
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+++++++++++++++++++++++++++++
The YAML ‘rules’ document begins with the keyword ‘rules’ followed by a
colon and square brackets. Each rule is then defined within the square
Each rule is expressed as follows:
-rule: {
+.. code-block:: text
-trigger: *logical expression in terms of conditions*,
+ rule: {
-microservices: [ *microservice1, microservice2, microservice3…* ]
+ trigger: *logical expression in terms of conditions*,
-alerts: [tcaE*ventName1, tcaEventName2, tcaEventName3…* ],
+ microservices: [ *microservice1, microservice2, microservice3…* ]
-}
+ alerts: [tcaE*ventName1, tcaEventName2, tcaEventName3…* ],
+
+ }
Notes:
microservices and alerts may be specified.
Simple Triggers
-~~~~~~~~~~~~~~~
+++++++++++++++++
The trigger is based on the named ‘conditions’ asserted in the action
qualifiers within the event definitions earlier in the YAML file. The
Example rules definition:
-rules: [
-
- rule: {
-
- trigger: A,
-
- alerts: [tcaEventName1],
-
- microservices: [rebootVm]
-
- },
-
- rule: {
-
- trigger: B \|\| (C & D),
-
- microservices: [scaleOut]
-
- }
+.. code-block:: text
-]
+ rules: [
+ rule: {
+ trigger: A,
+ alerts: [tcaEventName1],
+ microservices: [rebootVm]
+ },
+ rule: {
+ trigger: B \|\| (C & D),
+ microservices: [scaleOut]
+ }
+ ]
Note: when microservices are defined in terms of multiple event
conditions, the designer should take care to consider whether the target
clarity.
Time Based Qualifiers
-~~~~~~~~~~~~~~~~~~~~~
++++++++++++++++++++++++
Time based rules may be established by following any named condition
with a colon and curly braces. The time based rule is placed in the
minutes AND condition C is in effect.
PM Dictionary
--------------
+~~~~~~~~~~~~~~
The Performance Management (PM) Dictionary is used by analytics
applications to interpret and process perf3gpp measurement information
Dictionary Schema).
PM Dictionary Schema Keywords
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
++++++++++++++++++++++++++++++++++++
The following is a list of standard PM Dictionary Schema Keywords:
+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
PM Dictionary Schema Example
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+++++++++++++++++++++++++++++
The following is a sample PM Dictionary Schema:
----
# PM Dictionary schema specifying and describing the meta information
used to define perf3gpp measurements in the PM Dictionary
.. code-block:: text
- pmDictionary: { presence: required, structure: {
-
- pmDictionaryHeader: { presence: required, structure: {
-
- nfType: { presence: required, comment: "NF type; should match the string used in the perf3gpp eventName"},
-
- pmDefSchemaVsn: { presence: required, value: 1.0, comment: "PM Dictionary Schema Version"},
-
- pmDefVsn: { presence: required, comment: "vendor-defined PM Dictionary version"},
-
- vendor: { presence: required, comment: "vendor of the NF type"}
-
- }},
-
- pmDictionaryMeasurements: { presence: required, array: [
-
- iMeasInfoId: { presence: required, comment: "vendor-defined integer measurement group identifier"},
-
- iMeasType: { presence: required, comment: "vendor-defined integer identifier for the measType; must be combined with measInfoId to identify a specific measurement."},
-
- measAdditionalFields: { presence: required, comment: "vendor-specific PM Dictionary fields", array: [
-
- keyValuePair: { presence: required, structure: {
-
- key: { presence: required, value: measAggregationLevels, comment:"Nokia-specific field"},
-
- value: { presence: required, value: [NGBTS, NGCELL, IPNO, IPSEC, ETHIF],comment: "list of one or more aggregation levels that Nokia recommends for this measurement; for example, if the value is NGBTS NGCELL, then Nokia recommends this measurement be aggregated on
- the 5G BTS level and the 5G Cell level"}
-
- }}
-
- ]},
-
- measChangeType: { presence: required, value: [added, modified, deleted],
- comment: "indicates the type of change that occurred during measLastChange"},
-
- measCollectionMethod: { presence: required, value: [CC, SI, DER, Gauge,
- Average], comment: "the measurement collection method; CC, SI, DER and Gauge are as defined in 3GPP; average contains the average value of the measurement during the granularity period"},
-
- measCondition: { presence: required, comment: "description of the
- condition causing the measurement"},
-
- measDescription: { presence: required, comment: "description of the
- measurement information and purpose"},
-
- measFamily: { presence: required, comment: "abbreviation for a family of
- measurements, in 3GPP format,or vendor defined"},
-
- measInfoId: { presence: required, comment: "name for a group of related
- measurements in 3GPP format or vendor defined"},
-
- measLastChange: { presence: required, comment: "version of the PM
- Dictionary the last time this measurement was added, modified or deleted"},
-
- measObjClass: { presence: required, value: [NGBTS, NGCELL, IPNO, IPSEC,
- ETHIF], comment: "measurement object class"},
-
- measResultRange: { presence: optional, comment: "range of the
- measurement result; only necessary when the range is smaller than the full range of the data type"},
-
- measResultType: { presence: required, value: [float, unit32, uint64],
- comment: "data type of the measurement result"},
-
- measResultUnits: { presence: required, value: [ seconds, minutes, nanoseconds, microseconds, dB, number, kilobytes, bytes, ethernetFrames, packets, users
- ], comment: "units of measure for the measurement result"},
-
- measType: { presence: required, comment: "measurement name in 3GPP or
- vendor-specific format;
-
- vendor specific names are preceded with VS"}
-
- ]}
-
- }}
+ pmDictionary: {
+ presence: required,
+ structure: {
+ pmDictionaryHeader: {
+ presence: required,
+ structure: {
+ nfType: {
+ presence: required,
+ comment: "NF type; should match the string used in the perf3gpp eventName"
+ },
+ pmDefSchemaVsn: {
+ presence: required,
+ value: 1.0,
+ comment: "PM Dictionary Schema Version"
+ },
+ pmDefVsn: {
+ presence: required,
+ comment: "vendor-defined PM Dictionary version"
+ },
+ vendor: {
+ presence: required,
+ comment: "vendor of the NF type"
+ }
+ }
+ },
+ pmDictionaryMeasurements: {
+ presence: required,
+ array: [
+ iMeasInfoId: {
+ presence: required,
+ comment: "vendor-defined integer measurement group identifier"
+ },
+ iMeasType: {
+ presence: required,
+ comment: "vendor-defined integer identifier for the measType; must be combined with measInfoId to identify a specific measurement."
+ },
+ measAdditionalFields: {
+ presence: required,
+ comment: "vendor-specific PM Dictionary fields",
+ array: [
+ keyValuePair: {
+ presence: required,
+ structure: {
+ key: {
+ presence: required,
+ value: measAggregationLevels,
+ comment:"Nokia-specific field"
+ },
+ value: {
+ presence: required,
+ value: [NGBTS, NGCELL, IPNO, IPSEC, ETHIF],
+ comment: "list of one or more aggregation levels that Nokia recommends for this measurement; for example, if the value is NGBTS NGCELL, then Nokia recommends this measurement be aggregated on the 5G BTS level and the 5G Cell level"
+ }
+ }
+ }
+ ]
+ },
+ measChangeType: {
+ presence: required,
+ value: [added, modified, deleted],
+ comment: "indicates the type of change that occurred during measLastChange"
+ },
+ measCollectionMethod: {
+ presence: required,
+ value: [CC, SI, DER, Gauge, Average],
+ comment: "the measurement collection method; CC, SI, DER and Gauge are as defined in 3GPP; average contains the average value of the measurement during the granularity period"
+ },
+ measCondition: {
+ presence: required,
+ comment: "description of the condition causing the measurement"
+ },
+ measDescription: {
+ presence: required,
+ comment: "description of the measurement information and purpose"
+ },
+ measFamily: {
+ presence: required,
+ comment: "abbreviation for a family of measurements, in 3GPP format,or vendor defined"
+ },
+ measInfoId: {
+ presence: required,
+ comment: "name for a group of related measurements in 3GPP format or vendor defined"
+ },
+ measLastChange: {
+ presence: required,
+ comment: "version of the PM Dictionary the last time this measurement was added, modified or deleted"
+ },
+ measObjClass: {
+ presence: required,
+ value: [NGBTS, NGCELL, IPNO, IPSEC, ETHIF],
+ comment: "measurement object class"
+ },
+ measResultRange: {
+ presence: optional,
+ comment: "range of the measurement result; only necessary when the range is smaller than the full range of the data type"
+ },
+ measResultType: {
+ presence: required,
+ value: [float, unit32, uint64],
+ comment: "data type of the measurement result"
+ },
+ measResultUnits: {
+ presence: required,
+ value: [ seconds, minutes, nanoseconds, microseconds, dB, number, kilobytes, bytes, ethernetFrames, packets, users],
+ comment: "units of measure for the measurement result"
+ },
+ measType: {
+ presence: required,
+ comment: "measurement name in 3GPP or vendor-specific format; vendor specific names are preceded with VS"
+ }
+ ]
+ }
+ }
+ }
...
PM Dictionary Example
-~~~~~~~~~~~~~~~~~~~~~
++++++++++++++++++++++
The following is a sample PM Dictionary in both bracketed and
indent-style YAML formats
----
# PM Dictionary perf3gpp measurements for the Nokia gnb NF (bracket
style yaml)
-.. code-block:: text
+.. code-block:: yaml
+
pmDictionary: {
pmDictionaryHeader: {
-
nfType: gnb,
-
pmDefSchemaVsn: 1.0,
-
pmDefVsn: 5G19\_1906\_002,
-
- vendor: Nokia
-
- },
-
+ vendor: Nokia },
pmDictionaryMeasurements: [
-
{
-
- iMeasInfoId: 2204,
-
- iMeasType: 1,
-
- measAdditionalFields: {
-
- measAggregationLevels: "NGBTS NGCELL",
-
- },
-
- measCollectionMethod: CC,
-
- measCondition: "This measurement is updated when X2AP: SgNB Modification Required message is sent to MeNB with the SCG Change Indication set as PSCellChange.",
-
- measDescription: "This counter indicates the number of intra gNB intra
- frequency PSCell change attempts.",
-
- measFamily: NINFC,
-
- measInfoId: "NR Intra Frequency PSCell Change",
-
- measLastChange: 5G18A\_1807\_003,
-
- measObjClass: NGCELL,
-
- measResultRange: 0..4096,
-
- measResultType: integer,
-
- measResultUnits: number,
-
- measType: VS.NINFC.IntraFrPscelChAttempt
-
- },
-
+ iMeasInfoId: 2204,
+ iMeasType: 1,
+ measAdditionalFields: { measAggregationLevels: "NGBTS NGCELL"},
+ measCollectionMethod: CC,
+ measCondition: "This measurement is updated when X2AP: SgNB Modification Required message is sent to MeNB with the SCG Change Indication set as PSCellChange.",
+ measDescription: "This counter indicates the number of intra gNB intra frequency PSCell change attempts.",
+ measFamily: NINFC,
+ measInfoId: "NR Intra Frequency PSCell Change",
+ measLastChange: 5G18A\_1807\_003,
+ measObjClass: NGCELL,
+ measResultRange: 0..4096,
+ measResultType: integer,
+ measResultUnits: number,
+ measType: VS.NINFC.IntraFrPscelChAttempt},
{
-
- iMeasInfoId: 2204,
-
- iMeasType: 2,
-
- measAdditionalFields: {
-
- measAggregationLevels: "NGBTS NGCELL",
-
- },
-
- measCollectionMethod: CC,
-
- measCondition: "This measurement is updated when the TDCoverall timer
- has elapsed before gNB receives the X2AP: SgNB Modification Confirm
- message.",
-
- measDescription: "This measurement the number of intra gNB intra
- frequency PSCell change failures due to TDCoverall timer expiry.",
-
- measFamily: NINFC,
-
- measInfoId: "NR Intra Frequency PSCell Change",
-
- measLastChange: 5G18A\_1807\_003,
-
- measObjClass: NGCELL,
-
- measResultRange: 0..4096,
-
- measResultType: integer,
-
- measResultUnits: number,
-
- measType: VS.NINFC.IntraFrPscelChFailTdcExp
-
- },
-
+ iMeasInfoId: 2204,
+ iMeasType: 2,
+ measAdditionalFields: {measAggregationLevels: "NGBTS NGCELL"},
+ measCollectionMethod: CC,
+ measCondition: "This measurement is updated when the TDCoverall timer has elapsed before gNB receives the X2AP: SgNB Modification Confirm message.",
+ measDescription: "This measurement the number of intra gNB intra frequency PSCell change failures due to TDCoverall timer expiry.",
+ measFamily: NINFC,
+ measInfoId: "NR Intra Frequency PSCell Change",
+ measLastChange: 5G18A\_1807\_003,
+ measObjClass: NGCELL,
+ measResultRange: 0..4096,
+ measResultType: integer,
+ measResultUnits: number,
+ measType: VS.NINFC.IntraFrPscelChFailTdcExp},
{
-
- iMeasInfoId: 2204,
-
- iMeasType: 3,
-
- measAdditionalFields: {
-
- measAggregationLevels: "NGBTS NGCELL",
-
- },
-
- measCondition: "This measurement is updated when MeNB replies to X2AP:
- SgNB Modification Required message with the X2AP: SgNB Modification
- Refuse message.",
-
- measCollectionMethod: CC,
-
- measDescription: "This counter indicates the number of intra gNB intra
- frequency PSCell change failures due to MeNB refusal.",
-
- measFamily: NINFC,
-
- measInfoId: "NR Intra Frequency PSCell Change",
-
- measLastChange: 5G19\_1906\_002,
-
- measObjClass: NGCELL,
-
- measResultRange: 0..4096,
-
- measResultType: integer,
-
- measResultUnits: number,
-
- measType: VS.NINFC.IntraFrPscelChFailMenbRef
-
- }
-
- ]
-
+ iMeasInfoId: 2204,
+ iMeasType: 3,
+ measAdditionalFields: { measAggregationLevels: "NGBTS NGCELL"},
+ measCondition: "This measurement is updated when MeNB replies to X2AP: SgNB Modification Required message with the X2AP: SgNB Modification Refuse message.",
+ measCollectionMethod: CC,
+ measDescription: "This counter indicates the number of intra gNB intra frequency PSCell change failures due to MeNB refusal.",
+ measFamily: NINFC,
+ measInfoId: "NR Intra Frequency PSCell Change",
+ measLastChange: 5G19\_1906\_002,
+ measObjClass: NGCELL,
+ measResultRange: 0..4096,
+ measResultType: integer,
+ measResultUnits: number,
+ measType: VS.NINFC.IntraFrPscelChFailMenbRef }
+ ]
}
-.. code-block:: text
+.. code-block:: yaml
# PM Dictionary perf3gpp measurements for the Nokia gnb NF (indented
style yaml)
measCondition: "This measurement is updated when X2AP: SgNB Modification Required message is sent to MeNB with the SCG Change Indication set as PSCellChange."
- measDescription: "This counter indicates the number of intra gNB intra
- frequency PSCell change attempts."
+ measDescription: "This counter indicates the number of intra gNB intra frequency PSCell change attempts."
measFamily: NINFC
measCollectionMethod: CC
- measCondition: "This measurement is updated when the TDCoverall timer
- has elapsed before gNB receives the X2AP: SgNB Modification Confirm
- message."
+ measCondition: "This measurement is updated when the TDCoverall timer has elapsed before gNB receives the X2AP: SgNB Modification Confirm message."
- measDescription: "This measurement the number of intra gNB intra
- frequency PSCell change failures due to TDCoverall timer expiry."
+ measDescription: "This measurement the number of intra gNB intra frequency PSCell change failures due to TDCoverall timer expiry."
measFamily: NINFC
measCollectionMethod: CC
- measCondition: "This measurement is updated when MeNB replies to X2AP:
- SgNB Modification Required message with the X2AP: SgNB Modification
- Refuse message."
+ measCondition: "This measurement is updated when MeNB replies to X2AP: SgNB Modification Required message with the X2AP: SgNB Modification Refuse message."
- measDescription: "This counter indicates the number of intra gNB intra
- frequency PSCell change failures due to MeNB refusal."
+ measDescription: "This counter indicates the number of intra gNB intra frequency PSCell change failures due to MeNB refusal."
measFamily: NINFC
FM Meta Data
-------------
+~~~~~~~~~~~~~
FM Meta Data enables vendors to provide meta information about FM events
using a set of standard keywords. FM Meta Data is conveyed in the YAML
make machine processing of FM Meta Data Keywords easier to perform.
Alarm Meta Data Keywords
-~~~~~~~~~~~~~~~~~~~~~~~~
+++++++++++++++++++++++++++++
The following is a list of standard Alarm Meta Data Keywords. Note: the
keywords are in CAPS so they can be easily found within the YAML
+---------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Fault Meta Data Keywords
-~~~~~~~~~~~~~~~~~~~~~~~~
++++++++++++++++++++++++++
The following is a list of standard Fault Meta Data Keywords. Note: the
keywords are in CAPS so they can be easily found within the YAML
+---------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
FM Meta Data Example
-~~~~~~~~~~~~~~~~~~~~
++++++++++++++++++++++
The following is a snippet of a fault event registration showing use of
the FM Meta Data keywords. Note: it is recommended the information be
}
YAML Examples
-=============
+^^^^^^^^^^^^^
An example YAML file is provided below which registers some events for a
hypothetical VNF. Note: some of the lines have been manually
easier to rapidly find examples of different types of events.
Fault
------
+~~~~~~
-.. code-block:: text
+.. code-block:: yaml
# registration for Fault\_vMrf\_alarm003
}}
-.. code-block:: text
+.. code-block:: yaml
# registration for clearing Fault\_vMrf\_alarm003Cleared
}}
Heartbeat
----------
+~~~~~~~~~~
-.. code-block:: text
+.. code-block:: yaml
# registration for Heartbeat\_vMRF
Measurements
-------------
+~~~~~~~~~~~~~
-.. code-block:: text
+.. code-block:: yaml
# registration for Mfvs\_vMRF
Syslog
-------
+~~~~~~
-.. code-block:: text
+.. code-block:: yaml
# registration for Syslog\_vMRF
Mobile Flow
------------
+~~~~~~~~~~~
-.. code-block:: text
+.. code-block:: yaml
# registration for mobileFlow
Sip Signaling
--------------
+~~~~~~~~~~~~~~
-.. code-block:: text
+.. code-block:: yaml
# registration for sipSignaling
Voice Quality
--------------
+~~~~~~~~~~~~~~
-.. code-block:: text
+.. code-block:: yaml
# registration for voiceQuality
Rules
------
+~~~~~~
-.. code-block:: text
+.. code-block:: yaml
#Rules
Appendix: Historical Change Log
-===============================
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
For the latest changes, see the Change Block just before the Table of
Contents.
.. Copyright 2017 AT&T Intellectual Property, All rights reserved
.. Copyright 2017-2018 Huawei Technologies Co., Ltd.
-===============================
+.. _ves_event_listener_7_1:
+
Service: VES Event Listener 7.1
-===============================
+-------------------------------
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **Legal Disclaimer** |
.. contents:: Table of Contents
Introduction
-============
+^^^^^^^^^^^^
This document describes the RESTful interface for the VES Event
Listener. The VES acronym originally stood for Virtual-function Event
of streaming events.
Event Registration
-------------------
+~~~~~~~~~~~~~~~~~~
All events must be compliant with the common event format, but specific
events identified by their eventNames, may require that certain fields,
that should be performed on those eventNames.
Naming Standards for eventName
-------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To prevent naming collisions, eventNames sent as part of the
commonEventHeader, should conform to the following naming convention
- Other\_So:WanBonding\_InstantiationPart1Complete
EventId Use Cases Examples
---------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
[Author: Alok Gupta]:
.. image:: Use-Case-2.png
Measurement Expansion Fields
-----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When expansion fields are used, the goal is to avoid custom development
by the service provider collecting the fields, since custom development
and isHomogeneous keywords.
Syslogs
--------
+~~~~~~~~
Syslog’s can be classified as either Control or Session/Traffic. They
differ by message content and expected volume:
High volume session logging should use a file-based transport solution.
Support for Protocols Other Than HTTPS
---------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This API specification describes an HTTPS RESTful interface using the
JSON content-type.
Protobuf, websockets, or Apache Avro.
Versioning
-----------
+~~~~~~~~~~~
Three types of version numbers supported by this specification:
to the field descriptions) will increment only the minor number.
Field Block Versions
-~~~~~~~~~~~~~~~~~~~~
++++++++++++++++++++++
A summary of the latest field block version enums as of this version of
the API spec is provided below:
- voiceQualityFieldsVersion: 4.0
Security
-========
+^^^^^^^^
Event sources must identify themselves to the VES Event Listener.
Examples are provided below.
Sample Request and Response
----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sample Request
-~~~~~~~~~~~~~~
+++++++++++++++
+-----------------------------------------------------------------+
| POST /eventListener/v7 HTTP/1.1 |
+-----------------------------------------------------------------+
Sample Success Response
-~~~~~~~~~~~~~~~~~~~~~~~
+++++++++++++++++++++++++
+--------------------------+
| HTTPS/1.1 202 Accepted |
+--------------------------+
Mutual SSL Certificate Authentication
--------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If service provider VES Event Listener support for Mutual SSL
Certification Authentication is available, event sources must initialize
Authentication must be used as described above.
Resource Structure
-==================
+^^^^^^^^^^^^^^^^^^
REST resources are defined with respect to a ServerRoot:
eventsource when it is instantiated. The {Port} above is typically 8443.
Common Event Format
-===================
+^^^^^^^^^^^^^^^^^^^^
A JSON schema describing the Common Event Format is provided below and
is reproduced in the tables that follow.
capitalized.
Common Event Datatypes
-----------------------
+~~~~~~~~~~~~~~~~~~~~~~~~
Datatype: arrayOfJsonObject
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+++++++++++++++++++++++++++++
The arrayOfJsonObject datatype provides an array of json objects, each
of which is describ ed by name, schema and other meta-information. It
+---------------------+------------------+-------------+-----------------------+
Datatype: arrayOfNamedHashMap
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+++++++++++++++++++++++++++++++
The arrayOfNamedHashMap datatype provides an array of hashMaps, each of
which is associated with a descriptive name. It consists of the
+-----------------------+--------------------+-------------+-------------------------+
Datatype: event
-~~~~~~~~~~~~~~~
+++++++++++++++++
The event datatype consists of the following fields which constitute the
‘root level’ of the common event format:
+--------------------------------+--------------------------------+-------------+------------------------------------------------------+
Datatype: eventList
-~~~~~~~~~~~~~~~~~~~
+++++++++++++++++++++
The eventList datatype consists of the following fields:
+-------------+-------------+-------------+-------------------+
Datatype: hashMap
-~~~~~~~~~~~~~~~~~
++++++++++++++++++++
The hashMap datatype is an ‘associative array’, which is an unordered
collection of key-value pairs of the form “key”: “value”, where each key
acronyms; only the first letter of each acronym shall be capitalized.
Datatype: jsonObject
-~~~~~~~~~~~~~~~~~~~~
+++++++++++++++++++++
The jsonObject datatype provides a json object schema, name and other
meta-information along with one or more object instances that conform to
+--------------------------+--------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Datatype: jsonObjectInstance
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
++++++++++++++++++++++++++++++
The jsonObjectInstance datatype provides meta-information about an
instance of a jsonObject along with the actual object instance:
+-------------------------------+--------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------+
Datatype: key
-~~~~~~~~~~~~~
++++++++++++++++
The key datatype is a tuple which provides the name of a key along with
its value and relative order; it consists of the following fields:
+------------+-----------+-------------+----------------------------------------------------------------------+
Datatype: namedHashMap
-~~~~~~~~~~~~~~~~~~~~~~
+++++++++++++++++++++++++
The namedHashMap datatype is a hashMap which is associated with and
described by a name; it consists of the following fields:
+-----------+-----------+-------------+--------------------------------------------------+
Datatype: requestError
-~~~~~~~~~~~~~~~~~~~~~~
++++++++++++++++++++++++
The requestError datatype defines the standard request error data
structure:
+-------------+----------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Datatype: vendorNfNameFields
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
++++++++++++++++++++++++++++++
The vendorNfNameFields provides vendor, nf and nfModule identifying
information:
+----------------+----------+-------------+-----------------------------------------------------+
‘Common Event Header’ Datatypes
--------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Datatype: commonEventHeader
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+++++++++++++++++++++++++++++
The commonEventHeader datatype consists of the following fields common
to all events:
+---------------------------+-------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Datatype: internalHeaderFields
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+++++++++++++++++++++++++++++++
The internalHeaderFields datatype is an undefined object which can
contain arbitrarily complex JSON structures. It is intended to be
Listener.
Technology Independent Datatypes
---------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
‘Fault’ Domain Datatypes
-~~~~~~~~~~~~~~~~~~~~~~~~
++++++++++++++++++++++++++
Datatype: faultFields
-^^^^^^^^^^^^^^^^^^^^^
+*********************
The faultFields datatype consists of the following fields:
+-------------------------------+-----------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Heartbeat’ Domain Datatypes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+++++++++++++++++++++++++++++
Datatype: heartbeatFields
-^^^^^^^^^^^^^^^^^^^^^^^^^
+*************************
The heartbeatFields datatype is an optional field block for fields
specific to heartbeat events; it consists of the following fields:
+--------------------------+-----------+-------------+------------------------------------------------------------------------------------------------------------------+
‘Measurements’ Domain Datatypes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+++++++++++++++++++++++++++++++++
Note: NFs are required to report exactly one Measurement event per
period per sourceName.
Datatype: codecsInUse
-^^^^^^^^^^^^^^^^^^^^^
+*********************
The codecsInUse datatype consists of the following fields describing the
number of times an identified codec was used over the
+------------------+-----------+-------------+--------------------------------+
Datatype: cpuUsage
-^^^^^^^^^^^^^^^^^^
+*******************
The cpuUsage datatype defines the usage of an identifier CPU and
consists of the following fields:
+-------------------------+----------+-------------+-------------------------------------------------------------------------------------------------------------------------------------+
Datatype: diskUsage
-^^^^^^^^^^^^^^^^^^^
+********************
The diskUsage datatype defines the usage of a disk and consists of the
following fields:
+-----------------------------+----------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Datatype: filesystemUsage
-^^^^^^^^^^^^^^^^^^^^^^^^^
+***************************
The filesystemUsage datatype consists of the following fields:
+-----------------------+----------+-------------+--------------------------------------------------------+
Datatype: hugePages
-^^^^^^^^^^^^^^^^^^^
+********************
The hugePages datatype provides metrics on system hugePages; it consists
of the following fields:
+-----------------------+----------+-------------+---------------------------------------+
Datatype: ipmi (Intelligent Platform Management Interface)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+***********************************************************
The ipmi datatype provides intelligent platform management interface
metrics; it consists of the following fields:
+---------------------------------------+--------------------------------------+-------------+---------------------------------------------------+
Datatype: ipmiBaseboardTemperature
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+************************************
The ipmiBaseboardTemperature datatype consists of the following fields
which describe ipmi baseboard temperature metrics:
+-----------------------------------+----------+-------------+--------------------------------------------------------------+
Datatype: ipmiBaseboardVoltageRegulator
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+*****************************************
The ipmiBaseboardVoltageRegulator datatype consists of the following
fields which describe ipmi baseboard voltage regulator metrics:
+----------------------------------------+----------+-------------+--------------------------------------------------+
Datatype: ipmiBattery
-^^^^^^^^^^^^^^^^^^^^^
+**********************
The ipmiBattery datatype consists of the following fields which describe
ipmi battery metrics:
+-----------------------+----------+-------------+------------------------------+
Datatype: ipmiFan
-^^^^^^^^^^^^^^^^^
+********************
The ipmiFan datatype consists of the following fields which describe
ipmi fan metrics:
+-----------------+----------+-------------+---------------------------------------------+
Datatype: ipmiGlobalAggregateTemperatureMargin
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+***********************************************
The ipmiGlobalAggregateTemperatureMargin datatype consists of the
following fields:
+----------------------------------------------+----------+-------------+-----------------------------------------------------------------------------+
Datatype: ipmiHsbp
-^^^^^^^^^^^^^^^^^^
+*******************
The ipmiHsbp datatype provides ipmi hot swap backplane power metrics; it
consists of the following fields:
+-------------------+----------+-------------+----------------------------------------------------+
Datatype: ipmiNic
-^^^^^^^^^^^^^^^^^
+******************
The ipmiNic datatype provides network interface control care metrics; it
consists of the following fields:
+------------------+----------+-------------+-----------------------------------------------------+
Datatype: ipmiPowerSupply
-^^^^^^^^^^^^^^^^^^^^^^^^^
+**************************
The ipmiPowerSupply datatype provides ipmi power supply metrics; it
consists of the following fields:
+------------------------------------+----------+-------------+------------------------------------------------------------------------+
Datatype: ipmiProcessor
-^^^^^^^^^^^^^^^^^^^^^^^
+************************
The ipmiProcessor datatype provides ipmi processor metrics; it consists
of the following fields:
+---------------------------------------------+---------------------------------------------+-------------+---------------------------------------------------------+
Datatype: latencyBucketMeasure
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+*******************************
The latencyBucketMeasure datatype consists of the following fields which
describe the number of counts falling within a defined latency bucket:
+--------------------------+----------+-------------+------------------------------------------------------------+
Datatype: load
-^^^^^^^^^^^^^^
+****************
The load datatype provides metrics on system cpu and io utilization
obtained using /proc/loadavg; it consists of the following fields:
+-------------+----------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+
Datatype: machineCheckException
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+********************************
The machineCheckException datatype describes machine check exceptions;
it consists of the following fields:
+---------------------------------+----------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Datatype: measurementFields
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+****************************
The measurementFields datatype consists of the following fields:
+------------------------------+-----------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Datatype: memoryUsage
-^^^^^^^^^^^^^^^^^^^^^
+**********************
The memoryUsage datatype defines the memory usage of a virtual machine
and consists of the following fields:
+------------------------+----------+-------------+-----------------------------------------------------------------------------------------------------------------------------------+
Datatype: nicPerformance
-^^^^^^^^^^^^^^^^^^^^^^^^
+*************************
The nicPerformance datatype consists of the following fields which
describe the performance and errors of an of an identified virtual
+------------------------------------------+----------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Datatype: processorDimmAggregateThermalMargin
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+**********************************************
The processorDimmAggregateThermalMargin datatype provides intelligent
platform management interface (ipmi) processor dual inline memory module
+--------------------------------------------------+----------+-------------+-------------------------------------------------------------------------------------------------------------------+
Datatype: processStats
-^^^^^^^^^^^^^^^^^^^^^^
+***********************
The processStats datatype provides metrics on system processes; it
consists of the following fields:
+---------------------+----------+-------------+-------------------------------------------------------+
‘Notification’ Domain Datatypes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+++++++++++++++++++++++++++++++++
Datatype: notificationFields
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+******************************
The notificationFields datatype consists of the following fields:
Other notificationFields are not used for fileReady.
‘Other’ Domain Datatypes
-~~~~~~~~~~~~~~~~~~~~~~~~
++++++++++++++++++++++++++
Datatype: otherFields
-^^^^^^^^^^^^^^^^^^^^^
+**********************
The otherFields datatype defines fields for events belonging to the
'other' domain of the commonEventHeader domain enumeration; it consists
+-----------------------+-----------------------+-------------+--------------------------------------------------------------------------------------------------------------+
‘perf3gpp’ Domain Datatypes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+++++++++++++++++++++++++++++
Datatype: measDataCollection
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+*****************************
The measDataCollection datatype defines a 3GPP measurement collection
structure aligned with the 3GPP PM format; it consists of the following
+---------------------------------+----------------+-------------+------------------------------------------------------------------------------------+
Datatype: measInfo
-^^^^^^^^^^^^^^^^^^
+********************
The measInfo datatype provides measurement information; it consists of
the following fields:
+--------------+-------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------+
Datatype: measInfoIdInteger
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+****************************
The measInfoIdInteger datatype provides an integer measurement group
identifier; it consists of the following fields:
+---------------+-----------+-------------+----------------------------------------+
Datatype: measInfoIdString
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+***************************
The measInfoIdString datatype provides a string measurement group
identifier; it consists of the following fields:
+---------------+-----------+-------------+---------------------------------------+
Datatype: measResultInteger
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+****************************
The measResultInteger datatype provides an integer 3GPP PM measurement
result; it consists of the following fields:
+----------+-----------+-------------+------------------------------------+
Datatype: measResultNull
-^^^^^^^^^^^^^^^^^^^^^^^^
+*************************
The measResultNull datatype provides a null 3GPP PM measurement result;
it consists of the following fields:
+----------+-----------+-------------+------------------------------------+
Datatype: measResultNumber
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+***************************
The measResultNumber datatype provides a number 3GPP PM measurement
result; it consists of the following fields:
+----------+-----------+-------------+------------------------------------+
Datatype: measResultString
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+***************************
The measResultString datatype provides a string 3GPP PM measurement
result; it consists of the following fields:
+----------+-----------+-------------+------------------------------------+
Datatype: measTypesInteger
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+***************************
The measTypesInteger datatype provides an array of integer measurement
identifiers associated with the measurement results; it consists of the
+------------------+---------------+-------------+------------------------------------------------------------------------------------+
Datatype: measTypesString
-^^^^^^^^^^^^^^^^^^^^^^^^^
+**************************
The measTypesString datatype provides an array of string measurement
identifiers associated with the measurement results; it consists of the
+------------------+--------------+-------------+-----------------------------------------------------------------------------------+
Datatype: measValues
-^^^^^^^^^^^^^^^^^^^^
+*********************
The measValues datatype provides 3GPP measurement values; it consists of
the following fields:
+-------------------+---------------------------------------------------------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------+
Datatype: perf3gppFields
-^^^^^^^^^^^^^^^^^^^^^^^^
+*************************
The perf3gppFields datatype defines fields for 3GPP PM format events,
based on 3GPP TS 28.550, belonging to the 'perf3gpp' domain of the
+-------------------------+----------------------+-------------+-----------------------------------------+
‘pnfRegistration’ Domain Datatypes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+++++++++++++++++++++++++++++++++++++
Datatype: pnfRegistrationFields
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+********************************
The pnfRegistrationFields datatype defines fields for events belonging
to the 'pnfRegistration' domain of the commonEventHeader domain
+--------------------------------+-----------+-------------+------------------------------------------------------------------------------------------------------------------------+
‘State Change’ Domain Datatypes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+++++++++++++++++++++++++++++++++
Datatype: stateChangeFields
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+*****************************
The stateChangeFields datatype consists of the following fields:
+----------------------------+-----------+-------------+--------------------------------------------------------------------------------------------------------------------+
‘Syslog’ Domain Datatypes
-~~~~~~~~~~~~~~~~~~~~~~~~~
+++++++++++++++++++++++++++
Datatype: syslogFields
-^^^^^^^^^^^^^^^^^^^^^^
+***********************
The syslogFields datatype consists of the following fields:
https://www.iana.org/assignments/syslog-parameters/syslog-parameters.xhtml
‘Threshold Crossing Alert’ Domain Datatypes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+++++++++++++++++++++++++++++++++++++++++++++
Datatype: counter
-^^^^^^^^^^^^^^^^^
+******************
The counter datatype consists of the following fields:
+---------------------+-----------+-------------+--------------------------------------------------------------------------------+
Datatype: thresholdCrossingAlertFields
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+****************************************
The thresholdCrossingAlertFields datatype consists of the following
fields:
+-----------------------------------+---------------+-------------+-------------------------------------------------------------------------------------------------------------------------------+
Technology Specific Datatypes
------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Mobile Flow’ Domain Datatypes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+++++++++++++++++++++++++++++++
Datatype: gtpPerFlowMetrics
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+****************************
The gtpPerFlowMetrics datatype consists of the following fields:
+------------------------------------+-----------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Datatype: mobileFlowFields
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+***************************
The mobileFlowFields datatype consists of the following fields:
+---------------------------+----------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
‘SipSignaling’ Domain Datatypes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
++++++++++++++++++++++++++++++++
Datatype: sipSignalingFields
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+*****************************
The sipSignalingFields datatype communicates information about sip
signaling messages, parameters and signaling state; it consists of the
+-----------------------------+----------------------+-------------+---------------------------------------------------------------------------------------------------------------------+
‘Voice Quality’ Domain Datatypes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
++++++++++++++++++++++++++++++++++
Datatype: endOfCallVqmSummaries
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+*********************************
The endOfCallVqmSummaries datatype provides end of call voice quality
metrics; it consists of the following fields:
+---------------------------------+----------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Datatype: voiceQualityFields
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+*****************************
The voiceQualityFields datatype provides statistics related to customer
facing voice products; consists of the following fields:
+-----------------------------+--------------------------+-------------+---------------------------------------------------------------------------------------------------------------------+
Exceptions
-==========
+^^^^^^^^^^^
RESTful Web Services Exceptions
--------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
RESTful services generate and send exceptions to clients in response to
invocation errors. Exceptions send HTTP status codes (specified later in
+------------------+----------------------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Service Exceptions
-------------------
+~~~~~~~~~~~~~~~~~~~
When a service is not able to process a request, and retrying the
request with the same information will also result in a failure, and
Table - Service Exceptions
Policy Exceptions
------------------
+~~~~~~~~~~~~~~~~~~
When a service is not able to complete because the request fails to
meet a policy criteria, then the service will issue a fault using the
Table - Policy Exceptions
RESTful Web Services Definition
-===============================
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
REST Operation Overview
------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~
REST Operation Summary
-~~~~~~~~~~~~~~~~~~~~~~
++++++++++++++++++++++++
+------------------------+------------+----------------------------------------------------------------------------+
| **Operation Action** | **HTTP** | **Resource URL relative to {ServerRoot}, which is defined in section 3** |
Table - REST Operation Summary
Api Versioning
-~~~~~~~~~~~~~~
++++++++++++++++
apiVersion is used to describe the major version number of the event
listener API (which is the same as the major version number of this
patch version of 7.1, which is 7.1.0.
Buffering of Events
-~~~~~~~~~~~~~~~~~~~~
+++++++++++++++++++++
{ServerRoot} is defined in section 3 of this document, which defines the
REST resource URL. One or more FQDNs may be provisioned in an event
oldest events first).
Message Size
-~~~~~~~~~~~~
++++++++++++++++
Message size should be limited to 2 megabytes of uncompressed text sent
as application/json.
Operation: publishAnyEvent
---------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
Functional Behavior
-~~~~~~~~~~~~~~~~~~~
++++++++++++++++++++++
Allows authorized clients to publish any single event to the VES event
listener.
messages
Call Flow
-~~~~~~~~~
+++++++++++
.. image:: publish-event-flow.png
Figure - publishAnyEvent Call Flow
Input Parameters
-~~~~~~~~~~~~~~~~
++++++++++++++++++
Header Fields (note: all parameter names shall be treated as
case-insensitive):
+-----------------+-----------------+-----------------+-----------------------------------------------------------+
Output Parameters
-~~~~~~~~~~~~~~~~~
+++++++++++++++++++
Header fields:
+-----------------+-----------------+--------------------+----------------------------------+
HTTP Status Codes
-~~~~~~~~~~~~~~~~~
+++++++++++++++++++
+----------+-------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| *Code* | *Reason Phrase* | *Description* |
+----------+-------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Sample Request and Response
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+++++++++++++++++++++++++++++
Sample Request
-^^^^^^^^^^^^^^
+***************
+-------------------------------------------------------------------------------+
| POST /eventListener/v7 HTTP/1.1 |
+-------------------------------------------------------------------------------+
Sample Success Response
-^^^^^^^^^^^^^^^^^^^^^^^
+************************
+--------------------------+
| HTTPS/1.1 202 Accepted |
+--------------------------+
Sample Error Responses
-^^^^^^^^^^^^^^^^^^^^^^
+************************
Sample Policy Exception
-'''''''''''''''''''''''
+""""""""""""""""""""""""
+---------------------------------------------------------------+
| HTTPS/1.1 400 Bad Request |
+---------------------------------------------------------------+
Sample Service Exception
-''''''''''''''''''''''''
+"""""""""""""""""""""""""
+-----------------------------------------------------+
| HTTPS/1.1 400 Bad Request |
+-----------------------------------------------------+
Operation: publishEventBatch
-----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Functional Behavior
-~~~~~~~~~~~~~~~~~~~
++++++++++++++++++++
Allows authorized clients to publish a batch of events to the VES event
listener.
messages
Call Flow
-~~~~~~~~~
++++++++++++
.. image:: publish-event-flow.png
Figure – publishEventBatch Call Flow
Input Parameters
-~~~~~~~~~~~~~~~~
++++++++++++++++++
Header Fields (note: all parameter names shall be treated as
case-insensitive):
+-----------------+-----------------+-----------------+----------------------------------------------------------+
Output Parameters
-~~~~~~~~~~~~~~~~~
++++++++++++++++++++
Header fields:
+-----------------+-----------------+--------------------+----------------------------------+
HTTP Status Codes
-~~~~~~~~~~~~~~~~~
+++++++++++++++++++
+----------+-------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| *Code* | *Reason Phrase* | *Description* |
+----------+-------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Sample Request and Response
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
++++++++++++++++++++++++++++++
Sample Request
-^^^^^^^^^^^^^^
+****************
+-------------------------------------------------------------------------------+
| POST /eventListener/v7/eventBatch HTTP/1.1 |
+-------------------------------------------------------------------------------+
Sample Success Response
-^^^^^^^^^^^^^^^^^^^^^^^
+*************************
+--------------------------+
| HTTPS/1.1 202 Accepted |
+--------------------------+
Sample Error Responses
-^^^^^^^^^^^^^^^^^^^^^^
+************************
Sample Policy Exception
-'''''''''''''''''''''''
+""""""""""""""""""""""""
+---------------------------------------------------------------+
| HTTPS/1.1 400 Bad Request |
+---------------------------------------------------------------+
Sample Service Exception
-''''''''''''''''''''''''
+"""""""""""""""""""""""""
+-----------------------------------------------------+
| HTTPS/1.1 400 Bad Request |
+-----------------------------------------------------+
Terminology
-===========
+^^^^^^^^^^^^
Terminology used in this document is summarized below:
re-usable, and responsible for a single capability.
Appendix: Historical Change Log
-===============================
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
For the latest changes, see the Change Block just before the Table of
Contents.
Code Review / vnfrqts / requirements.git / commitdiff