[netconf] A review of draft-ietf-netconf-adaptive-subscription

[Adrian Farrel <[e-mail]>]

Hi,

I had cause to read this draft and found a number of editorial clean-ups
that would be a benefit for readability. There are also one or two 
minor questions embedded - nothing that needs discussion, but the authors
might like to think about whether my questions need to be addressed by
changes of text (for clarity) or changes to technical content.

Thanks for the work.

Best,
Adrian
--
It's Christmas. 
Treat someone you love to a fairy story.
Books of fairy tales for adults of all ages:
. Tales from the Wood
. More Tales from the Wood
. Tales from Beyond the Wood
. Tales from the Castle
Get them on line https://www.feedaread.com/profiles/8604/
Get them from me at IETF-115 in London
Or buy a signed copy from me by post


===

Abstract

OLD
   This document defines a YANG data model and associated mechanism
   enabling the subscriber's adaptive subscriptions to a publisher's
   event streams with various different period intervals to report
   updates.  Applying these elements allows servers automatically adjust
   the rate and volume of telemetry traffic sent from a publisher to
   receivers.
NEW
   This document defines a YANG data model and associated mechanism
   that enable adaptive subscription to a publisher's event streams.
   The periodic update interval for the event streams can be set.
   Applying these elements allows servers to automatically adjust
   the rate and volume of telemetry traffic sent from a publisher to
   receivers.
END

---

1.  Introduction

   YANG-Push subscriptions [RFC8641] allow subscriber applications to
   request a continuous customized stream of updates from a YANG
   datastore without needing to poll.  It defines a mechanism (i.e.,
   update trigger) to determine when an update record needs to be
   generated.  Two types of subscriptions are introduced in [RFC8641],
s/subscriptions/subscription/
   distinguished by how updates are triggered: periodic and on-change.

---

1.  Introduction


OLD
   However in some large scale deployments (e.g., massive data
   collection for wireless network performance monitoring) where an
   increased data collection rate is used, it becomes more likely that
   both clients and servers are temporarily overwhelmed with a burst of
   streamed data and consumes expensive network resource (e.g.,
   bandwidth resource, radio resource) and computation resource,
   therefore hard to continuously monitor operational data, especially
   values that fall outside normal operational ranges.  If the rate at
   which we can collect a stream of data is set too low or chosen to get
   low priority telemetry data dropped, these telemetry data are not
   sufficient to detect and diagnose problems and verify correct network
   behavior.
NEW
   However, in some large-scale deployments (e.g., massive data
   collection for wireless network performance monitoring) where an
   increased data collection rate is used, it becomes more likely that
   both clients and servers could be temporarily overwhelmed with a
   burst of streamed data, and that network resources (e.g., bandwidth
   resource, radio resource) and computation resource could be
   excessively consumed.  Therefore, it may be hard to continuously
   monitor operational data, especially values that fall outside normal
   operational ranges.  Conversely, if the rate at which we collect a
   stream of data is set too low or chosen so that low priority
   telemetry data are dropped, these telemetry data will not be
   sufficient to detect and diagnose problems and to verify correct
   network behavior.
END

---

1.  Introduction

   A client might choose to monitor the operational state and send a
   request to modify the data collection rate on the server.  But how
   often the client evaluates if the modification of the data collection
   rate is required highly depends on the current collection rate,
s/,/:/
   collecting a stream of data at a low rate prevents the subscriber

---

1.  Introduction

   There is a need for a service to balance between data management cost
   and real time streaming telemetry.  To achieve this, servers can be
s/real time/real-time/
   configured with multiple different period intervals and corresponding
s/and/and a/
   subscription update policy which allows servers/publishers
   automatically switch to different period intervals according to the
s/automatically/to automatically/
   network condition change without the interaction with the client for
s/change/changes/
   policy update instruction, e.g., when the wireless signal strength
s/instruction, e.g.,/instructions.  E.g.,/
   falls below a configured threshold, the subscribed data can be
   streamed at a higher rate to capture potentially important data and
   events (e.g., continuous service degeneration); while when the
   wireless signal strength crosses a configured threshold, the
   subscribed data can be streamed at a lower rate.

---

1.  Introduction

OLD
   This document defines a YANG data model and associated mechanism
   enabling the subscriber's adaptive subscriptions to a publisher's
   event streams.  Applying these elements allows servers to
   automatically adjust the rate and volume of telemetry traffic sent
   from a publisher to receivers.
NEW
   This document defines a YANG data model and associated mechanism
   that enable adaptive subscription to a publisher's event streams.
   The periodic update interval for the event streams can be set.
   Applying these elements allows servers to automatically adjust
   the rate and volume of telemetry traffic sent from a publisher to
   receivers.
END

---

1.1.  Terminology

   Adaptive Subscription:  Apply subscription update policy on the
      servers and allow servers/publishers automatically switch to
s/automatically/to automatically/
      different period intervals according to the network condition
d/the/
      change without the interaction with the client for update policy
s/change/changes/
s/the interaction/interacting/
      instruction.
s/instruction/instructions/

---

2.1.  Subscription Configuration

   *  a "period" defines the new duration between push updates.  The
      period can be switched based on trigger conditions;
>>> Centiseconds seems to be a fine granularity here.  I wonder what it
>>> would really mean if period was set to 0.01 seconds.  Perhaps you
>>> could provide some advice about not setting this field to a low
>>> value.

---

2.1.  Subscription Configuration

      How often the XPath expression criterion is evaluated is up to the
      publisher's implementation.  With minimal delay, the expression
      can be evaluated whenever changes to targeted data object occur,
      or at the end of each higher frequency streaming update period.
      To reduce the frequency of evaluation, the server can choose to
      check targeted object change at every multiple (e.g.,2 or 3) high-
      frequency streaming update periods.

>>> I cannot work out here whether the period and xpath-external-eval
>>> are mutually exclusive, can both be present independently, or are
>>> co-dependent. In particular, if the period is set, one might need to
>>> know whether the XPath expression is required to be evaluated at
>>> least as frequently as the period value.  That is, if the object
>>> is being streamed anyway, why would you bother evaluating the
>>> expression?

---

2.1.  Subscription Configuration


      For the cases where multiple list instances are needed to handle
      in "xpath-external-eval", XPath abbreviated syntax can be used to
s/in/an/
      identify a particular instance, e.g., to represent a comparison
      for a leaf in a list entry:

---

2.1.  Subscription Configuration


   Note that the adaptive subscription may not be supported by every
s/may/need/
   YANG datastore node.  A publisher MAY decide to simply reject an
   adaptive subscription with "adaptive-unsupported" (defined in
   Section 2.2.1.1) if the scope of the subscription contains selected
   data nodes for which adaptive subscription is not supported.

---

2.2.1.  "establish-subscription" RPC

   The augmentation of YANG module "ietf-yang-push" made to RPCs
   specified in YANG module "ietf-subscribed-notifications" [RFC8639] is
   introduced.  This augmentation concerns the "establish-subscription"
   RPC, which is augmented with parameters that are needed to specify a
   subscriber's adaptive subscriptions.  These parameters are the same
   as ones defined in Section 2.1.
s/as/as the/

---

2.2.1.1.  RPC Failures

>>> I think the next three paragraphs should begin with lowercase
>>> letters because the names of the errors are all lowercase.

   Adaptive-unsupported is used to indicate that the adaptive
   subscription is not supported for any objects that are selectable by
   the filter.

   Xpath-evaluation-unsupported is used to indicate that a server fails
   to parse syntax defined in "xpath-external-eval".  The failure can be
   caused by either a syntax error or some XPath 1.0 syntax not
   supported against the specific object.

   Multi-xpath-criteria-conflict is used to indicate that the multiple
   Xpath evaluation criteria represented by "xpath-external-eval" is
   evaluated as conflict, i.e., more than one condition expressions are
   evaluated to "true".  However, the publisher should still push
   updates at the higher frequency streaming period if multiple Xpath
   evaluations conflict with each other during the lifecycle of an
   adaptive subscription.

---

2.2.1.1.  RPC Failures

   Xpath-evaluation-unsupported is used to indicate that a server fails
s/fails/failed/

---

2.2.1.1.  RPC Failures

   Multi-xpath-criteria-conflict is used to indicate that the multiple
   Xpath evaluation criteria represented by "xpath-external-eval" is
/is/are/
   evaluated as conflict, i.e., more than one condition expressions are
s/conflict/conflicting/

---

2.2.1.1.  RPC Failures

   For an example of how above RPC errors can be returned, see the
s/above/the above/
   "xpath-evaluation-unsupported" error response illustrated in
   Appendix B.3.

---

2.3.  Notifications for Adaptive Subscribed Content

   The adaptive update notification is similar to subscription state
   change notifications defined in [RFC8639].  It is inserted into the
   sequence of notification messages sent to a particular receiver.  As
   stated in RFC 8639, section 2.7, the adaptive update notification
   cannot be dropped or filtered out, it cannot be stored in replay
   buffers, and it is delivered only to impacted receivers of a
   subscription.  The identification of adaptive update notification is
s/of/of the/

---

2.3.  Notifications for Adaptive Subscribed Content

   *  A selection filter is to identify YANG nodes of interest in a
d/is/
      datastore.  Filter contents are specified via a reference to an
      existing filter or via an in-line definition for only that
      subscription based on XPath Evaluation criteria defined in section
      6.4 of [RFC7950].  Referenced filters allow an implementation to
      avoid evaluating filter acceptability during a dynamic
      subscription request.  The "case" statement differentiates the
      options.  Note that filter contents are not affected by "xpath-
s/by/by the/
      external-eval" parameter defined by the update trigger.

---

3.  XPath Complexity Evaluation

   *  Support more than one target object selection and operation(e.g.,
s/operation(e.g.,/operation (e.g.,/
      addition, subtraction, division and multiplication) in the XPath
      evaluation criterion;

---

3.  XPath Complexity Evaluation

   *  Support any type of node set in the XPath evaluation criterion,
      e.g., string,int64, uint64, and decimal64 types;
s/string,int64/string, int64/

---

3.  XPath Complexity Evaluation

   As described in section 6.4 of RFC7950, Numbers in XPath 1.0 are IEEE
   754 [IEEE754-2008] double-precision floating-point values; some
>>> Need to add this to the references section
   values of int64, uint64, and decimal64 types cannot be exactly
   represented in XPath expressions.

---

3.  XPath Complexity Evaluation

   If two objects to be compared are in different data types, conversion
s/types,/types, a/
   function is needed to convert different data types into numbers.

---

3.  XPath Complexity Evaluation

   *  One object to be compared in the XPath Evaluation criteria MUST be
      a leaf data node.
>>> This list of bullets begins with a lower case "recommended" and
>>> these are just design principles.  Using a "MUST" in this context is
>>> odd. Possibly s/MUST be/is/

---

3.  XPath Complexity Evaluation

   *  The other object to be compared in the XPath Evaluation criteria
      MUST be a number data type.
>>> I would combine this bullet with the previous so you end up with...
>>>*  One object to be compared in the XPath Evaluation criteria is a
>>>   leaf data node and the other object is a number data type.

---

3.  XPath Complexity Evaluation

   If a server receives an XPath Evaluation criterion with some XPath
   syntax unsupported against the specific object, an RPC error with
   "xpath-evaluation-unsupported" should be returned.
>>> I think this is at least "SHOULD" (in which case, you need to say
>>> why you would not return such an error), but possibly "MUST".

---

4.  Adaptive Subscription YANG Module

>>> You need to have include RFC 6991 in your references (because of the
>>> import).  I suggest you add the following text at this point in the
>>> document.
>>>This YANG model makes imports from [RFC8639], [RFC8641], and
>>>[RFC6991].

---

4.  Adaptive Subscription YANG Module

>>> There are a few line-length problems in this YANG

---

4.  Adaptive Subscription YANG Module

     namespace "urn:ietf:params:xml:ns:yang:ietf-adaptive-subscription";
>>> I recall some discussions about trying to keep namespace entries
>>> short. Such as ...:ietf-adsub

---

4.  Adaptive Subscription YANG Module

     identity xpath-evaluation-unsupported {
       base sn:establish-subscription-error;
       description
         "Unable to parse the xpath evaluation criteria defined in
          'xpath-external-eval' because a syntax error or some
s/because/because of/
          XPath 1.0 syntax not supported against the specific object.";
     }

---

4.  Adaptive Subscription YANG Module

     identity multi-xpath-criteria-conflict {
       base sn:establish-subscription-error;
       base sn:subscription-terminated-reason;
       description
OLD
         "Multiple Xpath evaluation criteria represented by
          'xpath-external-eval' is evaluated as conflict, i.e.,
          more than one condition expressions are evaluated to
          'true'.";
NEW
         "Multiple Xpath evaluation criteria represented by
          'xpath-external-eval' are evaluated as a conflict.  I.e.,
          more than one condition expression is evaluated to
          'true'.";
END

---

4.  Adaptive Subscription YANG Module

     grouping adaptive-subscription-modifiable {
       description
         "This grouping describes the datastore-specific adaptive
subscription
          conditions that can be changed during the lifetime of the
          subscription.";
       container adaptive-subscriptions {
         list adaptive-period {
           key "name";
           description
             "Defines necessary conditions to switch update interval for
s/switch/switch the/
              sending an event record to the subscriber. The event record
output
              generation will not be influenced these conditions.";

---

4.  Adaptive Subscription YANG Module

           leaf xpath-external-eval {
             type string;
             mandatory true;
             description
               "A XPath string, representing a logical expression,
s/A/An/
                which can contain comparisons of datastore values
                and logical operations in the XPath format.";
           }

---

4.  Adaptive Subscription YANG Module

           leaf anchor-time {
             type yang:date-and-time;
             description
               "Designates a timestamp before or after which a series
                of periodic push updates are determined.  The next
s/are/is/
                update will take place at a point in time that is a

---

4.  Adaptive Subscription YANG Module

       leaf anchor-time {
         type yang:date-and-time;
         description
           "Designates a timestamp before or after which a series
            of periodic push updates are determined.  The next
s/are/is/

---

Appendix A.  Example YANG Module

>>> I had to read Appendix B before I found out why Appendix A is
>>> present!
>>> You need to say that this example is provided so that Appendix B
>>> can give examples of how the YANG model defined in this document
>>> is used to perform adaptive subscription.

---

B.5.  Changes between Revisions

>>> This should be a new top-level Appendix (e.g., Appendix C)
>>> You should mark this with a request to the RFC Editor to remove this
>>> Appendix before publication as an RFC