summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorSteven Wright <sw3588@att.com>2019-05-29 13:00:08 +0000
committerGerrit Code Review <gerrit@onap.org>2019-05-29 13:00:08 +0000
commit6441ccbf69a50f6ea5eff890962215c00b0eefdf (patch)
tree82a35479a1cbdca451728250d5bb1a5c00c81bce
parent83003c307c92f8d240d9e894a4cfeb4ee278b82a (diff)
parent6cef7fd987f90b02e3b472fe31a4393aa52a7df4 (diff)
Merge "VNFRQTS - fixing links and formatting in VES"
-rw-r--r--conf.py5
-rwxr-xr-xdocs/Chapter7/Monitoring-And-Management.rst6
-rwxr-xr-xdocs/Chapter7/VNF-On-boarding-and-package-management.rst4
-rw-r--r--docs/Chapter8/VES_Registraion_3_2.rst960
-rw-r--r--docs/Chapter8/ves7_1spec.rst267
-rw-r--r--etc/requirements.txt4
6 files changed, 611 insertions, 635 deletions
diff --git a/conf.py b/conf.py
index db7c64f..7f9ea7b 100644
--- a/conf.py
+++ b/conf.py
@@ -138,7 +138,10 @@ html_theme = 'sphinx_rtd_theme'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
-#html_theme_options = {}
+html_theme_options = {
+ 'style_nav_header_background': 'white',
+ 'sticky_navigation': False
+ }
# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
diff --git a/docs/Chapter7/Monitoring-And-Management.rst b/docs/Chapter7/Monitoring-And-Management.rst
index da2a2bc..24ad489 100755
--- a/docs/Chapter7/Monitoring-And-Management.rst
+++ b/docs/Chapter7/Monitoring-And-Management.rst
@@ -319,7 +319,7 @@ Data Structure Specification of the Event Record
:updated: dublin
The VNF or PNF provider **MUST** provide a YAML file formatted in adherence with
- the :doc:`VES Event Registration specification <../../../../vnfsdk/model.git/docs/files/VESEventRegistration_3_0>`
+ the :ref:`VES Event Registration specification <ves_event_registration_3_2>`
that defines the following information for each event produced by the VNF:
* ``eventName``
@@ -339,7 +339,7 @@ Data Structure Specification of the Event Record
The VNF or PNF provider **MUST** indicate specific conditions that may arise, and
recommend actions that may be taken at specific thresholds, or if specific
conditions repeat within a specified time interval, using the semantics and
- syntax described by the :doc:`VES Event Registration specification <../../../../vnfsdk/model.git/docs/files/VESEventRegistration_3_0>`.
+ syntax described by the :ref:`VES Event Registration specification <ves_event_registration_3_2>`.
**NOTE:** The Service Provider may override VNF or PNF provider Event
Registrations using the ONAP SDC Design Studio to finalizes Service
@@ -361,7 +361,7 @@ These changes may modify any of the following:
The events produced by the VNF or PNF **MUST** must be compliant with the common
event format defined in the
- :doc:`VES Event Listener<../../../../vnfsdk/model.git/docs/files/VESEventListener_7_0_1>`
+ :ref:`VES Event Listener<ves_event_listener_7_1>`
specification.
.. req::
diff --git a/docs/Chapter7/VNF-On-boarding-and-package-management.rst b/docs/Chapter7/VNF-On-boarding-and-package-management.rst
index dc2800a..f170f30 100755
--- a/docs/Chapter7/VNF-On-boarding-and-package-management.rst
+++ b/docs/Chapter7/VNF-On-boarding-and-package-management.rst
@@ -132,7 +132,7 @@ Resource Description
:updated: dublin
:validation_mode: static
- The VNF or PNF package **MUST** provide :doc:`VES Event Registration <../../../../vnfsdk/model.git/docs/files/VESEventRegistration_3_0>`
+ The VNF or PNF package **MUST** provide :ref:`VES Event Registration <ves_event_registration_3_2>`
for all VES events provided by that VNF or PNF.
.. req::
@@ -332,7 +332,7 @@ Resource Control Loop
The VNF or PNF Package **MUST** include documentation which must include
all events (fault, measurement for VNF or PNF Scaling, Syslogs, State Change
- and Mobile Flow), that need to be collected at each VM, VNFC (defined in `VNF Guidelines <https://onap.readthedocs.io/en/latest/submodules/vnfrqts/guidelines.git/docs/vnf_guidelines/vnf_guidelines.html>`__ ) and for the overall VNF or PNF.
+ and Mobile Flow), that need to be collected at each VM, VNFC (defined in `VNF Guidelines <https://onap.readthedocs.io/en/latest/submodules/vnfrqts/guidelines.git/docs/vnf_guidelines.html>`__ ) and for the overall VNF or PNF.
.. req::
diff --git a/docs/Chapter8/VES_Registraion_3_2.rst b/docs/Chapter8/VES_Registraion_3_2.rst
index a09953f..f05771e 100644
--- a/docs/Chapter8/VES_Registraion_3_2.rst
+++ b/docs/Chapter8/VES_Registraion_3_2.rst
@@ -3,19 +3,26 @@
.. 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 |
@@ -44,7 +51,7 @@ Service: VES Event Registration 3.2
+-----------------+------------------------------+
Introduction
-============
+^^^^^^^^^^^^
This document specifies a YAML format for the registration of VES
Events. The YAML format enables both human designers and applications to
@@ -63,7 +70,7 @@ introduces the concept of specific types of events, identified by
eventNames.
Audience
---------
+~~~~~~~~
This document is intended to support the following groups:
@@ -88,14 +95,14 @@ The Service Provided-created version of the YAML will be distributed to
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
@@ -121,7 +128,7 @@ value (e.g., ‘MINOR’), or to a subset of the possible enumerated values
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)
@@ -145,20 +152,20 @@ can support the receipt and processing of VNF events, without the need
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.
@@ -179,46 +186,49 @@ it appears in the the Service Design and Creation Environment).
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
@@ -226,13 +236,13 @@ registered, including any extensible fields (e.g., specific name-value
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
@@ -242,7 +252,7 @@ Semantics have been defined for the following types of meta-information
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
@@ -318,23 +328,27 @@ communicate the actions to be taken if that trigger occurs:
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.
@@ -375,27 +389,23 @@ Example 1:
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:
@@ -418,48 +428,30 @@ 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.
@@ -468,16 +460,18 @@ declare the array elements and will not communicate them anonymously.
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
@@ -497,37 +491,32 @@ A value may be castTo one and only one of the following data types:
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
@@ -537,30 +526,50 @@ particular fields or with the event as a whole.
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
@@ -575,22 +584,23 @@ and optionality as those described for the ‘action’ keyword.
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.
@@ -617,42 +627,48 @@ Examples:
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
@@ -669,12 +685,16 @@ Common Event Format.
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
@@ -682,24 +702,23 @@ object.
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
@@ -710,17 +729,17 @@ ports’).
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
@@ -735,89 +754,95 @@ single quotes.
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
@@ -825,15 +850,17 @@ brackets. Commas are used to separate rules.
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:
@@ -846,7 +873,7 @@ 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
@@ -867,27 +894,19 @@ file.
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
@@ -896,7 +915,7 @@ the action on). Future versions of this document may provide more
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
@@ -917,7 +936,7 @@ times in 5 minutes, OR, if condition D occurs 2 (or more) times in 10
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
@@ -942,7 +961,7 @@ The PM dictionary is supplied by NF vendors in two parts:
Dictionary Schema).
PM Dictionary Schema Keywords
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
++++++++++++++++++++++++++++++++++++
The following is a list of standard PM Dictionary Schema Keywords:
@@ -1001,244 +1020,204 @@ pmDictionaryMeasurements 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)
@@ -1271,8 +1250,7 @@ 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
@@ -1302,12 +1280,9 @@ style yaml)
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
@@ -1337,12 +1312,9 @@ style yaml)
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
@@ -1362,7 +1334,7 @@ style yaml)
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
@@ -1384,7 +1356,7 @@ Successive keywords must be separated by commas. These conventions will
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
@@ -1417,7 +1389,7 @@ comments. R / O refers to recommended / optional.
+---------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
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
@@ -1440,7 +1412,7 @@ comments. R / O refers to recommended / optional.
+---------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
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
@@ -1633,7 +1605,7 @@ conveyed in a human readable form similar to the example below:
}
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
@@ -1642,9 +1614,9 @@ breaks that interrupt this single file; they were added to make it
easier to rapidly find examples of different types of events.
Fault
------
+~~~~~~
-.. code-block:: text
+.. code-block:: yaml
# registration for Fault\_vMrf\_alarm003
@@ -1719,7 +1691,7 @@ Fault
}}
-.. code-block:: text
+.. code-block:: yaml
# registration for clearing Fault\_vMrf\_alarm003Cleared
@@ -1789,9 +1761,9 @@ Fault
}}
Heartbeat
----------
+~~~~~~~~~~
-.. code-block:: text
+.. code-block:: yaml
# registration for Heartbeat\_vMRF
@@ -1853,9 +1825,9 @@ Heartbeat
Measurements
-------------
+~~~~~~~~~~~~~
-.. code-block:: text
+.. code-block:: yaml
# registration for Mfvs\_vMRF
@@ -2392,9 +2364,9 @@ Measurements
Syslog
-------
+~~~~~~
-.. code-block:: text
+.. code-block:: yaml
# registration for Syslog\_vMRF
@@ -2589,9 +2561,9 @@ Syslog
Mobile Flow
------------
+~~~~~~~~~~~
-.. code-block:: text
+.. code-block:: yaml
# registration for mobileFlow
@@ -2826,9 +2798,9 @@ Mobile Flow
Sip Signaling
--------------
+~~~~~~~~~~~~~~
-.. code-block:: text
+.. code-block:: yaml
# registration for sipSignaling
@@ -2925,9 +2897,9 @@ Sip Signaling
Voice Quality
--------------
+~~~~~~~~~~~~~~
-.. code-block:: text
+.. code-block:: yaml
# registration for voiceQuality
@@ -3082,9 +3054,9 @@ Voice Quality
Rules
------
+~~~~~~
-.. code-block:: text
+.. code-block:: yaml
#Rules
@@ -3114,7 +3086,7 @@ Rules
Appendix: Historical Change Log
-===============================
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
For the latest changes, see the Change Block just before the Table of
Contents.
diff --git a/docs/Chapter8/ves7_1spec.rst b/docs/Chapter8/ves7_1spec.rst
index b9a4b6a..c4464ff 100644
--- a/docs/Chapter8/ves7_1spec.rst
+++ b/docs/Chapter8/ves7_1spec.rst
@@ -3,9 +3,10 @@
.. 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** |
@@ -49,7 +50,7 @@ Service: VES Event Listener 7.1
.. 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
@@ -76,7 +77,7 @@ transports which make use of persistent TCP connections for high volumes
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,
@@ -91,7 +92,7 @@ are required, what field values may be sent, and any special handling
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
@@ -192,7 +193,7 @@ below:
- Other\_So:WanBonding\_InstantiationPart1Complete
EventId Use Cases Examples
---------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
[Author: Alok Gupta]:
@@ -271,7 +272,7 @@ Rules:
.. 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
@@ -286,7 +287,7 @@ Registration specification and in particular the aggregationRole, castTo
and isHomogeneous keywords.
Syslogs
--------
+~~~~~~~~
Syslog’s can be classified as either Control or Session/Traffic. They
differ by message content and expected volume:
@@ -306,7 +307,7 @@ control logs or for lower volume session logs, less than 60k per hour.
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.
@@ -315,7 +316,7 @@ Alternative API specifications may be provided in future using Google
Protobuf, websockets, or Apache Avro.
Versioning
-----------
+~~~~~~~~~~~
Three types of version numbers supported by this specification:
@@ -345,7 +346,7 @@ 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:
@@ -385,7 +386,7 @@ the API spec is provided below:
- voiceQualityFieldsVersion: 4.0
Security
-========
+^^^^^^^^
Event sources must identify themselves to the VES Event Listener.
@@ -414,10 +415,10 @@ event contents. TLS 1.2 or higher must be used.
Examples are provided below.
Sample Request and Response
----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sample Request
-~~~~~~~~~~~~~~
+++++++++++++++
+-----------------------------------------------------------------+
| POST /eventListener/v7 HTTP/1.1 |
@@ -475,7 +476,7 @@ Sample Request
+-----------------------------------------------------------------+
Sample Success Response
-~~~~~~~~~~~~~~~~~~~~~~~
+++++++++++++++++++++++++
+--------------------------+
| HTTPS/1.1 202 Accepted |
@@ -488,7 +489,7 @@ Sample Success Response
+--------------------------+
Mutual SSL Certificate Authentication
--------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If service provider VES Event Listener support for Mutual SSL
Certification Authentication is available, event sources must initialize
@@ -500,7 +501,7 @@ event source certificates cannot be verified or if certificate subject
Authentication must be used as described above.
Resource Structure
-==================
+^^^^^^^^^^^^^^^^^^
REST resources are defined with respect to a ServerRoot:
@@ -516,7 +517,7 @@ The {Domain} or FQDN above is typically provisioned into each
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.
@@ -548,10 +549,10 @@ Note on extensible fields:
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
@@ -564,7 +565,7 @@ consists of the following fields:
+---------------------+------------------+-------------+-----------------------+
Datatype: arrayOfNamedHashMap
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+++++++++++++++++++++++++++++++
The arrayOfNamedHashMap datatype provides an array of hashMaps, each of
which is associated with a descriptive name. It consists of the
@@ -577,7 +578,7 @@ following fields:
+-----------------------+--------------------+-------------+-------------------------+
Datatype: event
-~~~~~~~~~~~~~~~
+++++++++++++++++
The event datatype consists of the following fields which constitute the
‘root level’ of the common event format:
@@ -613,7 +614,7 @@ The event datatype consists of the following fields which constitute the
+--------------------------------+--------------------------------+-------------+------------------------------------------------------+
Datatype: eventList
-~~~~~~~~~~~~~~~~~~~
+++++++++++++++++++++
The eventList datatype consists of the following fields:
@@ -624,7 +625,7 @@ 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
@@ -632,7 +633,7 @@ and value are strings. Keys must use camel casing to separate words and
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
@@ -655,7 +656,7 @@ the schema:
+--------------------------+--------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Datatype: jsonObjectInstance
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
++++++++++++++++++++++++++++++
The jsonObjectInstance datatype provides meta-information about an
instance of a jsonObject along with the actual object instance:
@@ -673,7 +674,7 @@ 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:
@@ -689,7 +690,7 @@ 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:
@@ -703,7 +704,7 @@ described by a name; it consists of the following fields:
+-----------+-----------+-------------+--------------------------------------------------+
Datatype: requestError
-~~~~~~~~~~~~~~~~~~~~~~
++++++++++++++++++++++++
The requestError datatype defines the standard request error data
structure:
@@ -721,7 +722,7 @@ structure:
+-------------+----------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Datatype: vendorNfNameFields
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
++++++++++++++++++++++++++++++
The vendorNfNameFields provides vendor, nf and nfModule identifying
information:
@@ -737,10 +738,10 @@ information:
+----------------+----------+-------------+-----------------------------------------------------+
‘Common Event Header’ Datatypes
--------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Datatype: commonEventHeader
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+++++++++++++++++++++++++++++
The commonEventHeader datatype consists of the following fields common
to all events:
@@ -788,7 +789,7 @@ to all events:
+---------------------------+-------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Datatype: internalHeaderFields
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+++++++++++++++++++++++++++++++
The internalHeaderFields datatype is an undefined object which can
contain arbitrarily complex JSON structures. It is intended to be
@@ -800,13 +801,13 @@ for efficient internal processing of events received by the VES Event
Listener.
Technology Independent Datatypes
---------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
‘Fault’ Domain Datatypes
-~~~~~~~~~~~~~~~~~~~~~~~~
++++++++++++++++++++++++++
Datatype: faultFields
-^^^^^^^^^^^^^^^^^^^^^
+*********************
The faultFields datatype consists of the following fields:
@@ -839,10 +840,10 @@ 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:
@@ -858,13 +859,13 @@ 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
@@ -879,7 +880,7 @@ measurementInterval:
+------------------+-----------+-------------+--------------------------------+
Datatype: cpuUsage
-^^^^^^^^^^^^^^^^^^
+*******************
The cpuUsage datatype defines the usage of an identifier CPU and
consists of the following fields:
@@ -923,7 +924,7 @@ consists of the following fields:
+-------------------------+----------+-------------+-------------------------------------------------------------------------------------------------------------------------------------+
Datatype: diskUsage
-^^^^^^^^^^^^^^^^^^^
+********************
The diskUsage datatype defines the usage of a disk and consists of the
following fields:
@@ -1045,7 +1046,7 @@ following fields:
+-----------------------------+----------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Datatype: filesystemUsage
-^^^^^^^^^^^^^^^^^^^^^^^^^
+***************************
The filesystemUsage datatype consists of the following fields:
@@ -1068,7 +1069,7 @@ The filesystemUsage datatype consists of the following fields:
+-----------------------+----------+-------------+--------------------------------------------------------+
Datatype: hugePages
-^^^^^^^^^^^^^^^^^^^
+********************
The hugePages datatype provides metrics on system hugePages; it consists
of the following fields:
@@ -1092,7 +1093,7 @@ 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:
@@ -1130,7 +1131,7 @@ metrics; it consists of the following fields:
+---------------------------------------+--------------------------------------+-------------+---------------------------------------------------+
Datatype: ipmiBaseboardTemperature
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+************************************
The ipmiBaseboardTemperature datatype consists of the following fields
which describe ipmi baseboard temperature metrics:
@@ -1144,7 +1145,7 @@ which describe ipmi baseboard temperature metrics:
+-----------------------------------+----------+-------------+--------------------------------------------------------------+
Datatype: ipmiBaseboardVoltageRegulator
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+*****************************************
The ipmiBaseboardVoltageRegulator datatype consists of the following
fields which describe ipmi baseboard voltage regulator metrics:
@@ -1158,7 +1159,7 @@ fields which describe ipmi baseboard voltage regulator metrics:
+----------------------------------------+----------+-------------+--------------------------------------------------+
Datatype: ipmiBattery
-^^^^^^^^^^^^^^^^^^^^^
+**********************
The ipmiBattery datatype consists of the following fields which describe
ipmi battery metrics:
@@ -1174,7 +1175,7 @@ ipmi battery metrics:
+-----------------------+----------+-------------+------------------------------+
Datatype: ipmiFan
-^^^^^^^^^^^^^^^^^
+********************
The ipmiFan datatype consists of the following fields which describe
ipmi fan metrics:
@@ -1188,7 +1189,7 @@ ipmi fan metrics:
+-----------------+----------+-------------+---------------------------------------------+
Datatype: ipmiGlobalAggregateTemperatureMargin
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+***********************************************
The ipmiGlobalAggregateTemperatureMargin datatype consists of the
following fields:
@@ -1202,7 +1203,7 @@ following fields:
+----------------------------------------------+----------+-------------+-----------------------------------------------------------------------------+
Datatype: ipmiHsbp
-^^^^^^^^^^^^^^^^^^
+*******************
The ipmiHsbp datatype provides ipmi hot swap backplane power metrics; it
consists of the following fields:
@@ -1216,7 +1217,7 @@ consists of the following fields:
+-------------------+----------+-------------+----------------------------------------------------+
Datatype: ipmiNic
-^^^^^^^^^^^^^^^^^
+******************
The ipmiNic datatype provides network interface control care metrics; it
consists of the following fields:
@@ -1230,7 +1231,7 @@ consists of the following fields:
+------------------+----------+-------------+-----------------------------------------------------+
Datatype: ipmiPowerSupply
-^^^^^^^^^^^^^^^^^^^^^^^^^
+**************************
The ipmiPowerSupply datatype provides ipmi power supply metrics; it
consists of the following fields:
@@ -1248,7 +1249,7 @@ consists of the following fields:
+------------------------------------+----------+-------------+------------------------------------------------------------------------+
Datatype: ipmiProcessor
-^^^^^^^^^^^^^^^^^^^^^^^
+************************
The ipmiProcessor datatype provides ipmi processor metrics; it consists
of the following fields:
@@ -1266,7 +1267,7 @@ 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:
@@ -1282,7 +1283,7 @@ 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:
@@ -1298,7 +1299,7 @@ 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:
@@ -1318,7 +1319,7 @@ it consists of the following fields:
+---------------------------------+----------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Datatype: measurementFields
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+****************************
The measurementFields datatype consists of the following fields:
@@ -1375,7 +1376,7 @@ 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:
@@ -1419,7 +1420,7 @@ 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
@@ -1508,7 +1509,7 @@ network interface card:
+------------------------------------------+----------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Datatype: processorDimmAggregateThermalMargin
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+**********************************************
The processorDimmAggregateThermalMargin datatype provides intelligent
platform management interface (ipmi) processor dual inline memory module
@@ -1523,7 +1524,7 @@ aggregate thermal margin metrics; it consists of the following fields:
+--------------------------------------------------+----------+-------------+-------------------------------------------------------------------------------------------------------------------+
Datatype: processStats
-^^^^^^^^^^^^^^^^^^^^^^
+***********************
The processStats datatype provides metrics on system processes; it
consists of the following fields:
@@ -1549,10 +1550,10 @@ consists of the following fields:
+---------------------+----------+-------------+-------------------------------------------------------+
‘Notification’ Domain Datatypes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+++++++++++++++++++++++++++++++++
Datatype: notificationFields
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+******************************
The notificationFields datatype consists of the following fields:
@@ -1607,10 +1608,10 @@ in 3GPP TS 28.550. The array contains the following key value pairs:
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
@@ -1629,10 +1630,10 @@ of the following fields:
+-----------------------+-----------------------+-------------+--------------------------------------------------------------------------------------------------------------+
‘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
@@ -1657,7 +1658,7 @@ fields:
+---------------------------------+----------------+-------------+------------------------------------------------------------------------------------+
Datatype: measInfo
-^^^^^^^^^^^^^^^^^^
+********************
The measInfo datatype provides measurement information; it consists of
the following fields:
@@ -1675,7 +1676,7 @@ the following fields:
+--------------+-------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------+
Datatype: measInfoIdInteger
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+****************************
The measInfoIdInteger datatype provides an integer measurement group
identifier; it consists of the following fields:
@@ -1687,7 +1688,7 @@ identifier; it consists of the following fields:
+---------------+-----------+-------------+----------------------------------------+
Datatype: measInfoIdString
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+***************************
The measInfoIdString datatype provides a string measurement group
identifier; it consists of the following fields:
@@ -1699,7 +1700,7 @@ 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:
@@ -1713,7 +1714,7 @@ 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:
@@ -1727,7 +1728,7 @@ it consists of the following fields:
+----------+-----------+-------------+------------------------------------+
Datatype: measResultNumber
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+***************************
The measResultNumber datatype provides a number 3GPP PM measurement
result; it consists of the following fields:
@@ -1741,7 +1742,7 @@ 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:
@@ -1755,7 +1756,7 @@ 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
@@ -1768,7 +1769,7 @@ following fields:
+------------------+---------------+-------------+------------------------------------------------------------------------------------+
Datatype: measTypesString
-^^^^^^^^^^^^^^^^^^^^^^^^^
+**************************
The measTypesString datatype provides an array of string measurement
identifiers associated with the measurement results; it consists of the
@@ -1781,7 +1782,7 @@ following fields:
+------------------+--------------+-------------+-----------------------------------------------------------------------------------+
Datatype: measValues
-^^^^^^^^^^^^^^^^^^^^
+*********************
The measValues datatype provides 3GPP measurement values; it consists of
the following fields:
@@ -1799,7 +1800,7 @@ 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
@@ -1817,10 +1818,10 @@ fields:
+-------------------------+----------------------+-------------+-----------------------------------------+
‘pnfRegistration’ Domain Datatypes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+++++++++++++++++++++++++++++++++++++
Datatype: pnfRegistrationFields
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+********************************
The pnfRegistrationFields datatype defines fields for events belonging
to the 'pnfRegistration' domain of the commonEventHeader domain
@@ -1857,10 +1858,10 @@ enumeration; it consists of the following fields:
+--------------------------------+-----------+-------------+------------------------------------------------------------------------------------------------------------------------+
‘State Change’ Domain Datatypes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+++++++++++++++++++++++++++++++++
Datatype: stateChangeFields
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+*****************************
The stateChangeFields datatype consists of the following fields:
@@ -1879,10 +1880,10 @@ The stateChangeFields datatype consists of the following fields:
+----------------------------+-----------+-------------+--------------------------------------------------------------------------------------------------------------------+
‘Syslog’ Domain Datatypes
-~~~~~~~~~~~~~~~~~~~~~~~~~
+++++++++++++++++++++++++++
Datatype: syslogFields
-^^^^^^^^^^^^^^^^^^^^^^
+***********************
The syslogFields datatype consists of the following fields:
@@ -2019,10 +2020,10 @@ https://tools.ietf.org/html/rfc5424#section-6
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:
@@ -2037,7 +2038,7 @@ The counter datatype consists of the following fields:
+---------------------+-----------+-------------+--------------------------------------------------------------------------------+
Datatype: thresholdCrossingAlertFields
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+****************************************
The thresholdCrossingAlertFields datatype consists of the following
fields:
@@ -2079,13 +2080,13 @@ fields:
+-----------------------------------+---------------+-------------+-------------------------------------------------------------------------------------------------------------------------------+
Technology Specific Datatypes
------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Mobile Flow’ Domain Datatypes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+++++++++++++++++++++++++++++++
Datatype: gtpPerFlowMetrics
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+****************************
The gtpPerFlowMetrics datatype consists of the following fields:
@@ -2194,7 +2195,7 @@ The gtpPerFlowMetrics datatype consists of the following fields:
+------------------------------------+-----------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Datatype: mobileFlowFields
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+***************************
The mobileFlowFields datatype consists of the following fields:
@@ -2269,10 +2270,10 @@ 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
@@ -2303,10 +2304,10 @@ following fields:
+-----------------------------+----------------------+-------------+---------------------------------------------------------------------------------------------------------------------+
‘Voice Quality’ Domain Datatypes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
++++++++++++++++++++++++++++++++++
Datatype: endOfCallVqmSummaries
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+*********************************
The endOfCallVqmSummaries datatype provides end of call voice quality
metrics; it consists of the following fields:
@@ -2374,7 +2375,7 @@ 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:
@@ -2402,10 +2403,10 @@ 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
@@ -2432,7 +2433,7 @@ exceptions may be defined: service exceptions and policy exceptions.
+------------------+----------------------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
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
@@ -2462,7 +2463,7 @@ Service Exceptions
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
@@ -2498,13 +2499,13 @@ Policy Exceptions
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** |
@@ -2519,7 +2520,7 @@ REST Operation Summary
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
@@ -2547,7 +2548,7 @@ request major version 7 with X-MinorVersion: 1, they will get the latest
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
@@ -2569,16 +2570,16 @@ discard events in a first-in, first-out (FIFO) manner (i.e., discard
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.
@@ -2593,14 +2594,14 @@ 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):
@@ -2636,7 +2637,7 @@ Body Fields:
+-----------------+-----------------+-----------------+-----------------------------------------------------------+
Output Parameters
-~~~~~~~~~~~~~~~~~
+++++++++++++++++++
Header fields:
@@ -2667,7 +2668,7 @@ Body Fields (for error responses):
+-----------------+-----------------+--------------------+----------------------------------+
HTTP Status Codes
-~~~~~~~~~~~~~~~~~
+++++++++++++++++++
+----------+-------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| *Code* | *Reason Phrase* | *Description* |
@@ -2686,10 +2687,10 @@ HTTP Status Codes
+----------+-------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Sample Request and Response
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+++++++++++++++++++++++++++++
Sample Request
-^^^^^^^^^^^^^^
+***************
+-------------------------------------------------------------------------------+
| POST /eventListener/v7 HTTP/1.1 |
@@ -2772,7 +2773,7 @@ Sample Request
+-------------------------------------------------------------------------------+
Sample Success Response
-^^^^^^^^^^^^^^^^^^^^^^^
+************************
+--------------------------+
| HTTPS/1.1 202 Accepted |
@@ -2785,10 +2786,10 @@ Sample Success Response
+--------------------------+
Sample Error Responses
-^^^^^^^^^^^^^^^^^^^^^^
+************************
Sample Policy Exception
-'''''''''''''''''''''''
+""""""""""""""""""""""""
+---------------------------------------------------------------+
| HTTPS/1.1 400 Bad Request |
@@ -2823,7 +2824,7 @@ Sample Policy Exception
+---------------------------------------------------------------+
Sample Service Exception
-''''''''''''''''''''''''
+"""""""""""""""""""""""""
+-----------------------------------------------------+
| HTTPS/1.1 400 Bad Request |
@@ -2866,10 +2867,10 @@ Sample Service Exception
+-----------------------------------------------------+
Operation: publishEventBatch
-----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Functional Behavior
-~~~~~~~~~~~~~~~~~~~
++++++++++++++++++++
Allows authorized clients to publish a batch of events to the VES event
listener.
@@ -2884,14 +2885,14 @@ 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):
@@ -2927,7 +2928,7 @@ Body Fields:
+-----------------+-----------------+-----------------+----------------------------------------------------------+
Output Parameters
-~~~~~~~~~~~~~~~~~
++++++++++++++++++++
Header fields:
@@ -2958,7 +2959,7 @@ Body Fields (for error responses):
+-----------------+-----------------+--------------------+----------------------------------+
HTTP Status Codes
-~~~~~~~~~~~~~~~~~
+++++++++++++++++++
+----------+-------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| *Code* | *Reason Phrase* | *Description* |
@@ -2977,10 +2978,10 @@ HTTP Status Codes
+----------+-------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Sample Request and Response
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
++++++++++++++++++++++++++++++
Sample Request
-^^^^^^^^^^^^^^
+****************
+-------------------------------------------------------------------------------+
| POST /eventListener/v7/eventBatch HTTP/1.1 |
@@ -3124,7 +3125,7 @@ Sample Request
+-------------------------------------------------------------------------------+
Sample Success Response
-^^^^^^^^^^^^^^^^^^^^^^^
+*************************
+--------------------------+
| HTTPS/1.1 202 Accepted |
@@ -3137,10 +3138,10 @@ Sample Success Response
+--------------------------+
Sample Error Responses
-^^^^^^^^^^^^^^^^^^^^^^
+************************
Sample Policy Exception
-'''''''''''''''''''''''
+""""""""""""""""""""""""
+---------------------------------------------------------------+
| HTTPS/1.1 400 Bad Request |
@@ -3175,7 +3176,7 @@ Sample Policy Exception
+---------------------------------------------------------------+
Sample Service Exception
-''''''''''''''''''''''''
+"""""""""""""""""""""""""
+-----------------------------------------------------+
| HTTPS/1.1 400 Bad Request |
@@ -3218,7 +3219,7 @@ Sample Service Exception
+-----------------------------------------------------+
Terminology
-===========
+^^^^^^^^^^^^
Terminology used in this document is summarized below:
@@ -3388,7 +3389,7 @@ It is a stand-alone executable that is loosely-coupled, granular,
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.
diff --git a/etc/requirements.txt b/etc/requirements.txt
index 21bd7e0..49b8c5e 100644
--- a/etc/requirements.txt
+++ b/etc/requirements.txt
@@ -15,13 +15,13 @@
#############################################################################
tox
-Sphinx==1.7
+Sphinx==1.8.4
doc8
docutils
docopt==0.6.2
setuptools
six
-sphinx_rtd_theme
+sphinx_rtd_theme>=0.4.3
sphinxcontrib-blockdiag
sphinxcontrib-httpdomain
sphinxcontrib-needs>=0.2.4