idnits 2.17.1 draft-tao-netmod-yang-node-tags-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 42 instances of too long lines in the document, the longest one being 15 characters in excess of 72. ** The abstract seems to contain references ([RFC7950]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 215 has weird spacing: '...latency tunne...' == Line 217 has weird spacing: '...et-loss tunne...' == Line 219 has weird spacing: '...latency tunne...' == Line 221 has weird spacing: '...latency tunne...' == Line 223 has weird spacing: '...-packet tun...' == (6 more instances...) -- The document date (July 8, 2020) is 1359 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'I-D.netconf-notification-capabilities' is mentioned on line 143, but not defined Summary: 2 errors (**), 0 flaws (~~), 8 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETMOD Working Group Q. Wu 3 Internet-Draft Huawei 4 Intended status: Standards Track B. Claise 5 Expires: January 9, 2021 Cisco 6 L. Geng 7 Z. Du 8 China Mobile 9 July 8, 2020 11 Telemetry Data Self Explanation Tags 12 draft-tao-netmod-yang-node-tags-03 14 Abstract 16 This document defines a method to tag data node associated with 17 telemetry data in YANG Modules. This YANG data node tagging method 18 can be used to provide input, instruction, indication to selection 19 filter and filter queries of operational state on a server during a 20 "pub/sub" service for YANG datastore updates and provide multiple 21 dimensional network visibility analysis when the state of all 22 subscriptions of a particular Subscriber to be fetched is huge, so 23 that the amount of data to be streamed out to the destination can be 24 greatly reduced and only targeted to the characteristics data. 26 An extension statement to be used to indicate YANG data node self 27 explanation tags that SHOULD be added by the module implementation 28 automatically (i.e., outside of configuration). 30 A YANG module [RFC7950] is defined, which augments Module tag model 31 and provides a list of data node entries to allow for adding or 32 removing of data node self explanation tags as well as viewing the 33 set of self explanation tags associated with a YANG module. 35 Status of This Memo 37 This Internet-Draft is submitted in full conformance with the 38 provisions of BCP 78 and BCP 79. 40 Internet-Drafts are working documents of the Internet Engineering 41 Task Force (IETF). Note that other groups may also distribute 42 working documents as Internet-Drafts. The list of current Internet- 43 Drafts is at https://datatracker.ietf.org/drafts/current/. 45 Internet-Drafts are draft documents valid for a maximum of six months 46 and may be updated, replaced, or obsoleted by other documents at any 47 time. It is inappropriate to use Internet-Drafts as reference 48 material or to cite them other than as "work in progress." 49 This Internet-Draft will expire on January 9, 2021. 51 Copyright Notice 53 Copyright (c) 2020 IETF Trust and the persons identified as the 54 document authors. All rights reserved. 56 This document is subject to BCP 78 and the IETF Trust's Legal 57 Provisions Relating to IETF Documents 58 (https://trustee.ietf.org/license-info) in effect on the date of 59 publication of this document. Please review these documents 60 carefully, as they describe your rights and restrictions with respect 61 to this document. Code Components extracted from this document must 62 include Simplified BSD License text as described in Section 4.e of 63 the Trust Legal Provisions and are provided without warranty as 64 described in the Simplified BSD License. 66 Table of Contents 68 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 69 1.1. Data Node tags Use Cases . . . . . . . . . . . . . . . . 4 70 1.1.1. Multiple Dimensional Performance Measurement 71 Information Tagging . . . . . . . . . . . . . . . . . 4 72 1.1.2. Correlated Information Tagging . . . . . . . . . . . 7 73 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 8 74 2. Data Node Tag Values . . . . . . . . . . . . . . . . . . . . 8 75 2.1. IETF Tags Prefix . . . . . . . . . . . . . . . . . . . . 8 76 2.2. Vendor Tags Prefix . . . . . . . . . . . . . . . . . . . 8 77 2.3. User Tags Prefix . . . . . . . . . . . . . . . . . . . . 8 78 2.4. Reserved Tags Prefix . . . . . . . . . . . . . . . . . . 8 79 3. Data Node Tag Management . . . . . . . . . . . . . . . . . . 9 80 3.1. Module Design Tagging . . . . . . . . . . . . . . . . . . 9 81 3.2. Implementation Tagging . . . . . . . . . . . . . . . . . 9 82 3.3. User Tagging . . . . . . . . . . . . . . . . . . . . . . 9 83 4. Tags Module Structure . . . . . . . . . . . . . . . . . . . . 9 84 4.1. Tags Module Tree . . . . . . . . . . . . . . . . . . . . 9 85 5. YANG Module . . . . . . . . . . . . . . . . . . . . . . . . . 10 86 6. Guidelines to Model Writers . . . . . . . . . . . . . . . . . 18 87 6.1. Define Standard Tags . . . . . . . . . . . . . . . . . . 18 88 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 89 7.1. YANG Data Node Tag Prefixes Registry . . . . . . . . . . 19 90 7.2. IETF YANG Data Node Tags Registry . . . . . . . . . . . . 20 91 7.3. Updates to the IETF XML Registry . . . . . . . . . . . . 25 92 7.4. Updates to the YANG Module Names Registry . . . . . . . . 25 93 8. Security Considerations . . . . . . . . . . . . . . . . . . . 25 94 9. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 26 95 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 26 96 10.1. Normative References . . . . . . . . . . . . . . . . . . 26 97 10.2. Informative References . . . . . . . . . . . . . . . . . 26 98 Appendix A. Targeted data object subscription example . . . . . 27 99 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 29 101 1. Introduction 103 As described [I.D-ietf-netmod-module-tags], the use of tags for 104 classification and organization is fairly ubiquitous not only within 105 IETF protocols, but in the internet itself (e.g., "#hashtags"). A 106 module tag defined in [I.D-ietf-netmod-module-tags] is a string 107 associated only with a module name at module level. 109 At the time of writing this document (2020), there are many data 110 models that have been specified or are being specified by various 111 different SDOs and Open Souce community. They cover many of the 112 networking protocols and techniques. However data objects defined by 113 these technology specific data models might represent a portion of 114 fault, configuration, accounting, performance, security management 115 categories information (e.g., performance metric specific data object 116 type) in various different ways, lack consistent classification 117 criteria and representation granularity,e.g., sensor data in hardware 118 model is defined with fine granularity with value scale and value 119 precision while interface model only provides statistics data for 120 specific interface type. 122 This document defines data node self explanation tags and associates 123 them with data nodes within YANG module, which 125 o Provide dictionary meaning for specific targeted data nodes; 127 o Indicate relationship between data nodes within the same YANG 128 module or from different YANG modules; 130 o Identify key performance metric scale, precision, statistics 131 operation; 133 o Identify specific service or feature, data source. 135 The data node self explanation tags can be used by the client to 136 provide input, instruction, indication to selection filter and filter 137 queries of configuration or operational state on a server based on 138 these data node tags,.e.g.,return specific object type of operational 139 state related to system-management. NETCONF clients can discover 140 data objects with data node self explanation tags supported by a 141 NETCONF server via operation. The data node self 142 explanation tag capability can also be advertised via capability 143 notification Model [I-D.netconf-notification-capabilities] by the 144 NETCONF server or some place where offline document are kept. These 145 self explanation tags may be registered as well as assigned during 146 the module definition; assigned by implementations; or dynamically 147 defined and set by users. 149 This document defines a YANG module [RFC7950] which augments module 150 tag model and provides a list of data node entries to allow for 151 adding or removing of self explanation tags as well as viewing the 152 set of self explanation tags associated with a data node within YANG 153 modules. 155 This document defines an extension statement to be used to indicate 156 self explanation tags that SHOULD be added by the module 157 implementation automatically (i.e., outside of configuration). 159 The YANG data model in this document conforms to the Network 160 Management Datastore Architecture defined in [RFC8342]. 162 1.1. Data Node tags Use Cases 164 The following is a list of already implemented and potential use 165 cases. 167 1.1.1. Multiple Dimensional Performance Measurement Information Tagging 169 Data node tags can be used to express multiple dimensional 170 performance metric and properties associated with YANG data nodes or 171 data objects modelled with YANG (See Figure 1). 173 ----- ----- 174 // \\ // \\ 175 | Property+------+ +-------+ Property| 176 \\ A // | | \\ B // 177 -----+ +--V----------------V---+ ----- 178 | YANG Data Node | 179 | /Data Object | 180 /---\ +--^----------------^---+ /---\ 181 / \ | | / \ 182 |Metric +-------+ +--------|Metric | 183 \ A / +-------------+ \ B / 184 \-+-/ | | \-+-/ 185 | | Metric Group| | 186 -------------| |--------------- 187 +-------------+ 189 Figure 1 191 The use of data node tags would be to help filter different discrete 192 categories of YANG data nodes across YANG modules supported by a 193 device. If data nodes across YANG modules are suitably tagged and 194 learnt by the client from a live server, then an XPath query can be 195 used by the client to list all related data nodes supported by a 196 device with the same characteristics. Data node tags can also be 197 used to help coordination when clients are interacting with various 198 different devices with the same categories of YANG data node across 199 different YANG modules. For example, one management client could 200 mark some specific data node across modules implemented in various 201 different devices with the same metric group tag, so consistent 202 representation and reporting can be provided for YANG data nodes 203 belonging to the same metric group (see Figure 2). 205 +-----------+---------------+-----------+-----------------------+ 206 | Object | Property | Metric | Metric Module | 207 | Name | Name | Group | Name | 208 | | | | | 209 |tunnel-svc | name | - | - tunnel | 210 | | | | | 211 |tunnel-svc | create-time | - | - tunnel | 212 | | | | | 213 |tunnel-svc | modified-time | - | - | 214 | | | | | 215 |tunnel-svc | - |lsp-ping-pm| avg-latency tunnel-pm| 216 | | | | | 217 |tunnel-svc | - |lsp-ping-pm| packet-loss tunnel-pm| 218 | | | | | 219 |tunnel-svc | - |lsp-ping-pm| min-latency tunnel-pm| 220 | | | | | 221 |tunnel-svc | - |lsp-ping-pm| max-latency tunnel-pm| 222 | | | |transmitted | 223 |tunnel-svc | - |lsp-ping-pm| -packet tunnel-pm| 224 +-----------+---------------+-----------+-----------------------+ 226 +---------------------------------------------------------+ 227 | Metric Metric Metric Metric Metric | 228 | Group Name Precision Scale Unit | 229 | | 230 | lsp-ping-pm avg- 1 1 ms | 231 | latency | 232 | | 233 | lsp-ping-pm packet- 1 1 percentile | 234 | loss | 235 | | 236 | | 237 | lsp-ping-pm min- 1 1 ms | 238 | latency | 239 | | 240 | | 241 | lsp-ping-pm max- 1 1 ms | 242 | latency | 243 | | 244 | | 245 | lsp-ping-pm transmitted 1 1 | 246 +---------------------------------------------------------+ 248 Figure 2 250 1.1.2. Correlated Information Tagging 252 Another example is the management client could mark some data node 253 across different level of YANG modules implemented in the device, the 254 management system with the same service tag (e.g., L3VPN Service), so 255 root cause can be identified efficiently during service-level 256 agreements and performance monitoring or network failure 257 troubleshooting. 259 +--------------+ 260 | Parent object| 261 +-------^------+ 262 | 263 ----- +-----+-----+ ----- 264 // \\ |Service Tag| // \\ 265 | Property+------+ ++--------+-+ +-------+ Property| 266 \\ A // | | | | \\ B // 267 -----+ +--V---V-+ +-V---V--+ ----- 268 | Child | | Child | 269 |ObjectA | |ObjectB | 270 /---\ +--^-----+ +-----^--+ /---\ 271 / \ | | / \ 272 |Metric +-------+ +--------|Metric | 273 \ A / \ B / 274 \---/ \---/ 276 +-----------------------------------------------------------+ 277 | Service Metric Metric Module Level | 278 | Tag Group Name | 279 | | 280 | L3VPN L3VPN maximum L3VPN Service | 281 | -routes | 282 | | 283 | L3VPN OSPF-Process total-active OSPF Device | 284 | routes | 285 | | 286 | total-active | 287 | L3VPN RIP-Process routes RIP Device | 288 | | 289 | total-active | 290 | L3VPN BGP-Process routes BGP Device | 291 | | 292 +-----------------------------------------------------------+ 294 1.2. Terminology 296 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 297 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 298 "OPTIONAL" in this document are to be interpreted as described in BCP 299 14 [RFC2119] [RFC8174] when, and only when, they appear in all 300 capitals, as shown here. 302 2. Data Node Tag Values 304 All data node tags SHOULD begin with a prefix indicating who owns 305 their definition. An IANA registry (Section 7.1) is used to support 306 registering data node tag prefixes. Currently 3 prefixes are 307 defined. 309 No further structure is imposed by this document on the value 310 following the registered prefix, and the value can contain any YANG 311 type 'string' characters except carriage-returns, newlines and tabs. 312 Therefore, designers, implementers, and users are free to add or not 313 add any structure they may require to their own tag values. 315 2.1. IETF Tags Prefix 317 An IETF tag is a data node tag that has the prefix "ietf:". All IETF 318 data node tags are registered with IANA in a registry defined later 319 in this document (Section 7.2). 321 2.2. Vendor Tags Prefix 323 A vendor tag is a tag that has the prefix "vendor:". These tags are 324 defined by the vendor that implements the module, and are not 325 registered; however, it is RECOMMENDED that the vendor include extra 326 identification in the tag to avoid collisions such as using the 327 enterpise or organization name following the "vendor:" prefix (e.g., 328 vendor:vendor-defined-classifier). 330 2.3. User Tags Prefix 332 A user tag is any tag that has the prefix "user:". These tags are 333 defined by the user/administrator and are not meant to be registered. 334 Users are not required to use the "user:" prefix; however, doing so 335 is RECOMMENDED as it helps avoid prefix collisions. 337 2.4. Reserved Tags Prefix 339 Any tag not starting with the prefix "ietf:", "vendor:" or "user:" is 340 reserved for future use. These tag values are not invalid, but 341 simply reserved in the context of specifications (e.g., RFCs). 343 3. Data Node Tag Management 345 Tags can become associated with a data node within YANG module in a 346 number of ways. Tags may be defined and associated at module design 347 time, at implementation time without the need of live server, or via 348 user administrative control . As the main consumer of data node tags 349 are users, users may also remove any tag from a live server, no 350 matter how the tag became associated with a data node within a YANG 351 module. 353 3.1. Module Design Tagging 355 A data node definition MAY indicate a set of data node tags to be 356 added by the module implementer. These design time tags are 357 indicated using the node-tag extension statement. 359 If the data node is defined in an IETF standards track document, the 360 data node tags MUST be IETF Tags (2.1). Thus, new data node can 361 drive the addition of new IETF tags to the IANA registry defined in 362 Section 7.2, and the IANA registry can serve as a check against 363 duplication. 365 3.2. Implementation Tagging 367 An implementation MAY include additional tags associated with data 368 node within a YANG module. These tags SHOULD be IETF Tags (i.e., 369 registered) or vendor specific tags. 371 3.3. User Tagging 373 Data node tags of any kind, with or without a prefix, can be assigned 374 and removed by the user from a live server using normal configuration 375 mechanisms. In order to remove a data node tag from the operational 376 datastore, the user adds a matching "masked-tag" entry for a given 377 data node within the ietf-data-node-tags Module. 379 4. Tags Module Structure 381 4.1. Tags Module Tree 383 The tree associated with the "ietf-data-node-tags" module follows. 384 The meaning of the symbols can be found in [RFC8340]. 386 module: ietf-data-node-tags 387 augment /tags:module-tags/tags:module: 388 +--rw self-explanation-node-tags 389 +--rw self-explanation-node* [node-name] 390 +--rw node-name nacm:node-instance-identifier 391 +--rw opm-tag tags:tag 392 +--rw metric-precision tags:tag 393 +--rw metric-scale tags:tag 394 +--rw operation-type tags:tag 395 +--rw service-tag* tags:tag 396 +--rw task-tag* tags:tag 397 +--rw multi-source-tag tags:tag 398 +--rw data-source tags:tag 400 5. YANG Module 402 file "ietf-self-explanation-node-tags@2019-05-03.yang" 403 module ietf-self-explanation-node-tags { 404 yang-version 1.1; 405 namespace "urn:ietf:params:xml:ns:yang:ietf-self-explanation-node-tags"; 406 prefix ntags; 407 import ietf-netconf-acm { prefix nacm; } 408 import ietf-module-tags { prefix tags; } 409 organization 410 "IETF NetMod Working Group (NetMod)"; 411 contact 412 "WG Web: 413 WG List: 414 Editor: Qin Wu 415 Editor: Benoit Claise 416 Editor: Liang Geng 417 Editor: Zongpeng Du "; 418 // RFC Ed.: replace XXXX with actual RFC number and 419 // remove this note. 421 description 422 "This module describes a mechanism associating self-explanation 423 tags with YANG data node within YANG modules. Tags may be IANA 424 assigned or privately defined. 426 Copyright (c) 2020 IETF Trust and the persons identified as 427 authors of the code. All rights reserved. 429 Redistribution and use in source and binary forms, with or 430 without modification, is permitted pursuant to, and subject to 431 the license terms contained in, the Simplified BSD License set 432 forth in Section 4.c of the IETF Trust's Legal Provisions 433 Relating to IETF Documents 434 (https://trustee.ietf.org/license-info). 436 This version of this YANG module is part of RFC XXXX 437 (https://tools.ietf.org/html/rfcXXXX); see the RFC itself for 438 full legal notices."; 440 // RFC Ed.: update the date below with the date of RFC publication 441 // and RFC number and remove this note. 443 revision 2019-05-03 { 444 description 445 "Initial revision."; 446 reference "RFC XXXX: YANG Data Node Tags"; 447 } 448 typedef tag { 449 type string { 450 length "1..max"; 451 pattern '[a-zA-Z_][a-zA-Z0-9\-_]*:[\S ]+'; 452 } 453 description 454 "A tag value is composed of a standard prefix followed by any type 455 'string' value that does not include carriage return, newline or 456 tab characters."; 457 } 458 typedef metric-precision { 459 type int8 { 460 range "-8 .. 9"; 461 } 462 description 463 "A node using this data type represents a sensor value 464 precision range. 466 A node of this type SHOULD be defined together with nodes of 467 type measurement-units and type measurement-scale. Together, 468 associated nodes of these three types are used to identify the 469 semantics of a node of type sensor-value. 471 If a node of this type contains a value in the range 1 to 9, 472 it represents the number of decimal places in the fractional 473 part of an associated sensor-value fixed-point number. 474 If a node of this type contains a value in the range -8 to -1, 475 it represents the number of accurate digits in the associated 476 sensor-value fixed-point number. 478 The value zero indicates the associated sensor-value node is 479 not a fixed-point number. 481 Server implementers must choose a value for the associated 482 sensor-value-precision node so that the precision and accuracy 483 of the associated sensor-value node is correctly indicated. 485 For example, a component representing a temperature sensor 486 that can measure 0 to 100 degrees C in 0.1 degree 487 increments, +/- 0.05 degrees, would have a 488 sensor-value-precision value of '1', a sensor-value-scale 489 value of 'units', and a sensor-value ranging from '0' to 490 '1000'. The sensor-value would be interpreted as 491 'degrees C * 10'."; 492 reference 493 "RFC 3433: Entity Sensor Management Information Base - 494 EntitySensorPrecision"; 495 } 497 typedef metric-scale { 498 type enumeration { 499 enum yocto { 500 value 1; 501 description 502 "Measurement scaling factor of 10^-24."; 503 } 504 enum zepto { 505 value 2; 506 description 507 "Measurement scaling factor of 10^-21."; 508 } 509 enum atto { 510 value 3; 511 description 512 "Measurement scaling factor of 10^-18."; 513 } 514 enum femto { 515 value 4; 516 description 517 "Measurement scaling factor of 10^-15."; 518 } 519 enum pico { 520 value 5; 521 description 522 "Measurement scaling factor of 10^-12."; 523 } 524 enum nano { 525 value 6; 526 description 527 "Measurement scaling factor of 10^-9."; 528 } 529 enum micro { 530 value 7; 531 description 532 "Measurement scaling factor of 10^-6."; 533 } 534 enum milli { 535 value 8; 536 description 537 "Measurement scaling factor of 10^-3."; 538 } 539 enum units { 540 value 9; 541 description 542 "Measurement scaling factor of 10^0."; 543 } 544 enum kilo { 545 value 10; 546 description 547 "Measurement scaling factor of 10^3."; 548 } 549 enum mega { 550 value 11; 551 description 552 "Measurement scaling factor of 10^6."; 553 } 554 enum giga { 555 value 12; 556 description 557 "Measurement scaling factor of 10^9."; 558 } 559 enum tera { 560 value 13; 561 description 562 "Measurement scaling factor of 10^12."; 563 } 564 enum peta { 565 value 14; 566 description 567 "Measurement scaling factor of 10^15."; 568 } 569 enum exa { 570 value 15; 571 description 572 "Measurement scaling factor of 10^18."; 573 } 574 enum zetta { 575 value 16; 576 description 577 "Measurement scaling factor of 10^21."; 579 } 580 enum yotta { 581 value 17; 582 description 583 "Measurement scaling factor of 10^24."; 584 } 585 } 586 description 587 "A node using this data type represents a data scaling factor, 588 represented with an International System of Units (SI) prefix. 589 The actual data units are determined by examining a node of 590 this type together with the associated sensor-value-type. 592 A node of this type SHOULD be defined together with nodes of 593 type sensor-value-type and type sensor-value-precision. 594 Together, associated nodes of these three types are used to 595 identify the semantics of a node of type sensor-value."; 596 reference 597 "RFC 3433: Entity Sensor Management Information Base - 598 EntitySensorDataScale"; 599 } 601 identity metric-unit { 602 description 603 "Base identity for measurement unit."; 604 } 606 identity ac-volts { 607 base metric-unit; 608 description 609 "Identity for a measure of electric potential (alternating current)."; 610 } 611 identity dc-volts { 612 base metric-unit; 613 description 614 "Identity for a measure of electric potential (direct current)."; 615 } 616 identity amperes { 617 base metric-unit; 618 description 619 "Identity for a measure of electric current."; 620 } 621 identity power { 622 base metric-unit; 623 description 624 "Identity for a measure of power."; 625 } 626 identity hertz { 627 base metric-unit; 628 description 629 "Identity for a measure of frequency."; 630 } 631 identity celsius { 632 base metric-unit; 633 description 634 "Identity for a measure of temperature."; 635 } 636 identity rpm { 637 base metric-unit; 638 description 639 "Identity for a measure of shaft revolutions per minute."; 640 } 641 extension opm-tag { 642 argument tag; 643 description 644 "The argument 'tag' is of type 'tag'. This extension statement 645 is used by module authors to indicate the opm tags that SHOULD be 646 added automatically by the system. As such the origin of the 647 value for the pre-defined tags should be set to 'system' 648 [RFC8342]."; 649 } 650 extension metric-scale{ 651 argument tag; 652 description 653 "The argument 'tag' is of type 'tag'.The metric-scale can be 654 used to provide an additional metric scale (e.g., Measurement 655 scaling factor of 10^0, 10^-3,10^3) information associated with 656 the performance metric data node tag."; 657 } 658 extension metric-precision { 659 argument tag; 660 description 661 "The argument 'tag' is of type 'tag'.The metric-precision can be 662 used to provide an additional metric precision (e.g., the range -8 to -1, 663 0, the range 1 to 9) information associated with the performance metric 664 data node tag."; 665 } 667 extension statistics-operation { 668 argument tag; 669 description 670 "The argument 'tag' is of type 'tag'.The statistics-operation can be 671 used to provide an additional statistics operation type(e.g., sum, 672 min, max,last) information associated with the performance metric 673 data node tag."; 674 } 676 extension service-tag { 677 argument tag; 678 description 679 "The argument 'tag' is of type 'tag'.The service-tag can be 680 used to provide a service classification information (e.g., tunnel, 681 l3vpn,l2vpn) information associated with YANG data node."; 682 } 684 extension task-tag { 685 argument tag; 686 description 687 "The argument 'tag' is of type 'tag'.The task-tag can be 688 used to provide a task classification information (e.g., fault management, 689 performance measurement) information associated with YANG data node."; 690 } 691 extension data-source { 692 argument tag; 693 description 694 "The argument 'tag' is of type 'tag'.The data-source-type can be 695 used to provide an additional data source type (e.g., connectivity, 696 resource, hardware,qos,policy) information associated with 697 the performance metric data node tag."; 698 } 699 extension multi-source-tag { 700 argument tag; 701 description 702 "The argument 'tag' is of type 'tag'.The multi-source-tag can be 703 used to provide an additional multiple source aggregation 704 information associated with the performance metric data node 705 or interface related data node."; 706 } 708 augment "/tags:module-tags/tags:module" { 709 description 710 "Augment the Tags module with data node tag attributes"; 711 container self-explanation-node-tags { 712 description 713 "Contains the list of data nodes and their associated tags"; 714 list self-explanation-node { 715 key "node-name"; 716 description 717 "A list of self-explanation nodes and their associated tags"; 718 leaf node-name { 719 type nacm:node-instance-identifier; 720 mandatory true; 721 description 722 "The YANG data node name."; 723 } 724 leaf opm-tag { 725 type tags:tag; 726 description 727 "Tags associated with the data node within YANG module. See 728 the IANA 'YANG Data Node Tag Prefixes' registry for reserved 729 prefixes and the IANA'IETF YANG Data Node Tags' registry for 730 IETF tags. 732 The 'operational' state [RFC8342] view of this list is 733 constructed using the following steps: 735 1) System tags (i.e., tags of 'system' origin) are added. 736 2) User configured tags (i.e., tags of 'intended' origin) 737 are added. 738 3) Any tag that is equal to a masked-tag is removed."; 739 } 740 leaf metric-precision { 741 type tags:tag; 742 description 743 "The numeric expression precision of performance 744 metric related data node."; 745 } 746 leaf metric-scale { 747 type tags:tag; 748 description 749 "The measurement scale of performance 750 metric related data node."; 751 } 752 leaf operation-type{ 753 type tags:tag; 754 description 755 "Statistics operation of performance metric related 756 data node, e.g., average,min, max,sum, threshold. 757 If the operation type is threshold type, the corresponding 758 data object support threshold handling,e.g.,scan all interfaces 759 for a certain type every 5 seconds and check the counters or 760 status to cross threshold, return an array of interface entries 761 that match the search.If the operation type is average,min,max, sum, 762 it indicate the data object supports statistics operation, e.g., 763 scan all interfaces for a certain type every 5 seconds up to 60 seconds, 764 only return min, average, max, sum value of specific data object rather than 765 the values that are current at the end of 60 seconds."; 766 } 767 leaf service-tag { 768 type tags:tag; 769 description 770 "The node-service-tag can be used to provide a service 771 classification information (e.g., tunnel, l3vpn,l2vpn) 772 information associated with YANG data node."; 773 } 774 leaf task-tag { 775 type tags:tag; 776 description 777 "The node-task-tag can be used to provide a task 778 classification information (e.g., fault management, 779 performance measurement) information associated with 780 YANG data node."; 781 } 782 leaf multi-source-tag { 783 type tags:tag; 784 description 785 "The mulitple source tag can be used to identify multiple source 786 aggregation tye(e.g., line card,member link in an aggregated 787 Ethernet interface) related to performance metric related 788 data node or interface related to data node). Two source 789 aggregation source types are supported, one is aggregation 790 which groups data from two or multiple different data objects, 791 the other is membership which identitfy each data object(e.g., 792 linecard, member link from multiple source aggregation."; 793 } 794 leaf data-source { 795 type tags:tag; 796 description 797 "The data source type (e.g., connectivity,resource, hardware 798 ,qos,policy) associated with the performance metric data node 799 within YANG module."; 800 } 801 } 802 } 803 } 804 } 805 807 6. Guidelines to Model Writers 809 This section updates [RFC8407]. 811 6.1. Define Standard Tags 813 A module MAY indicate, using node-tag extension statements, a set of 814 tags that are to be automatically associated with it (i.e., not added 815 through configuration). 817 module example-module-A { 818 //... 819 import ietf-data-node-tags { prefix ntags; } 820 container top { 821 ntags:opm-tag "ietf:object-type"; 822 list X { 823 leaf foo { 824 ntags:opm-tag "ietf:property"; 825 } 826 } 827 container Y { 828 ntags:opm-tag "ietf:metric"; 829 leaf bar { 830 ntags:statistics-operation "ietf:avg"; 831 ntags:metric-scale "ietf:milli"; 832 } 833 } 834 } 835 // ... 836 } 838 The module writer can use existing standard tags, or use new tags 839 defined in the model definition, as appropriate. For IETF 840 standardized modules new data node tags MUST be assigned in the IANA 841 registry defined below, see Section Section 7.2. 843 7. IANA Considerations 845 7.1. YANG Data Node Tag Prefixes Registry 847 IANA is asked to create a new registry "YANG Data Node Tag Prefixes" 848 grouped under a new "Protocol" category named "YANG Data Node Tag 849 Prefixes". 851 This registry allocates tag prefixes. All YANG data node tags SHOULD 852 begin with one of the prefixes in this registry. 854 Prefix entries in this registry should be short strings consisting of 855 lowercase ASCII alpha-numeric characters and a final ":" character. 857 The allocation policy for this registry is Specification Required 858 [RFC8126]. The Reference and Assignee values should be sufficient to 859 identify and contact the organization that has been allocated the 860 prefix. 862 The initial values for this registry are as follows. 864 +----------+----------------------------------+-----------+----------+ 865 | Prefix | Description | Reference | Assignee | 866 +----------+----------------------------------+-----------+----------+ 867 | ietf: | IETF Tags allocated in the IANA | [This | IETF | 868 | | IETF YANG Data Node Tags registry| document] | | 869 | | | | | 870 |vendor: | Non-registered tags allocated by | [This | IETF | 871 | | the module implementer. | document] | | 872 | | | | | 873 | user: | Non-registered tags allocated by | [This | IETF | 874 | | and for the user. | document] | | 875 +----------+----------------------------------+-----------+----------+ 877 Other standards organizations (SDOs) wishing to allocate their own 878 set of tags should allocate a prefix from this registry. 880 7.2. IETF YANG Data Node Tags Registry 882 IANA is asked to create four new registries "IETF YANG Data Node 883 Tags","IETF Metric Precision Tags","IETF Statistics Operation 884 Tags","Node Service Tag" grouped under a new "Protocol" category 885 "IETF YANG Data Node Tags". These four registries should be included 886 below "YANG Data Node Tag Prefixes" when listed on the same page. 888 Four registries allocate tags that have the registered prefix 889 "ietf:". New values should be well considered and not achievable 890 through a combination of already existing IETF tags. 892 The allocation policy for these four registries is IETF Review 893 [RFC8126]. 895 The initial values for these eight registries are as follows. 897 +----------------------------+--------------------------+-----------+ 898 | Data Node Tag | Description | Reference | 899 +----------------------------+--------------------------+-----------+ 900 | | | | 901 | ietf:object-type | Relates to object type | [This | 902 | | (e.g., interfaces). | document] | 903 | | | | 904 | ietf:metric | Relates to performance | [This | 905 | | metric info | document] | 906 | | (e.g., ifstatistics). | | 907 | | | | 908 | ietf:metric-group | Represent metric group | [This | 909 | | (e.g., flow statistics). | document] | 910 | | | | 911 | ietf:property | Represents a object | [This | 912 | | property | document] | 913 | | (e.g.,ifindex). | | 914 +----------------------------+--------------------------+-----------+ 915 +----------------------------+--------------------------+-----------+ 916 | Metric Precision | Description | Reference | 917 +----------------------------+--------------------------+-----------+ 918 |ietf:minus-eight |Relates to metric precision [This | 919 | | of performance metric | document] | 920 | | | | 921 |ietf:minus-seven |Relates to metric precision [This | 922 | | of performance metric | document] | 923 | | | | 924 |ietf:minus-sixe |Relates to metric precision [This | 925 | | of performance metric | document] | 926 | | | | 927 |ietf:minus-five |Relates to metric precision [This | 928 | | of performance metric | document] | 929 | | | | 930 |ietf:minus-four |Relates to metric precision [This | 931 | | of performance metric | document] | 932 | | | | 933 |ietf:minus-three |Relates to metric precision [This | 934 | | of performance metric | document] | 935 | | | | 936 |ietf:minus-two |Relates to metric precision [This | 937 | | of performance metric | document] | 938 | | | | 939 |ietf:minus-one |Relates to metric precision [This | 940 | | of performance metric | document] | 941 | | | | 942 |ietf:zero |Relates to metric precision [This | 943 | | of performance metric | document] | 944 | | | | 945 |ietf:one |Relates to metric precision [This | 946 | | of performance metric | document] | 947 | | | | 948 |ietf:two |Relates to metric precision [This | 949 | | of performance metric | document] | 950 | | | | 951 |ietf:three |Relates to metric precision [This | 952 | | of performance metric | document] | 953 | | | | 954 |ietf:four | Relates to metric precision [This | 955 | | of performance metric | document] | 956 | | | | 957 |ietf:five | Relates to metric precision [This | 958 | | of performance metric | document] | 959 | | | | 960 |ietf:six | Relates to metric precision [This | 961 | | of performance metric | document] | 962 | | | | 963 |ietf:seven | Relates to metric precision [This | 964 | | of performance metric | document] | 965 | | | | 966 |ietf:eight | Relates to metric precision [This | 967 | | of performance metric | document] | 968 | | | | 969 |ietf:nine | Relates to metric precision [This | 970 | | of performance metric | document] | 971 +----------------------------+--------------------------+-----------+ 972 +----------------------------+--------------------------+-----------+ 973 | Metric scale | Description | Reference | 974 +----------------------------+--------------------------+-----------+ 975 |ietf:yocto | Relates to metric scale | [This | 976 | | of performance metric | document] | 977 | | | | 978 |ietf:zepto | Relates to metric scale | [This | 979 | | of performance metric | document] | 980 | | | | 981 |ietf:atto | Relates to metric scale | [This | 982 | | of performance metric | document] | 983 | | | | 984 |ietf: femto | Relates to metric scale | [This | 985 | | of performance metric | document] | 986 | | | | 987 |ietf: pico | Relates to metric scale | [This | 988 | | of performance metric | document] | 989 | | | | 990 |ietf: nano | Relates to metric scale | [This | 991 | | of performance metric | document] | 992 | | | | 993 |ietf: micro | Relates to metric scale | [This | 994 | | of performance metric | document] | 995 | | | | 996 |ietf: milli | Relates to metric scale | [This | 997 | | of performance metric | document] | 998 | | | | 999 |ietf: units | Relates to metric scale | [This | 1000 | | of performance metric | document] | 1001 | | | | 1002 |ietf: kilo | Relates to metric scale | [This | 1003 | | of performance metric | document] | 1004 | | | | 1005 |ietf: mega | Relates to metric scale | [This | 1006 | | of performance metric | document] | 1007 | | | | 1008 |ietf: giga | Relates to metric scale | [This | 1009 | | of performance metric | document] | 1010 | | | | 1011 |ietf: tera | Relates to metric scale | [This | 1012 | | of performance metric | document] | 1013 | | | | 1014 |ietf: peta | Relates to metric scale | [This | 1015 | | of performance metric | document] | 1016 | | | | 1017 |ietf: exa | Relates to metric scale | [This | 1018 | | of performance metric | document] | 1019 | | | | 1020 |ietf: zetta | Relates to metric scale | [This | 1021 | | of performance metric | document] | 1022 | | | | 1023 |ietf: yotta | Relates to metric scale | [This | 1024 | | of performance metric | document] | 1025 +----------------------------+--------------------------+-----------+ 1026 +----------------------------+--------------------------+-----------+ 1027 | Operation Type Tag | Description | Reference | 1028 +----------------------------+--------------------------+-----------+ 1029 |ietf:avg | Relates to statistics | [This | 1030 | | operation(e.g.,average, | document] | 1031 | | min, max, sum,etc) | | 1032 |ietf:sum | Relates to statistics | [This | 1033 | | operation(e.g.,average, | document] | 1034 | | min, max, sum,etc) | | 1035 |ietf:min | Relates to statistics | [This | 1036 | | operation(e.g.,average, | document] | 1037 | | min, max, sum,etc) | | 1038 |ietf:max | Relates to statistics | [This | 1039 | | operation(e.g.,average, | document] | 1040 | | min, max, sum,etc) | | 1041 |ietf:threshold | Relates to statistics | [This | 1042 | | operation(e.g.,average, | document] | 1043 | | min, max, threshold,etc) | | 1044 +----------------------------+--------------------------+-----------+ 1045 +----------------------------+--------------------------+-----------+ 1046 | Parent Tag | Description | Reference | 1047 +----------------------------+--------------------------+-----------+ 1048 |ietf:member |Relates to multiple source| [This | 1049 | |aggregation type(e.g., | document] | 1050 | |lag, linecard, sub inf) | | 1051 | | | | 1052 |ietf:agg |Relates to multiple source| [This | 1053 | |aggregation type(e.g.,agg)| document] | 1054 +----------------------------+--------------------------+-----------+ 1055 +----------------------------+--------------------------+-----------+ 1056 | Data Source | Description | Reference | 1057 +----------------------------+--------------------------+-----------+ 1058 | | | | 1059 | ietf:service-flow | Relates to data source | [This | 1060 | | type(e.g., microburst). | document] | 1061 | | | | 1062 | ietf:topo | Relates to data source | [This | 1063 | | type(e.g., topology). | document] | 1064 | | | | 1065 | ietf:resource | Relates to data source | [This | 1066 | | type info | document] | 1067 | | (e.g., interface,queue). | | 1068 | | | | 1069 | ietf:policy | Relates to data source | [This | 1070 | | type info | document] | 1071 | |(e.g., acl, routing policy| | 1072 | | | | 1073 | ietf:hardware | Relates to data source | [This | 1074 | | type | document] | 1075 | | (e.g.,optical module). | | 1076 +----------------------------+--------------------------+-----------+ 1077 +----------------------------+--------------------------+-----------+ 1078 | Service Tag | Description | Reference | 1079 +----------------------------+--------------------------+-----------+ 1080 |ietf:l3vpn | Relates to service | [This | 1081 | | offering(e.g.,l3vpn | document] | 1082 | | l2vpn,tunnel,etc) | | 1083 |ietf:l2vpn | Relates to service | [This | 1084 | | offering(e.g.,l3vpn | document] | 1085 | | l2vpn,tunnel,etc) | | 1086 |ietf:te-tunnel | Relates to service | [This | 1087 | | offering(e.g.,l3vpn | document] | 1088 | | l2vpn,tunnel,etc) | | 1089 +----------------------------+--------------------------+-----------+ 1090 +----------------------------+--------------------------+-----------+ 1091 | Task Tag | Description | Reference | 1092 +----------------------------+--------------------------+-----------+ 1093 |ietf:vpn-diag | Relates to vpn serivce | [This | 1094 | | diagonostic function | document] | 1095 | | | | 1096 |ietf:vpn-fullfilment | Relates to vpn service | [This | 1097 | | fullfillment function | document] | 1098 | | | | 1099 |ietf:vpn-assurance | Relates to vpn service | [This | 1100 | | assurance function | document] | 1101 +----------------------------+--------------------------+-----------+ 1103 7.3. Updates to the IETF XML Registry 1105 This document registers a URI in the "IETF XML Registry" [RFC3688]. 1106 Following the format in [RFC3688], the following registration has 1107 been made: 1109 URI: 1110 urn:ietf:params:xml:ns:yang:ietf-self-explaination-node-tags 1111 Registrant Contact: 1112 The IESG. 1113 XML: 1114 N/A; the requested URI is an XML namespace. 1116 7.4. Updates to the YANG Module Names Registry 1118 This document registers one YANG module in the "YANG Module Names" 1119 registry [RFC6020]. Following the format in [RFC6020], the following 1120 registration has been made: 1122 name: 1123 ietf-self-explaination-node-tags 1124 namespace: 1125 urn:ietf:params:xml:ns:yang:ietf-self-explaination-node-tags 1126 prefix: 1127 ntags 1128 reference: 1129 RFC XXXX (RFC Ed.: replace XXX with actual RFC number and remove 1130 this note.) 1132 8. Security Considerations 1134 The YANG module defined in this memo is designed to be accessed via 1135 the NETCONF protocol [RFC6241]. The lowest NETCONF layer is the 1136 secure transport layer and the mandatory-to-implement secure 1137 transport is SSH [RFC6242]. 1139 This document adds the ability to associate data node tag meta-data 1140 with YANG modules. This document does not define any actions based 1141 on these associations, and none are yet defined, and therefore it 1142 does not by itself introduce any new security considerations. 1144 Users of the data node tag-meta data may define various actions to be 1145 taken based on the data node tag meta-data. These actions and their 1146 definitions are outside the scope of this document. Users will need 1147 to consider the security implications of any actions they choose to 1148 define. 1150 9. Contributors 1152 The authors would like to thank Ran Tao for his major contributions 1153 to the initial modeling and use cases. 1155 10. References 1157 10.1. Normative References 1159 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1160 Requirement Levels", BCP 14, RFC 2119, 1161 DOI 10.17487/RFC2119, March 1997, 1162 . 1164 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1165 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1166 . 1168 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 1169 Writing an IANA Considerations Section in RFCs", BCP 26, 1170 RFC 8126, DOI 10.17487/RFC8126, June 2017, 1171 . 1173 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1174 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1175 May 2017, . 1177 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1178 and R. Wilton, "Network Management Datastore Architecture 1179 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 1180 . 1182 [RFC8407] Bierman, A., "Guidelines for Authors and Reviewers of 1183 Documents Containing YANG Data Models", BCP 216, RFC 8407, 1184 DOI 10.17487/RFC8407, October 2018, 1185 . 1187 10.2. Informative References 1189 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1190 DOI 10.17487/RFC3688, January 2004, 1191 . 1193 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1194 the Network Configuration Protocol (NETCONF)", RFC 6020, 1195 DOI 10.17487/RFC6020, October 2010, 1196 . 1198 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1199 and A. Bierman, Ed., "Network Configuration Protocol 1200 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1201 . 1203 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 1204 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 1205 . 1207 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 1208 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 1209 . 1211 Appendix A. Targeted data object subscription example 1213 The following subsections provides targeted data object subscription 1214 example.The subscription "id" values of 22 used below is just an 1215 example. In production, the actual values of "id" might not be small 1216 integers. 1218 +-----------+ +-----------+ 1219 | Subscriber| | Publisher | 1220 +------+----+ +-----+-----+ 1221 | | 1222 | | 1223 |Telemery data Tagging Advertisement 1224 | (node-selector, opm-tag = metric) 1225 |<---------------------------------| 1226 | | 1227 | establish-subscription | 1228 | (datasore,node-selector) | 1229 |--------------------------------->| 1230 | | 1231 | | 1232 | | 1233 | RPC Reply: OK, id = 22 | 1234 |<---------------------------------| 1235 | | 1236 | | 1237 | | 1238 | Notification Message (for 22) | 1239 | <--------------------------------| 1240 | | 1241 | | 1242 | | 1244 The publisher advertise telemetry data node capability to the 1245 subscriber to instruct the receiver to subscribe targeted data object 1246 with specific characteristics (e.g., performance metric related data 1247 object) and specific data path corresponding to the targeted data 1248 object. 1250 The following XML example [W3C.REC-xml-20081126] illustrates the 1251 advertisment of the list of available target objects: 1253 1254 1256 acme-router-notification-capabilities 1257 1258 ietf-system-capabilities@2020-03-23 1259 ietf-notification-capabilities@2020-03-23 1260 ietf-data-export-capabilities@2020-03-23 1261 1262 1263 Defines the notification capabilities of an acme-router. 1264 The router only has running, and operational datastores. 1265 Every change can be reported on-change from running, but 1266 only config=true nodes and some config=false data from operational. 1267 Statistics are not reported based on timer based trigger and counter 1268 threshold based trigger. 1269 1270 1271 1276 1277 ds:operational 1278 1279 \ 1280 /if:interfaces/if:interface/if:statistics/if:in-errors\ 1281 1282 1283 bandwith 1284 metric 1285 1286 1287 1288 1289 1290 1292 With telemetry data tagging information carried in the Telemetry data 1293 Tagging Advertisement, the subscriber identifies targeted data object 1294 and associated data path to the datastore node and sends a establish- 1295 subscription RPC to subscribe specific data objects that are 1296 interests to the client application from the publisher. 1298 1300 1303 1305 ds:operational 1306 1307 1309 /if:interfaces/if:interface/if:statistics/if:in-errors 1310 1311 1312 500 1313 1314 1315 1317 The publisher returns specific object type of operational state 1318 related to the subscriber. 1320 Authors' Addresses 1322 Qin Wu 1323 Huawei 1324 101 Software Avenue, Yuhua District 1325 Nanjing, Jiangsu 210012 1326 China 1328 Email: bill.wu@huawei.com 1330 Benoit Claise 1331 Cisco 1332 De Kleetlaan 6a b1 1333 Diegem 1831 1334 Belgium 1336 Email: bclaise@cisco.com 1337 Liang Geng 1338 China Mobile 1339 32 Xuanwumen West St, Xicheng District 1340 Beijing 10053 1342 Email: gengliang@chinamobile.com 1344 Zongpeng Du 1345 China Mobile 1346 32 Xuanwumen West St, Xicheng District 1347 Beijing 10053 1349 Email: duzongpeng@chinamobile.com