draft-tgraf-yang-push-observation-time-00.xml

<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<?rfc toc="yes"?>
<?rfc tocompact="yes"?>
<?rfc tocdepth="2"?>
<?rfc tocindent="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<rfc category="std" docName="draft-tgraf-yang-push-observation-time-00"
     ipr="trust200902">
  <front>
    <title abbrev="YANG Notifications Observation Time">Support of Network
    Observation Timestamping in YANG Notifications</title>

    <author fullname="Thomas Graf" initials="T" surname="Graf">
      <organization>Swisscom</organization>

      <address>
        <postal>
          <street>Binzring 17</street>

          <city>Zurich</city>

          <code>8045</code>

          <country>Switzerland</country>
        </postal>

        <email>thomas.graf@swisscom.com</email>
      </address>
    </author>

    <author fullname="Benoit Claise" initials="B" surname="Claise">
      <organization>Huawei</organization>

      <address>
        <email>benoit.claise@huawei.com</email>
      </address>
    </author>

    <author fullname="Alex Huang Feng" initials="A." surname="Huang Feng">
      <organization>INSA-Lyon</organization>

      <address>
        <postal>
          <street/>

          <city>Lyon</city>

          <region/>

          <code/>

          <country>France</country>
        </postal>

        <phone/>

        <facsimile/>

        <email>alex.huang-feng@insa-lyon.fr</email>

        <uri/>
      </address>
    </author>

    <date day="5" month="February" year="2023"/>

    <abstract>
      <t>This document extends the YANG Notification header to support besides
      message export also network observation timestamping. In case of
      "push-change-update" notifications to describe when the network state
      change was observed. In case of "push-update" from when to when
      measurements where accounted.</t>
    </abstract>
  </front>

  <middle>
    <section anchor="Introduction" title="Introduction">
      <t>To correlate network data among different Network Telemetry planes as
      described in Section 3.1 of <xref target="RFC9232"/> or among different
      YANG push subscription types defined in Section 3.1 of <xref
      target="RFC8641"/>, network observation timestamping describing when the
      state change was observed or from when to when the data was accounted is
      essential to understand the timely relationship among these different
      planes and YANG push subscription types.</t>

      <t>With <xref target="I-D.tgraf-netconf-notif-sequencing"/> the
      delay between the YANG Notification export and the arrival at the
      downstream system storing the data can be measured. With network
      observation timestamping described in this document, the delay between
      the network observation and the data export of the YANG push publisher
      process can be measured as well, extending the delay measurement scope
      from the time the network observation and storing the data.</t>
    </section>

    <section anchor="Streaming-Update"
             title="Extend the Streaming Update Notifications">
      <!-- <t>Besides the Subscription ID as described in Section 3.7 of <xref
      target="RFC8641"/>, the following network observation time metadata
      object is part of a "push-update" or "push-change-update" notification.
      Depending on subscription type described in Section 3.1 of <xref
      target="RFC8641"/>, the semantic meaning of the populated timestamp is
      different.</t>

      <dl>
        <dt>observation-time:</dt>

        <dd>Describes in case of a "periodical" subscription when the
        accounting has started. By comparing the observation-time of two YANG
        Notifications, the time from when to when the measurements where
        accounted can be deducted. In case of a "on-change" subscription it
        describes the time when the network state change was observed after
        the subscription was initially established. In case of an "on-change
        sync on start" subscription it describes the time when the network
        state change was observed before the subscription was
        established.</dd>
      </dl> -->

      <t>Besides the Subscription ID as described in Section 3.7 of <xref
      target="RFC8641"/>, the following network observation time metadata
      objects are part of "push-update" and "push-change-update" notifications.</t>

      <dl>
        <dt>start-observation-time:</dt>

        <dd>Describes in the "push-update" notification in a "periodical"
        subscription when the accounting has started.
        By comparing the "start-observation-time" of two "push-update" notifications,
        the the collector can deduce from when to when the measurements where
        recorded.</dd>

        <dt>changed-observation-time:</dt>
        
        <dd>Describes in the "push-change-update" notification in a "on-change"
        subscription the time when the network state change was observed after
        the subscription was initially established. In case of an "on-change
        sync on start" subscription it describes the time when the network
        state change was observed before the subscription was
        established.</dd>
      </dl>

      <t><xref target="subscription_modified_example_json_fig"/> provides an
      example of a JSON encoded, <xref target="RFC8259"/>,
      "push-change-update" notification message over HTTPS-based <xref
      target="I-D.ietf-netconf-https-notif"/> or UDP-based <xref
      target="I-D.ietf-netconf-udp-notif"/> transport for the same
      subscription.</t>

      <figure anchor="subscription_modified_example_json_fig"
              title="JSON Push Example for a subscription-modified notification message">
        <artwork><![CDATA[
{
   "ietf-notification:notification": {
      "eventTime": "2023-02-04T16:30:11.22Z",
      "sysName": "example-router",
      "sequenceNumbe": 187653,
      "ietf-yang-push:push-update": {
         "id": 1011,
         "observation-time": "2023-02-04T16:30:09.44Z",
         "module": "ietf-interfaces",
         "namespace": "urn:ietf:params:xml:ns:yang:ietf-interfaces",
         "revision": "2014-05-08",
         "revision-label": "1.0.0",
         "datastore-xpath-filter": "ietf-interfaces:interfaces",
         "datastore-contents": {
            "ietf-interfaces:interface": {
               "name": {
                  "eth0": {
                     "oper-status": "up"
                  }
               }
            }
         }
      }
   }
}
        ]]></artwork>
      </figure>
    </section>

    <section anchor="YANG-push-netobs-timestamping-module"
             title="The &quot;ietf-yang-push-netobs-timestamping&quot; YANG Module">

      <t>This YANG module augments the "ietf-yang-push" module with the
      observation-time in the "push-update" and "push-change-update"
      streaming update notifications.</t>

      <section anchor="YANG-netobs-timestamping-model" title="Data Model Overview">

        <section anchor="Tree View" title="Tree View">
          <t>The following is the YANG tree diagram <xref target="RFC8340"/>
          for the ietf-yang-push-netobs-timestamping YANG module</t>

          <t><figure>
              <artwork><![CDATA[
module: ietf-yang-push-netobs-timestamping

  augment /yp:push-update:
    +--ro start-observation-time?   yang:date-and-time
  augment /yp:push-change-update:
    +--ro changed-observation-time?   yang:date-and-time
]]></artwork>
            </figure></t>
        </section>

        <section anchor="Full Tree View" title="Full Tree View">
          <t>The following is the YANG tree diagram <xref target="RFC8340"/>
          for the ietf-yang-push-netobs-timestamping augmentation within the
          ietf-subscribed-notifications, including the RPCs and
          notifications.</t>

          <t><figure>
              <artwork><![CDATA[
module: ietf-yang-push

  augment /sn:establish-subscription/sn:input:
    +---w (update-trigger)?
       +--:(periodic)
       |  +---w periodic!
       |     +---w period         centiseconds
       |     +---w anchor-time?   yang:date-and-time
       +--:(on-change) {on-change}?
          +---w on-change!
             +---w dampening-period?   centiseconds
             +---w sync-on-start?      boolean
             +---w excluded-change*    change-type
  augment /sn:establish-subscription/sn:input/sn:target:
    +--:(datastore)
       +-- datastore                               identityref
       +-- (selection-filter)?
          +--:(by-reference)
          |  +-- selection-filter-ref
          |          selection-filter-ref
          +--:(within-subscription)
             +-- (filter-spec)?
                +--:(datastore-subtree-filter)
                |  +-- datastore-subtree-filter?   <anydata>
                |          {sn:subtree}?
                +--:(datastore-xpath-filter)
                   +-- datastore-xpath-filter?     yang:xpath1.0
                           {sn:xpath}?
  augment /sn:modify-subscription/sn:input:
    +---w (update-trigger)?
       +--:(periodic)
       |  +---w periodic!
       |     +---w period         centiseconds
       |     +---w anchor-time?   yang:date-and-time
       +--:(on-change) {on-change}?
          +---w on-change!
             +---w dampening-period?   centiseconds
  augment /sn:modify-subscription/sn:input/sn:target:
    +--:(datastore)
       +-- datastore                               identityref
       +-- (selection-filter)?
          +--:(by-reference)
          |  +-- selection-filter-ref
          |          selection-filter-ref
          +--:(within-subscription)
             +-- (filter-spec)?
                +--:(datastore-subtree-filter)
                |  +-- datastore-subtree-filter?   <anydata>
                |          {sn:subtree}?
                +--:(datastore-xpath-filter)
                   +-- datastore-xpath-filter?     yang:xpath1.0
                           {sn:xpath}?
  augment /sn:subscription-started:
    +--ro (update-trigger)?
       +--:(periodic)
       |  +--ro periodic!
       |     +--ro period         centiseconds
       |     +--ro anchor-time?   yang:date-and-time
       +--:(on-change) {on-change}?
          +--ro on-change!
             +--ro dampening-period?   centiseconds
             +--ro sync-on-start?      boolean
             +--ro excluded-change*    change-type
  augment /sn:subscription-started/sn:target:
    +--:(datastore)
       +-- datastore                               identityref
       +-- (selection-filter)?
          +--:(by-reference)
          |  +-- selection-filter-ref
          |          selection-filter-ref
          +--:(within-subscription)
             +-- (filter-spec)?
                +--:(datastore-subtree-filter)
                |  +-- datastore-subtree-filter?   <anydata>
                |          {sn:subtree}?
                +--:(datastore-xpath-filter)
                   +-- datastore-xpath-filter?     yang:xpath1.0
                           {sn:xpath}?
  augment /sn:subscription-modified:
    +--ro (update-trigger)?
       +--:(periodic)
       |  +--ro periodic!
       |     +--ro period         centiseconds
       |     +--ro anchor-time?   yang:date-and-time
       +--:(on-change) {on-change}?
          +--ro on-change!
             +--ro dampening-period?   centiseconds
             +--ro sync-on-start?      boolean
             +--ro excluded-change*    change-type
  augment /sn:subscription-modified/sn:target:
    +--:(datastore)
       +-- datastore                               identityref
       +-- (selection-filter)?
          +--:(by-reference)
          |  +-- selection-filter-ref
          |          selection-filter-ref
          +--:(within-subscription)
             +-- (filter-spec)?
                +--:(datastore-subtree-filter)
                |  +-- datastore-subtree-filter?   <anydata>
                |          {sn:subtree}?
                +--:(datastore-xpath-filter)
                   +-- datastore-xpath-filter?     yang:xpath1.0
                           {sn:xpath}?
  augment /sn:filters:
    +--rw selection-filter* [filter-id]
       +--rw filter-id                         string
       +--rw (filter-spec)?
          +--:(datastore-subtree-filter)
          |  +--rw datastore-subtree-filter?   <anydata>
          |          {sn:subtree}?
          +--:(datastore-xpath-filter)
             +--rw datastore-xpath-filter?     yang:xpath1.0
                     {sn:xpath}?
  augment /sn:subscriptions/sn:subscription:
    +--rw (update-trigger)?
       +--:(periodic)
       |  +--rw periodic!
       |     +--rw period         centiseconds
       |     +--rw anchor-time?   yang:date-and-time
       +--:(on-change) {on-change}?
          +--rw on-change!
             +--rw dampening-period?   centiseconds
             +--rw sync-on-start?      boolean
             +--rw excluded-change*    change-type
  augment /sn:subscriptions/sn:subscription/sn:target:
    +--:(datastore)
       +--rw datastore                               identityref
       +--rw (selection-filter)?
          +--:(by-reference)
          |  +--rw selection-filter-ref
          |          selection-filter-ref
          +--:(within-subscription)
             +--rw (filter-spec)?
                +--:(datastore-subtree-filter)
                |  +--rw datastore-subtree-filter?   <anydata>
                |          {sn:subtree}?
                +--:(datastore-xpath-filter)
                   +--rw datastore-xpath-filter?
                           yang:xpath1.0 {sn:xpath}?

  rpcs:
    +---x resync-subscription {on-change}?
       +---w input
          +---w id    sn:subscription-id

  notifications:
    +---n push-update
    |  +--ro id?                            sn:subscription-id
    |  +--ro datastore-contents?            <anydata>
    |  +--ro incomplete-update?             empty
    |  +--ro ypnt:start-observation-time?   yang:date-and-time
    +---n push-change-update {on-change}?
       +--ro id?                              sn:subscription-id
       +--ro datastore-changes
       |  +--ro yang-patch
       |     +--ro patch-id    string
       |     +--ro comment?    string
       |     +--ro edit* [edit-id]
       |        +--ro edit-id      string
       |        +--ro operation    enumeration
       |        +--ro target       target-resource-offset
       |        +--ro point?       target-resource-offset
       |        +--ro where?       enumeration
       |        +--ro value?       <anydata>
       +--ro incomplete-update?               empty
       +--ro ypnt:changed-observation-time?   yang:date-and-time

]]></artwork>
            </figure></t>
        </section>
      </section>

      <section anchor="YANG-netobs-timestamping-module" title="YANG Module">
        <t>The YANG module has one leave augmenting the model of <xref
        target="RFC8639">Subscription to YANG Notifications</xref>.</t>

        <t><figure>
            <artwork><![CDATA[
<CODE BEGINS> file "ietf-yang-push-netobs-timestamping@2023-02-14.yang"
module ietf-yang-push-netobs-timestamping {
  yang-version 1.1;
  namespace
    "urn:ietf:params:xml:ns:yang:ietf-yang-push-netobs-timestamping";
  prefix ypnt;
  import ietf-yang-types {
    prefix yang;
    reference
      "RFC 6991: Common YANG Data Types";
  }
  import ietf-yang-push {
    prefix yp;
    reference
      "RFC 8641: Subscription to YANG Notifications for Datastore Updates";
  }
  organization "IETF NETCONF (Network Configuration) Working Group";
  contact
    "WG Web:   <http:/tools.ietf.org/wg/netconf/>
     WG List:  <mailto:netconf@ietf.org>

     Authors:  Thomas Graf
               <mailto:thomas.graf@swisscom.com>
               Benoit Claise
               <mailto:benoit.claise@huawei.com>
               Alex Huang Feng
               <mailto:alex.huang-feng@insa-lyon.fr>";

  description
    "Defines YANG push event notification header with the observation
    time in push-update and push-change-update notifications.

    Copyright (c) 2023 IETF Trust and the persons identified as
    authors of the code.  All rights reserved.

    Redistribution and use in source and binary forms, with or without
    modification, is permitted pursuant to, and subject to the license
    terms contained in, the Revised BSD License set forth in Section
    4.c of the IETF Trust's Legal Provisions Relating to IETF Documents
    (https://trustee.ietf.org/license-info).

    This version of this YANG module is part of RFC XXXX; see the RFC
    itself for full legal notices.";

  revision 2023-02-14 {
    description
      "First revision";
    reference
      "RFC XXXX: Support of YANG Notifications Observation Time";
  }

  feature yang-push-change-update-obs-timestamp {
    description
      "This feature indicates the YANG-push Notifications support
      the observation timestamps in the push-change-update notifications.";
  }

  feature yang-push-update-obs-timestamp {
    description
      "This feature indicates the YANG-push Notifications support
      the observation timestamps in the push-update notifications.";
  }

  grouping yang-push-update-obs-timestamp {
    description
      "This grouping adds the start timestamp and the end timestamp of the
      observed metrics.";
    leaf start-observation-time {
      type yang:date-and-time;
      description
        "This is the time when metrics started counting.";
    }
  }

  grouping yang-push-change-update-obs-timestamp {
    description
      "This grouping adds the timestamp of the recorded event.";
    leaf changed-observation-time {
      type yang:date-and-time;
      description
        "This is the time when event happened.";
    }
  }

  // Event notifications
  augment "/yp:push-update" {
    description
      "This augmentation adds the start timestamp of the counted metrics
      in the push-update notification.";
    uses ypnt:yang-push-update-obs-timestamp;
  }

  augment "/yp:push-change-update" {
    description
      "This augmentation adds the timestamp of the event in the push-change-update
      notification.";
      uses ypnt:yang-push-change-update-obs-timestamp;
  }
}
<CODE ENDS>]]></artwork>
          </figure></t>
      </section>
    </section>

    <section anchor="Security" title="Security Considerations">
      <t>The security considerations for the YANG notifications subscription
      mechanism are described in <xref target="RFC8641"/>. This document adds
      no additional security considerations.</t>
    </section>

    <section anchor="IANA_Considerations" title="IANA Considerations">
      <t>TBD: ask the YANG Module name to IANA</t>
      <t>TBD: ask a new XML namespace for the xml Schema</t>
      <!-- <t>This document has no IANA actions.</t> -->
    </section>

    <section anchor="Acknowledgements" title="Acknowledgements">
      <t>The authors would like to thank xxx for their review and valuable
      comments.</t>
    </section>
  </middle>

  <back>
    <references title="Normative References">
       

      <?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.8639.xml'?>
      <?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.8641.xml'?>
      <!-- <?rfc include='http://xml.resource.org/public/rfc/bibxml-ids/reference.I-D.tgraf-netconf-notif-sequencing.xml'?> -->

      <reference anchor="I-D.tgraf-netconf-notif-sequencing" target="">
        <front>
          <title>Support of Hostname and Sequencing in YANG Notifications</title>


          <author fullname="Thomas Graf" initials="T." surname="Graf">
            <organization>Swisscom</organization>
          </author>
          <author fullname="Jean Quilbeuf" initials="J." surname="Quilbeuf">
            <organization>Huawei</organization>
          </author>
          <author fullname="Alex Huang Feng" initials="A." surname="Huang Feng">
            <organization>INSA-Lyon</organization>
          </author>

          <date month="February" year="2023"/>
        </front>

        <seriesInfo name="Internet-Draft"
                    value="draft-tgraf-netconf-notif-sequencing-00"/>
      </reference>

    </references>

    <references title="Informative References">
      <?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.8259.xml'?>
      <?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.8340.xml'?>
      <?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.9232.xml'?>
      <?rfc include='http://xml.resource.org/public/rfc/bibxml-ids/reference.I-D.ietf-netconf-https-notif.xml'?>
      <?rfc include='http://xml.resource.org/public/rfc/bibxml-ids/reference.I-D.ietf-netconf-udp-notif.xml'?>
    </references>
  </back>
</rfc>