NMOP                                                        A. Elhassany
Internet-Draft                                                   T. Graf
Intended status: Informational                                  Swisscom
Expires: 2 September 2025                                   1 March 2025


       Extensible YANG Model for Network Telemetry Notifications
         draft-netana-nmop-message-broker-telemetry-message-00

Abstract

   This document defines an extensible message schema in YANG to be used
   at the data collection for transforming Network Telemetry
   notifications into external systems such as message brokers.  The
   extensible message schema enables a data collection to add metadata
   for the provenance of the operational network data.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at https://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on 2 September 2025.

Copyright Notice

   Copyright (c) 2025 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents (https://trustee.ietf.org/
   license-info) in effect on the date of publication of this document.
   Please review these documents carefully, as they describe your rights
   and restrictions with respect to this document.  Code Components
   extracted from this document must include Revised BSD License text as
   described in Section 4.e of the Trust Legal Provisions and are
   provided without warranty as described in the Revised BSD License.




Elhassany & Graf        Expires 2 September 2025                [Page 1]

Internet-Draft              Telmetery Message                 March 2025


Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
     1.1.  Requirements Language . . . . . . . . . . . . . . . . . .   3
   2.  YANG Module . . . . . . . . . . . . . . . . . . . . . . . . .   4
   3.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  13
   4.  Security Considerations . . . . . . . . . . . . . . . . . . .  13
   5.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  13
     5.1.  Normative References  . . . . . . . . . . . . . . . . . .  13
     5.2.  Informative References  . . . . . . . . . . . . . . . . .  14
   Acknowledgements  . . . . . . . . . . . . . . . . . . . . . . . .  14
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  14

1.  Introduction

   Nowadays network operators are using machine and human readable YANG
   [RFC7950] to model their configurations and obtain YANG modelled
   operational data from their networks.

   Network operators organize their data in a Data Mesh [Deh22] where a
   message broker such as Apache Kafka [Kaf11] or RabbitMQ [Rab07]
   facilitates the exchange of messages among data processing
   components.

   Today, subscribing to a YANG datastore, publishing a YANG modeled
   notifications message from the network and viewing the data in a time
   series database, manual labor is needed to perform data
   transformation to make a message broker and its data processing
   components with YANG notifications interoperable.

   Even though YANG is intented to ease data management, this promise
   has not yet been fulfilled for Network Telemetry [RFC9232].

   An Architecture for YANG-Push to Message Broker Integration
   [I-D.ietf-nmop-yang-message-broker-integration] defined an
   architecture for integrating YANG-Push with message brokers for a
   Data Mesh architecture.  How the notification messages at a YANG-Push
   receiver is being transformed to the message broker is being
   described in Section Section 4.5 of
   [I-D.ietf-nmop-yang-message-broker-integration], however the produced
   message format left unspecified.










Elhassany & Graf        Expires 2 September 2025                [Page 2]

Internet-Draft              Telmetery Message                 March 2025


   The message could be published as it was received from the network to
   their organization's message broker.  However, this approach is
   insufficient for correct human and automated understanding of the
   data generated by the network.  This insufficiency stems from not
   presenting a holistic picture along with the data generated by the
   network.  In particular, when a data consumer in the data mesh
   consumes a YANG message from their organization's message broker,
   they cannot answer simple questions such as:

   *  Which network operating system collected the data?

   *  To which network platform belongs the network node?

   *  What is the subscribed xpath, sub-tree filter and its schema
      reference?

   *  When did the data collection received the data?

   *  What additional metadata is necessary for a consumer to make sense
      of the data?

   This document defines a standard YANG envelope message to carry with
   the collected Network Telemetry notifications the provenance and
   metadata information for a YANG data exchanged in message brokers for
   a Data Mesh architecture.

1.1.  Requirements Language

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
   "OPTIONAL" in this document are to be interpreted as described in BCP
   14 [RFC2119] [RFC8174] when, and only when, they appear in all
   capitals, as shown here.

   The terms "subscriber", "publisher", and "receiver" are used as
   defined in [RFC8639].

   In addition, this document reuses the terms defined in
   [I-D.netana-netconf-notif-envelope] for the use in message broker
   enviroment:

   Notification Metadata: Additional data describing the context of a
   notification that is sent in each message, e.g. which node generated
   the messsage or at which time the notification was published.

   Notification Envelope: YANG structure encapsulating the payload of a
   notification, allowing the inclusion of metadata.




Elhassany & Graf        Expires 2 September 2025                [Page 3]

Internet-Draft              Telmetery Message                 March 2025


2.  YANG Module

   The extensible YANG module for Network Telemetry notifications
   defines an envelope message schema which adds four metadata
   categories to the collected Network Telemetry notifications.

   Network Node Provenance:  Is the provenance information about the
      network node that published YANG notifications to the receiver.
      This category adds metadata such as the node name, address, and
      software version to the message.

   Data Collection Provenance:  Is the provenance information about the
      data collection.  The data type is the same as the first category
      but specific to the collector node.

   Data Collection Protocol Provenance:  Is the session information
      about the session between the collector and the network node.
      This category adds fields such as the session protocol and the
      time the event was generated in the network node.  Moreover, this
      document defines an extension specific to YANG-Push that includes
      YANG-Push subscription information.

   Network Operator Provenance:  Is the operator specific metadata.
      Some operators enrich the collected data with specific
      information.  For instance: type of the network node (MPLS
      provider or provider edge node) or which operational unit the node
      is operated by.  For this purpose the document defines a generic
      metadata map with key/values that can be used freely by the
      network operator.






















Elhassany & Graf        Expires 2 September 2025                [Page 4]

Internet-Draft              Telmetery Message                 March 2025


   module: ietf-telemetry-message
     +--ro message
        +--ro timestamp           yang:date-and-time
        +--ro session-protocol    telemetry-session-protocol-type
        +--ro node
        |  +--ro address             inet:host
        |  +--ro port                inet:port-number
        |  +--ro platform-name?      string
        |  +--ro vendor?             string
        |  +--ro vendor-pen?         uint32
        |  +--ro software-version?   string
        |  +--ro software-flavor?    string
        |  +--ro os-version?         string
        |  +--ro os-type?            string
        +--ro collector
        |  +--ro address             inet:host
        |  +--ro port                inet:port-number
        |  +--ro platform-name?      string
        |  +--ro vendor?             string
        |  +--ro vendor-pen?         uint32
        |  +--ro software-version?   string
        |  +--ro software-flavor?    string
        |  +--ro os-version?         string
        |  +--ro os-type?            string
        +--ro session-metadata
        |  +--ro event-time    yang:date-and-time
        +--ro metadata
        |  +--ro labels* [name]
        |     +--ro name       string
        |     +--ro (value)
        |        +--:(string-value)
        |        |  +--ro (string-value)?
        |        |     +--:(string-value)
        |        |        +--ro string-value?   string
        |        +--:(anydata-value)
        |           +--ro (anydata-value)?
        |              +--:(anydata-value)
        |                 +--ro anydata-value?   anydata
        +--ro payload?            anydata

                   Figure 1: ietf-telemetry-message tree










Elhassany & Graf        Expires 2 September 2025                [Page 5]

Internet-Draft              Telmetery Message                 March 2025


   module: ietf-yang-push-telemetry-message

     augment /tm:message/tm:session-metadata:
       +--ro yang-push-subscription
          +--ro id                                   sn:subscription-id
          +--ro filters
          |  +--ro stream-filter* [name]
          |     +--ro name                         string
          |     +---u sn:stream-filter-elements
          +---u ypr:yang-push-module-version-list


              Figure 2: ietf-yang-push-telemetry-message tree

   <CODE BEGINS> file "ietf-yang-push-telemetry-message@2024-02-20.yang"
   module ietf-telemetry-message {
     yang-version 1.1;
     namespace "urn:ietf:params:xml:ns:yang:telemetry-message";
     prefix tm;

     import ietf-yang-types {
       prefix yang;
     }
     import ietf-inet-types {
       prefix inet;
     }
     import ietf-subscribed-notifications {
       prefix sn;
       reference
         "RFC 8639: Subscription to YANG Notifications";
     }

     organization
       "IETF Draft";
     contact
       "Author:    Ahmed Elhassany
                   &lt;mailto:ahmed.elhassany@swisscom.com&gt;";
     description
       "This YANG modules defines a model for a telemetry collector to send
        collected YANG data from the network.

        Copyright (c) 2024 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



Elhassany & Graf        Expires 2 September 2025                [Page 6]

Internet-Draft              Telmetery Message                 March 2025


        (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 2024-02-20 {
       description
         "Initial revision.";
       reference
         "RFC XXXX";
     }

     typedef telemetry-message-event-type {
       type enumeration {
         enum "log" {
           description
             "Collector is reporting the event as it arrived from
               the network element";
         }
         enum "update" {
           description
             "Collector has updated an entry inside its local cache.
               This could be triggered by an event from the network for
               instance interface operational status changed or an internal
               event in the collector, such as a timer triggered to referesh
               old enteries";
         }
         enum "delete" {
           description
             "Collector has deleted an entry from its local cache";
         }
       }
       description
         "Type of event reported by the collector";
     }

     typedef telemetry-session-protocol-type {
       type enumeration {
         enum "netconf" {
           description
             "NETCONF RFC8640";
         }
         enum "restconf" {
           description
             "RESTCONF RFC8650";
         }
         enum "https" {
           description



Elhassany & Graf        Expires 2 September 2025                [Page 7]

Internet-Draft              Telmetery Message                 March 2025


             "HTTPS draft-ietf-netconf-https-notif";
         }
         enum "udp-notif" {
           description
             "UDP draft-ietf-netconf-udp-notif";
         }
       }
       description
         "Session protocol used to deliver the messaget to the collector";
     }

     grouping node-information {
       description
         "Idenitfy a network node by its hostname/IP Address and port number.";
       leaf address {
         type inet:host;
         mandatory true;
         description
           "Node address";
       }
       leaf port {
         type inet:port-number;
         mandatory true;
         description
           "Node port number";
       }
       leaf platform-name {
         type string;
         description
           "Model of the platform from which data is collected.";
       }
       leaf vendor {
         type string;
         description
           "Organization that implements that platform.";
       }
       leaf vendor-pen {
         type uint32;
         description
           "Vendor''s registered Private Enterprise Number as
            described in RFC9371";
       }
       leaf software-version {
         type string;
         description
           "Name of the version of software. With respect to most network
             device appliances, this will be the operating system version.
             But for other YANG module implementation, this would be a



Elhassany & Graf        Expires 2 September 2025                [Page 8]

Internet-Draft              Telmetery Message                 March 2025


             version of appliance software. Ultimately, this should
             correspond to a version string that will be recognizable by
             the consumers of the platform.";
       }
       leaf software-flavor {
         type string;
         description
           "A variation of a specific version where YANG model support
             may be different.  Depending on the vendor, this could be a
             license, additional software component, or a feature set.";
       }
       leaf os-version {
         type string;
         description
           "Version of the operating system using this module. This is
             primarily useful if the software implementing the module is
             an application that requires a specific operating system
             version.";
       }
       leaf os-type {
         type string;
         description
           "Type of the operating system using this module. This is
             primarily useful if the software implementing the module is
             an application that requires a specific operating system
             type.";
       }
     }

     container message {
       config false;
       leaf timestamp {
         type yang:date-and-time;
         mandatory true;
         description
           "Timestamp when the collector received the message from the network
             element or an update or delete event is triggered";
       }
       leaf session-protocol {
         type telemetry-session-protocol-type;
         mandatory true;
         description
           "Protocol used to send the message from network node to
             the collector";
       }
       container node {
         description
           "Address of network element sent the message";



Elhassany & Graf        Expires 2 September 2025                [Page 9]

Internet-Draft              Telmetery Message                 March 2025


         uses node-information;
       }
       container collector {
         description
           "Address of the telemetry collector";
         uses node-information;
       }
       container session-metadata {
         leaf event-time {
           type yang:date-and-time;
           mandatory true;
           description
             "NETCONF eventTime. Redefined in here since NETCONF header is XML
               not YANG";
         }
       }
       container metadata {
         description
           "Collector added metadata.";
         list labels {
           key "name";
           description
             "arbiterary labels assinged by the collector";
           leaf name {
             type string {
               length "1..max";
             }
             description
               "label name";
           }
           choice value {
             mandatory true;
             choice string-value {
               leaf string-value {
                 type string;
               }
             }
             choice anydata-value {
               anydata anydata-value {
                 description
                   "anydata yang";
               }
             }
           }
         }
       }
       anydata payload {
         description



Elhassany & Graf        Expires 2 September 2025               [Page 10]

Internet-Draft              Telmetery Message                 March 2025


           "message received from network element";
       }
     }
   }

           </sourcecode>
         </figure>

       <figure>
     <name>Telemetry message YANG Module</name>
     <sourcecode
       markers="true"
       name="ietf-yang-push-telemetry-message@2024-02-20.yang"
       type="yang">
   module ietf-yang-push-telemetry-message {
     yang-version 1.1;
     namespace "urn:ietf:params:xml:ns:yang:yang-push-telemetry-message";
     prefix yptm;

     import ietf-subscribed-notifications {
       prefix sn;
       reference
         "RFC 8639: Subscription to YANG Notifications";
     }
     import ietf-telemetry-message {
       prefix tm;
       reference
         "XXX";
     }
     import ietf-yang-push-revision {
       prefix ypr;
       reference
         "XXX";
     }

     organization
       "IETF Draft";
     contact
       "Author:    Ahmed Elhassany
                   &lt;mailto:ahmed.elhassany@swisscom.com&gt;";
     description
       "Augments the ietf-telemetry-message with YANG Push specific
        fields.

        Copyright (c) 2024 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



Elhassany & Graf        Expires 2 September 2025               [Page 11]

Internet-Draft              Telmetery Message                 March 2025


        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 2024-02-20 {
       description
         "Initial revision.";
       reference
         "RFC XXXX";
     }

     augment "/tm:message/tm:session-metadata" {
       container yang-push-subscription {
         config false;
         leaf id {
           type sn:subscription-id;
           mandatory true;
           description
             "This references the affected subscription.";
         }
         container filters {
           description
             "Contains a list of configurable filters that can be applied to
               subscriptions.  This facilitates the reuse of complex filters
               once defined.";
           list stream-filter {
             key "name";
             description
               "A list of preconfigured filters that can be applied to
                 subscriptions.";
             leaf name {
               type string;
               description
                 "A name to differentiate between filters.";
             }
             uses sn:stream-filter-elements;
           }
         }
         uses ypr:yang-push-module-version-list;
       }
     }
   }
   <CODE ENDS>




Elhassany & Graf        Expires 2 September 2025               [Page 12]

Internet-Draft              Telmetery Message                 March 2025


                  Figure 3: Telemetry message YANG Module

3.  IANA Considerations

   TODO

4.  Security Considerations

   TODO

5.  References

5.1.  Normative References

   [RFC7950]  Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
              RFC 7950, DOI 10.17487/RFC7950, August 2016,
              <https://www.rfc-editor.org/info/rfc7950>.

   [RFC8639]  Voit, E., Clemm, A., Gonzalez Prieto, A., Nilsen-Nygaard,
              E., and A. Tripathy, "Subscription to YANG Notifications",
              RFC 8639, DOI 10.17487/RFC8639, September 2019,
              <https://www.rfc-editor.org/info/rfc8639>.

   [RFC9232]  Song, H., Qin, F., Martinez-Julia, P., Ciavaglia, L., and
              A. Wang, "Network Telemetry Framework", RFC 9232,
              DOI 10.17487/RFC9232, May 2022,
              <https://www.rfc-editor.org/info/rfc9232>.

   [I-D.ietf-nmop-yang-message-broker-integration]
              Graf, T. and A. Elhassany, "An Architecture for YANG-Push
              to Message Broker Integration", Work in Progress,
              Internet-Draft, draft-ietf-nmop-yang-message-broker-
              integration-06, 5 February 2025,
              <https://datatracker.ietf.org/doc/html/draft-ietf-nmop-
              yang-message-broker-integration-06>.

   [I-D.netana-netconf-notif-envelope]
              Feng, A. H., Francois, P., Graf, T., and B. Claise,
              "Extensible YANG Model for YANG-Push Notifications", Work
              in Progress, Internet-Draft, draft-netana-netconf-notif-
              envelope-02, 28 January 2025,
              <https://datatracker.ietf.org/doc/html/draft-netana-
              netconf-notif-envelope-02>.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
              May 2017, <https://www.rfc-editor.org/info/rfc8174>.




Elhassany & Graf        Expires 2 September 2025               [Page 13]

Internet-Draft              Telmetery Message                 March 2025


   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/info/rfc2119>.

5.2.  Informative References

   [Deh22]    Dehghani, Z., "Data Mesh", O'Reilly Media,
              ISBN 9781492092391, March 2022,
              <https://www.oreilly.com/library/view/data-
              mesh/9781492092384/>.

   [Rab07]    VMware, "RabbitMQ", Mozilla Public License, February 2007,
              <https://rabbitmq.com/>.

   [Kaf11]    Narkhede, N., "Apache Kafka", Apache Software Foundation,
              January 2011, <https://kafka.apache.org/>.

Acknowledgements

   TODO

Authors' Addresses

   Ahmed Elhassany
   Swisscom
   Binzring 17
   CH- Zuerich 8045
   Switzerland
   Email: ahmed.elhassany@swisscom.com


   Thomas Graf
   Swisscom
   Binzring 17
   CH- Zuerich 8045
   Switzerland
   Email: thomas.graf@swisscom.com













Elhassany & Graf        Expires 2 September 2025               [Page 14]