idnits 2.17.1 draft-tao-netmod-yang-node-tags-02.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 34 instances of too long lines in the document, the longest one being 11 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 214 has weird spacing: '...latency tunne...' == Line 216 has weird spacing: '...et-loss tunne...' == Line 218 has weird spacing: '...latency tunne...' == Line 220 has weird spacing: '...latency tunne...' == Line 222 has weird spacing: '...-packet tun...' == (6 more instances...) -- The document date (June 1, 2020) is 1425 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 142, 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 R. Tao 3 Internet-Draft Q. Wu 4 Intended status: Standards Track Huawei 5 Expires: December 3, 2020 B. Claise 6 Cisco 7 L. Geng 8 Z. Du 9 China Mobile 10 June 1, 2020 12 YANG Data Node Self Explanation Tags 13 draft-tao-netmod-yang-node-tags-02 15 Abstract 17 This document defines a method to tag data node associated with 18 telemetry data in YANG Modules. This YANG data node tagging method 19 can be used to provide input, instruction, indication to selection 20 filter and filter queries of operational state on a server during a 21 "pub/sub" service for YANG datastore updates and provide multiple 22 dimensional network visibility analysis when the state of all 23 subscriptions of a particular Subscriber to be fetched is huge, so 24 that the amount of data to be streamed out to the destination can be 25 greatly reduced and only targeted to the characteristics data. 27 An extension statement to be used to indicate YANG data node self 28 explanation tags that SHOULD be added by the module implementation 29 automatically (i.e., outside of configuration). 31 A YANG module [RFC7950] is defined, which augments Module tag model 32 and provides a list of data node entries to allow for adding or 33 removing of data node self explanation tags as well as viewing the 34 set of self explanation tags associated with a YANG module. 36 Status of This Memo 38 This Internet-Draft is submitted in full conformance with the 39 provisions of BCP 78 and BCP 79. 41 Internet-Drafts are working documents of the Internet Engineering 42 Task Force (IETF). Note that other groups may also distribute 43 working documents as Internet-Drafts. The list of current Internet- 44 Drafts is at https://datatracker.ietf.org/drafts/current/. 46 Internet-Drafts are draft documents valid for a maximum of six months 47 and may be updated, replaced, or obsoleted by other documents at any 48 time. It is inappropriate to use Internet-Drafts as reference 49 material or to cite them other than as "work in progress." 51 This Internet-Draft will expire on December 3, 2020. 53 Copyright Notice 55 Copyright (c) 2020 IETF Trust and the persons identified as the 56 document authors. All rights reserved. 58 This document is subject to BCP 78 and the IETF Trust's Legal 59 Provisions Relating to IETF Documents 60 (https://trustee.ietf.org/license-info) in effect on the date of 61 publication of this document. Please review these documents 62 carefully, as they describe your rights and restrictions with respect 63 to this document. Code Components extracted from this document must 64 include Simplified BSD License text as described in Section 4.e of 65 the Trust Legal Provisions and are provided without warranty as 66 described in the Simplified BSD License. 68 Table of Contents 70 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 71 1.1. Data Node tags Use Cases . . . . . . . . . . . . . . . . 4 72 1.1.1. Multiple Dimensional Performance Measurement 73 Information Tagging . . . . . . . . . . . . . . . . . 4 74 1.1.2. Correlated Information Tagging . . . . . . . . . . . 7 75 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 8 76 2. Data Node Tag Values . . . . . . . . . . . . . . . . . . . . 8 77 2.1. IETF Tags Prefix . . . . . . . . . . . . . . . . . . . . 8 78 2.2. Vendor Tags Prefix . . . . . . . . . . . . . . . . . . . 8 79 2.3. User Tags Prefix . . . . . . . . . . . . . . . . . . . . 8 80 2.4. Reserved Tags Prefix . . . . . . . . . . . . . . . . . . 8 81 3. Data Node Tag Management . . . . . . . . . . . . . . . . . . 9 82 3.1. Module Design Tagging . . . . . . . . . . . . . . . . . . 9 83 3.2. Implementation Tagging . . . . . . . . . . . . . . . . . 9 84 3.3. User Tagging . . . . . . . . . . . . . . . . . . . . . . 9 85 4. Tags Module Structure . . . . . . . . . . . . . . . . . . . . 9 86 4.1. Tags Module Tree . . . . . . . . . . . . . . . . . . . . 9 87 5. YANG Module . . . . . . . . . . . . . . . . . . . . . . . . . 10 88 6. Guidelines to Model Writers . . . . . . . . . . . . . . . . . 18 89 6.1. Define Standard Tags . . . . . . . . . . . . . . . . . . 18 90 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 91 7.1. YANG Data Node Tag Prefixes Registry . . . . . . . . . . 19 92 7.2. IETF YANG Data Node Tags Registry . . . . . . . . . . . . 20 93 7.3. Updates to the IETF XML Registry . . . . . . . . . . . . 25 94 7.4. Updates to the YANG Module Names Registry . . . . . . . . 25 95 8. Security Considerations . . . . . . . . . . . . . . . . . . . 25 96 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 26 97 9.1. Normative References . . . . . . . . . . . . . . . . . . 26 98 9.2. Informative References . . . . . . . . . . . . . . . . . 26 99 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 27 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 the IETF. 111 They cover many of the networking protocols and techniques. However 112 data objects defined by these technology specific data models might 113 represent a portion of fault, configuration, accounting, performance, 114 security management categories information (e.g., performance metric 115 associated with specific data object type) in various different way, 116 lack the same classification criteria and granularity,e.g., sensor 117 data in hardware model is defined with fine granularity with value 118 scale and value precision while interface model only provides 119 statistics data for specific interface type. 121 This document defines data node self explanation tags and associates 122 them with data nodes within YANG module, which 124 o Provide dictionary meaning for each data node; 126 o Indicate relationship between data nodes within the same YANG 127 module or of different YANG modules; 129 o Identify key performance metric scale, precision, statistics 130 operation; 132 o Identify specific service or feature, data source. 134 The data node self explanation tags can be used by the client to 135 provide input, instruction, indication to selection filter and filter 136 queries of configuration or operational state on a server based on 137 these data node tags,.e.g.,return specific object type operational 138 state related to system-management. NETCONF clients can discover 139 data models with data node self explanation tags supported by a 140 NETCONF server via operation. The data node self 141 explanation tag capability can also be advertised via capability 142 notification Model [I-D.netconf-notification-capabilities] by the 143 NETCONF server or some place where offline document are kept. These 144 self explanation tags may be registered as well as assigned during 145 the module definition; assigned by implementations; or dynamically 146 defined and set by users. 148 This document defines a YANG module [RFC7950] which augments module 149 tag model and provides a list of data node entries to allow for 150 adding or removing of self explanation tags as well as viewing the 151 set of self explanation tags associated with a data node within YANG 152 modules. 154 This document defines an extension statement to be used to indicate 155 self explanation tags that SHOULD be added by the module 156 implementation automatically (i.e., outside of configuration). 158 The YANG data model in this document conforms to the Network 159 Management Datastore Architecture defined in [RFC8342]. 161 1.1. Data Node tags Use Cases 163 The following is a list of already implemented and potential use 164 cases. 166 1.1.1. Multiple Dimensional Performance Measurement Information Tagging 168 Data node tags can be used to express multiple dimensional 169 performance metric and properties associated with YANG data nodes or 170 data objects modelled with YANG (See Figure 1). 172 ----- ----- 173 // \\ // \\ 174 | Property+------+ +-------+ Property| 175 \\ A // | | \\ B // 176 -----+ +--V----------------V---+ ----- 177 | YANG Data Node | 178 | /Data Object | 179 /---\ +--^----------------^---+ /---\ 180 / \ | | / \ 181 |Metric +-------+ +--------|Metric | 182 \ A / +-------------+ \ B / 183 \-+-/ | | \-+-/ 184 | | Metric Group| | 185 -------------| |--------------- 186 +-------------+ 188 Figure 1 190 The use of data node tags would be to help filter different discrete 191 categories of YANG data nodes across YANG modules supported by a 192 device. If data nodes across YANG modules are suitably tagged and 193 learnt by the client from a live server, then an XPath query can be 194 used by the client to list all related data nodes supported by a 195 device with the same characteristics. Data node tags can also be 196 used to help coordination when clients are interacting with various 197 different devices with the same categories of YANG data node across 198 different YANG modules. For example, one management client could 199 mark some specific data node across modules implemented in various 200 different devices with the same metric group tag, so consistent 201 representation and reporting can be provided for YANG data nodes 202 belonging to the same metric group (see Figure 2). 204 +-----------+---------------+-----------+-----------------------+ 205 | Object | Property | Metric | Metric Module | 206 | Name | Name | Group | Name | 207 | | | | | 208 |tunnel-svc | name | - | - tunnel | 209 | | | | | 210 |tunnel-svc | create-time | - | - tunnel | 211 | | | | | 212 |tunnel-svc | modified-time | - | - | 213 | | | | | 214 |tunnel-svc | - |lsp-ping-pm| avg-latency tunnel-pm| 215 | | | | | 216 |tunnel-svc | - |lsp-ping-pm| packet-loss tunnel-pm| 217 | | | | | 218 |tunnel-svc | - |lsp-ping-pm| min-latency tunnel-pm| 219 | | | | | 220 |tunnel-svc | - |lsp-ping-pm| max-latency tunnel-pm| 221 | | | |transmitted | 222 |tunnel-svc | - |lsp-ping-pm| -packet tunnel-pm| 223 +-----------+---------------+-----------+-----------------------+ 225 +---------------------------------------------------------+ 226 | Metric Metric Metric Metric Metric | 227 | Group Name Precision Scale Unit | 228 | | 229 | lsp-ping-pm avg- 1 1 ms | 230 | latency | 231 | | 232 | lsp-ping-pm packet- 1 1 percentile | 233 | loss | 234 | | 235 | | 236 | lsp-ping-pm min- 1 1 ms | 237 | latency | 238 | | 239 | | 240 | lsp-ping-pm max- 1 1 ms | 241 | latency | 242 | | 243 | | 244 | lsp-ping-pm transmitted 1 1 | 245 +---------------------------------------------------------+ 247 Figure 2 249 1.1.2. Correlated Information Tagging 251 Another example is the management client could mark some data node 252 across different level of YANG modules implemented in the device, the 253 management system with the same service tag (e.g., L3VPN Service), so 254 root cause can be identified efficiently during service-level 255 agreements and performance monitoring or network failure 256 troubleshooting. 258 +--------------+ 259 | Parent object| 260 +-------^------+ 261 | 262 ----- +-----+-----+ ----- 263 // \\ |Service Tag| // \\ 264 | Property+------+ ++--------+-+ +-------+ Property| 265 \\ A // | | | | \\ B // 266 -----+ +--V---V-+ +-V---V--+ ----- 267 | Child | | Child | 268 |ObjectA | |ObjectB | 269 /---\ +--^-----+ +-----^--+ /---\ 270 / \ | | / \ 271 |Metric +-------+ +--------|Metric | 272 \ A / \ B / 273 \---/ \---/ 275 +-----------------------------------------------------------+ 276 | Service Metric Metric Module Level | 277 | Tag Group Name | 278 | | 279 | L3VPN L3VPN maximum L3VPN Service | 280 | -routes | 281 | | 282 | L3VPN OSPF-Process total-active OSPF Device | 283 | routes | 284 | | 285 | total-active | 286 | L3VPN RIP-Process routes RIP Device | 287 | | 288 | total-active | 289 | L3VPN BGP-Process routes BGP Device | 290 | | 291 +-----------------------------------------------------------+ 293 1.2. Terminology 295 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 296 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 297 "OPTIONAL" in this document are to be interpreted as described in BCP 298 14 [RFC2119] [RFC8174] when, and only when, they appear in all 299 capitals, as shown here. 301 2. Data Node Tag Values 303 All data node tags SHOULD begin with a prefix indicating who owns 304 their definition. An IANA registry (Section 7.1) is used to support 305 registering data node tag prefixes. Currently 3 prefixes are 306 defined. 308 No further structure is imposed by this document on the value 309 following the registered prefix, and the value can contain any YANG 310 type 'string' characters except carriage-returns, newlines and tabs. 311 Therefore, designers, implementers, and users are free to add or not 312 add any structure they may require to their own tag values. 314 2.1. IETF Tags Prefix 316 An IETF tag is a data node tag that has the prefix "ietf:". All IETF 317 data node tags are registered with IANA in a registry defined later 318 in this document (Section 7.2). 320 2.2. Vendor Tags Prefix 322 A vendor tag is a tag that has the prefix "vendor:". These tags are 323 defined by the vendor that implements the module, and are not 324 registered; however, it is RECOMMENDED that the vendor include extra 325 identification in the tag to avoid collisions such as using the 326 enterpise or organization name following the "vendor:" prefix (e.g., 327 vendor:vendor-defined-classifier). 329 2.3. User Tags Prefix 331 A user tag is any tag that has the prefix "user:". These tags are 332 defined by the user/administrator and are not meant to be registered. 333 Users are not required to use the "user:" prefix; however, doing so 334 is RECOMMENDED as it helps avoid prefix collisions. 336 2.4. Reserved Tags Prefix 338 Any tag not starting with the prefix "ietf:", "vendor:" or "user:" is 339 reserved for future use. These tag values are not invalid, but 340 simply reserved in the context of specifications (e.g., RFCs). 342 3. Data Node Tag Management 344 Tags can become associated with a data node within YANG module in a 345 number of ways. Tags may be defined and associated at module design 346 time, at implementation time without the need of live server, or via 347 user administrative control . As the main consumer of data node tags 348 are users, users may also remove any tag from a live server, no 349 matter how the tag became associated with a data node within a YANG 350 module. 352 3.1. Module Design Tagging 354 A data node definition MAY indicate a set of data node tags to be 355 added by the module implementer. These design time tags are 356 indicated using the node-tag extension statement. 358 If the data node is defined in an IETF standards track document, the 359 data node tags MUST be IETF Tags (2.1). Thus, new data node can 360 drive the addition of new IETF tags to the IANA registry defined in 361 Section 7.2, and the IANA registry can serve as a check against 362 duplication. 364 3.2. Implementation Tagging 366 An implementation MAY include additional tags associated with data 367 node within a YANG module. These tags SHOULD be IETF Tags (i.e., 368 registered) or vendor specific tags. 370 3.3. User Tagging 372 Data node tags of any kind, with or without a prefix, can be assigned 373 and removed by the user from a live server using normal configuration 374 mechanisms. In order to remove a data node tag from the operational 375 datastore, the user adds a matching "masked-tag" entry for a given 376 data node within the ietf-data-node-tags Module. 378 4. Tags Module Structure 380 4.1. Tags Module Tree 382 The tree associated with the "ietf-data-node-tags" module follows. 383 The meaning of the symbols can be found in [RFC8340]. 385 module: ietf-data-node-tags 386 augment /tags:module-tags/tags:module: 387 +--rw self-explanation-node-tags 388 +--rw self-explanation-node* [node-name] 389 +--rw node-name nacm:node-instance-identifier 390 +--rw opm-tag tags:tag 391 +--rw metric-precision tags:tag 392 +--rw metric-scale tags:tag 393 +--rw operation-type tags:tag 394 +--rw service-tag* tags:tag 395 +--rw task-tag* tags:tag 396 +--rw parent-tag tags:tag 397 +--rw data-source tags:tag 399 5. YANG Module 401 file "ietf-self-explanation-node-tags@2019-05-03.yang" 402 module ietf-self-explanation-node-tags { 403 yang-version 1.1; 404 namespace "urn:ietf:params:xml:ns:yang:ietf-self-explanation-node-tags"; 405 prefix ntags; 406 import ietf-netconf-acm { prefix nacm; } 407 import ietf-module-tags { prefix tags; } 408 organization 409 "IETF NetMod Working Group (NetMod)"; 410 contact 411 "WG Web: 412 WG List: 413 Editor: Ran Tao 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."; 578 } 579 enum yotta { 580 value 17; 581 description 582 "Measurement scaling factor of 10^24."; 583 } 584 } 585 description 586 "A node using this data type represents a data scaling factor, 587 represented with an International System of Units (SI) prefix. 588 The actual data units are determined by examining a node of 589 this type together with the associated sensor-value-type. 591 A node of this type SHOULD be defined together with nodes of 592 type sensor-value-type and type sensor-value-precision. 593 Together, associated nodes of these three types are used to 594 identify the semantics of a node of type sensor-value."; 595 reference 596 "RFC 3433: Entity Sensor Management Information Base - 597 EntitySensorDataScale"; 598 } 600 identity metric-unit { 601 description 602 "Base identity for measurement unit."; 603 } 605 identity ac-volts { 606 base metric-unit; 607 description 608 "Identity for a measure of electric potential (alternating current)."; 609 } 610 identity dc-volts { 611 base metric-unit; 612 description 613 "Identity for a measure of electric potential (direct current)."; 614 } 615 identity amperes { 616 base metric-unit; 617 description 618 "Identity for a measure of electric current."; 619 } 620 identity power { 621 base metric-unit; 622 description 623 "Identity for a measure of power."; 624 } 625 identity hertz { 626 base metric-unit; 627 description 628 "Identity for a measure of frequency."; 629 } 630 identity celsius { 631 base metric-unit; 632 description 633 "Identity for a measure of temperature."; 634 } 635 identity rpm { 636 base metric-unit; 637 description 638 "Identity for a measure of shaft revolutions per minute."; 639 } 640 extension opm-tag { 641 argument tag; 642 description 643 "The argument 'tag' is of type 'tag'. This extension statement 644 is used by module authors to indicate the opm tags that SHOULD be 645 added automatically by the system. As such the origin of the 646 value for the pre-defined tags should be set to 'system' 647 [RFC8342]."; 648 } 649 extension metric-scale{ 650 argument tag; 651 description 652 "The argument 'tag' is of type 'tag'.The metric-scale can be 653 used to provide an additional metric scale (e.g., Measurement 654 scaling factor of 10^0, 10^-3,10^3) information associated with 655 the performance metric data node tag."; 656 } 657 extension metric-precision { 658 argument tag; 659 description 660 "The argument 'tag' is of type 'tag'.The metric-precision can be 661 used to provide an additional metric precision (e.g., the range -8 to -1, 662 0, the range 1 to 9) information associated with the performance metric 663 data node tag."; 664 } 666 extension statistics-operation { 667 argument tag; 668 description 669 "The argument 'tag' is of type 'tag'.The statistics-operation can be 670 used to provide an additional statistics operation type(e.g., sum, 671 min, max,last) information associated with the performance metric 672 data node tag."; 674 } 675 extension service-tag { 676 argument tag; 677 description 678 "The argument 'tag' is of type 'tag'.The service-tag can be 679 used to provide a service classification information (e.g., tunnel, 680 l3vpn,l2vpn) information associated with YANG data node."; 681 } 683 extension task-tag { 684 argument tag; 685 description 686 "The argument 'tag' is of type 'tag'.The task-tag can be 687 used to provide a task classification information (e.g., fault management, 688 performance measurement) information associated with YANG data node."; 689 } 690 extension data-source { 691 argument tag; 692 description 693 "The argument 'tag' is of type 'tag'.The data-source-type can be 694 used to provide an additional data source type (e.g., connectivity, 695 resource, hardware,qos,policy) information associated with 696 the performance metric data node tag."; 697 } 698 extension parent-tag { 699 argument tag; 700 description 701 "The argument 'tag' is of type 'tag'.The parent-tag can be 702 used to provide an additional multiple source aggregation 703 information associated with the performance metric data node 704 or interface related data node."; 705 } 707 augment "/tags:module-tags/tags:module" { 708 description 709 "Augment the Tags module with data node tag attributes"; 710 container self-explanation-node-tags { 711 description 712 "Contains the list of data nodes and their associated tags"; 713 list self-explanation-node { 714 key "node-name"; 715 description 716 "A list of self-explanation nodes and their associated tags"; 717 leaf node-name { 718 type nacm:node-instance-identifier; 719 mandatory true; 720 description 721 "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."; 757 } 758 leaf service-tag { 759 type tags:tag; 760 description 761 "The node-service-tag can be used to provide a service 762 classification information (e.g., tunnel, l3vpn,l2vpn) 763 information associated with YANG data node."; 764 } 765 leaf task-tag { 766 type tags:tag; 767 description 768 "The node-task-tag can be used to provide a task 769 classification information (e.g., fault management, 770 performance measurement) information associated with 771 YANG data node."; 772 } 773 leaf parent-tag { 774 type tags:tag; 775 description 776 "The parent tag can be used to identify multiple source 777 aggregation tye(e.g., line card,member link in an aggregated 778 Ethernet interface) related to performance metric related 779 data node or interface related to data node). Two source 780 aggregation source types are supported, one is aggregation 781 which groups data from two or multiple different data objects, 782 the other is membership which identitfy each data object(e.g., 783 linecard, member link from multiple source aggregation."; 784 } 785 leaf data-source { 786 type tags:tag; 787 description 788 "The data source type (e.g., connectivity,resource, hardware 789 ,qos,policy) associated with the performance metric data node 790 within YANG module."; 791 } 792 } 793 } 794 } 795 } 796 798 6. Guidelines to Model Writers 800 This section updates [RFC8407]. 802 6.1. Define Standard Tags 804 A module MAY indicate, using node-tag extension statements, a set of 805 tags that are to be automatically associated with it (i.e., not added 806 through configuration). 808 module example-module-A { 809 //... 810 import ietf-data-node-tags { prefix ntags; } 811 container top { 812 ntags:opm-tag "ietf:object-type"; 813 list X { 814 leaf foo { 815 ntags:opm-tag "ietf:property"; 816 } 817 } 818 container Y { 819 ntags:opm-tag "ietf:metric"; 820 leaf bar { 821 ntags:statistics-operation "ietf:avg"; 822 ntags:metric-scale "ietf:milli"; 823 } 824 } 825 } 826 // ... 827 } 829 The module writer can use existing standard tags, or use new tags 830 defined in the model definition, as appropriate. For IETF 831 standardized modules new data node tags MUST be assigned in the IANA 832 registry defined below, see Section Section 7.2. 834 7. IANA Considerations 836 7.1. YANG Data Node Tag Prefixes Registry 838 IANA is asked to create a new registry "YANG Data Node Tag Prefixes" 839 grouped under a new "Protocol" category named "YANG Data Node Tag 840 Prefixes". 842 This registry allocates tag prefixes. All YANG data node tags SHOULD 843 begin with one of the prefixes in this registry. 845 Prefix entries in this registry should be short strings consisting of 846 lowercase ASCII alpha-numeric characters and a final ":" character. 848 The allocation policy for this registry is Specification Required 849 [RFC8126]. The Reference and Assignee values should be sufficient to 850 identify and contact the organization that has been allocated the 851 prefix. 853 The initial values for this registry are as follows. 855 +----------+----------------------------------+-----------+----------+ 856 | Prefix | Description | Reference | Assignee | 857 +----------+----------------------------------+-----------+----------+ 858 | ietf: | IETF Tags allocated in the IANA | [This | IETF | 859 | | IETF YANG Data Node Tags registry| document] | | 860 | | | | | 861 |vendor: | Non-registered tags allocated by | [This | IETF | 862 | | the module implementer. | document] | | 863 | | | | | 864 | user: | Non-registered tags allocated by | [This | IETF | 865 | | and for the user. | document] | | 866 +----------+----------------------------------+-----------+----------+ 868 Other standards organizations (SDOs) wishing to allocate their own 869 set of tags should allocate a prefix from this registry. 871 7.2. IETF YANG Data Node Tags Registry 873 IANA is asked to create four new registries "IETF YANG Data Node 874 Tags","IETF Metric Precision Tags","IETF Statistics Operation 875 Tags","Node Service Tag" grouped under a new "Protocol" category 876 "IETF YANG Data Node Tags". These four registries should be included 877 below "YANG Data Node Tag Prefixes" when listed on the same page. 879 Four registries allocate tags that have the registered prefix 880 "ietf:". New values should be well considered and not achievable 881 through a combination of already existing IETF tags. 883 The allocation policy for these four registries is IETF Review 884 [RFC8126]. 886 The initial values for these eight registries are as follows. 888 +----------------------------+--------------------------+-----------+ 889 | Data Node Tag | Description | Reference | 890 +----------------------------+--------------------------+-----------+ 891 | | | | 892 | ietf:object-type | Relates to object type | [This | 893 | | (e.g., interfaces). | document] | 894 | | | | 895 | ietf:metric | Relates to performance | [This | 896 | | metric info | document] | 897 | | (e.g., ifstatistics). | | 898 | | | | 899 | ietf:metric-group | Represent metric group | [This | 900 | | (e.g., flow statistics). | document] | 901 | | | | 902 | ietf:property | Represents a object | [This | 903 | | property | document] | 904 | | (e.g.,ifindex). | | 905 +----------------------------+--------------------------+-----------+ 906 +----------------------------+--------------------------+-----------+ 907 | Metric Precision | Description | Reference | 908 +----------------------------+--------------------------+-----------+ 909 |ietf:minus-eight |Relates to metric precision [This | 910 | | of performance metric | document] | 911 | | | | 912 |ietf:minus-seven |Relates to metric precision [This | 913 | | of performance metric | document] | 914 | | | | 915 |ietf:minus-sixe |Relates to metric precision [This | 916 | | of performance metric | document] | 917 | | | | 918 |ietf:minus-five |Relates to metric precision [This | 919 | | of performance metric | document] | 920 | | | | 921 |ietf:minus-four |Relates to metric precision [This | 922 | | of performance metric | document] | 923 | | | | 924 |ietf:minus-three |Relates to metric precision [This | 925 | | of performance metric | document] | 926 | | | | 927 |ietf:minus-two |Relates to metric precision [This | 928 | | of performance metric | document] | 929 | | | | 930 |ietf:minus-one |Relates to metric precision [This | 931 | | of performance metric | document] | 932 | | | | 933 |ietf:zero |Relates to metric precision [This | 934 | | of performance metric | document] | 935 | | | | 936 |ietf:one |Relates to metric precision [This | 937 | | of performance metric | document] | 938 | | | | 939 |ietf:two |Relates to metric precision [This | 940 | | of performance metric | document] | 941 | | | | 942 |ietf:three |Relates to metric precision [This | 943 | | of performance metric | document] | 944 | | | | 945 |ietf:four | Relates to metric precision [This | 946 | | of performance metric | document] | 947 | | | | 948 |ietf:five | Relates to metric precision [This | 949 | | of performance metric | document] | 950 | | | | 951 |ietf:six | Relates to metric precision [This | 952 | | of performance metric | document] | 953 | | | | 954 |ietf:seven | Relates to metric precision [This | 955 | | of performance metric | document] | 956 | | | | 957 |ietf:eight | Relates to metric precision [This | 958 | | of performance metric | document] | 959 | | | | 960 |ietf:nine | Relates to metric precision [This | 961 | | of performance metric | document] | 962 +----------------------------+--------------------------+-----------+ 963 +----------------------------+--------------------------+-----------+ 964 | Metric scale | Description | Reference | 965 +----------------------------+--------------------------+-----------+ 966 |ietf:yocto | Relates to metric scale | [This | 967 | | of performance metric | document] | 968 | | | | 969 |ietf:zepto | Relates to metric scale | [This | 970 | | of performance metric | document] | 971 | | | | 972 |ietf:atto | Relates to metric scale | [This | 973 | | of performance metric | document] | 974 | | | | 975 |ietf: femto | Relates to metric scale | [This | 976 | | of performance metric | document] | 977 | | | | 978 |ietf: pico | Relates to metric scale | [This | 979 | | of performance metric | document] | 980 | | | | 981 |ietf: nano | Relates to metric scale | [This | 982 | | of performance metric | document] | 983 | | | | 984 |ietf: micro | Relates to metric scale | [This | 985 | | of performance metric | document] | 986 | | | | 987 |ietf: milli | Relates to metric scale | [This | 988 | | of performance metric | document] | 989 | | | | 990 |ietf: units | Relates to metric scale | [This | 991 | | of performance metric | document] | 992 | | | | 993 |ietf: kilo | Relates to metric scale | [This | 994 | | of performance metric | document] | 995 | | | | 996 |ietf: mega | Relates to metric scale | [This | 997 | | of performance metric | document] | 998 | | | | 999 |ietf: giga | Relates to metric scale | [This | 1000 | | of performance metric | document] | 1001 | | | | 1002 |ietf: tera | Relates to metric scale | [This | 1003 | | of performance metric | document] | 1004 | | | | 1005 |ietf: peta | Relates to metric scale | [This | 1006 | | of performance metric | document] | 1007 | | | | 1008 |ietf: exa | Relates to metric scale | [This | 1009 | | of performance metric | document] | 1010 | | | | 1011 |ietf: zetta | Relates to metric scale | [This | 1012 | | of performance metric | document] | 1013 | | | | 1014 |ietf: yotta | Relates to metric scale | [This | 1015 | | of performance metric | document] | 1016 +----------------------------+--------------------------+-----------+ 1017 +----------------------------+--------------------------+-----------+ 1018 | Statistics Operation Tag | Description | Reference | 1019 +----------------------------+--------------------------+-----------+ 1020 |ietf:avg | Relates to statistics | [This | 1021 | | operation(e.g.,average, | document] | 1022 | | min, max, sum,etc) | | 1023 |ietf:sum | Relates to statistics | [This | 1024 | | operation(e.g.,average, | document] | 1025 | | min, max, sum,etc) | | 1026 |ietf:min | Relates to statistics | [This | 1027 | | operation(e.g.,average, | document] | 1028 | | min, max, sum,etc) | | 1029 |ietf:max | Relates to statistics | [This | 1030 | | operation(e.g.,average, | document] | 1031 | | min, max, sum,etc) | | 1032 |ietf:threshold | Relates to statistics | [This | 1033 | | operation(e.g.,average, | document] | 1034 | | min, max, threshold,etc) | | 1035 +----------------------------+--------------------------+-----------+ 1036 +----------------------------+--------------------------+-----------+ 1037 | Parent Tag | Description | Reference | 1038 +----------------------------+--------------------------+-----------+ 1039 |ietf:member |Relates to multiple source| [This | 1040 | |aggregation type(e.g., | document] | 1041 | |lag, linecard, sub inf) | | 1042 | | | | 1043 |ietf:agg |Relates to multiple source| [This | 1044 | |aggregation type(e.g.,agg)| document] | 1045 +----------------------------+--------------------------+-----------+ 1046 +----------------------------+--------------------------+-----------+ 1047 | Data Source | Description | Reference | 1048 +----------------------------+--------------------------+-----------+ 1049 | | | | 1050 | ietf:service-flow | Relates to data source | [This | 1051 | | type(e.g., microburst). | document] | 1052 | | | | 1053 | ietf:topo | Relates to data source | [This | 1054 | | type(e.g., topology). | document] | 1055 | | | | 1056 | ietf:resource | Relates to data source | [This | 1057 | | type info | document] | 1058 | | (e.g., interface,queue). | | 1059 | | | | 1060 | ietf:policy | Relates to data source | [This | 1061 | | type info | document] | 1062 | |(e.g., acl, routing policy| | 1063 | | | | 1064 | ietf:hardware | Relates to data source | [This | 1065 | | type | document] | 1066 | | (e.g.,optical module). | | 1067 +----------------------------+--------------------------+-----------+ 1068 +----------------------------+--------------------------+-----------+ 1069 | Service Tag | Description | Reference | 1070 +----------------------------+--------------------------+-----------+ 1071 |ietf:l3vpn | Relates to service | [This | 1072 | | offering(e.g.,l3vpn | document] | 1073 | | l2vpn,tunnel,etc) | | 1074 |ietf:l2vpn | Relates to service | [This | 1075 | | offering(e.g.,l3vpn | document] | 1076 | | l2vpn,tunnel,etc) | | 1077 |ietf:te-tunnel | Relates to service | [This | 1078 | | offering(e.g.,l3vpn | document] | 1079 | | l2vpn,tunnel,etc) | | 1080 +----------------------------+--------------------------+-----------+ 1081 +----------------------------+--------------------------+-----------+ 1082 | Task Tag | Description | Reference | 1083 +----------------------------+--------------------------+-----------+ 1084 |ietf:vpn-diag | Relates to vpn serivce | [This | 1085 | | diagonostic function | document] | 1086 | | | | 1087 |ietf:vpn-fullfilment | Relates to vpn service | [This | 1088 | | fullfillment function | document] | 1089 | | | | 1090 |ietf:vpn-assurance | Relates to vpn service | [This | 1091 | | assurance function | document] | 1092 +----------------------------+--------------------------+-----------+ 1094 7.3. Updates to the IETF XML Registry 1096 This document registers a URI in the "IETF XML Registry" [RFC3688]. 1097 Following the format in [RFC3688], the following registration has 1098 been made: 1100 URI: 1101 urn:ietf:params:xml:ns:yang:ietf-self-explaination-node-tags 1102 Registrant Contact: 1103 The IESG. 1104 XML: 1105 N/A; the requested URI is an XML namespace. 1107 7.4. Updates to the YANG Module Names Registry 1109 This document registers one YANG module in the "YANG Module Names" 1110 registry [RFC6020]. Following the format in [RFC6020], the following 1111 registration has been made: 1113 name: 1114 ietf-self-explaination-node-tags 1115 namespace: 1116 urn:ietf:params:xml:ns:yang:ietf-self-explaination-node-tags 1117 prefix: 1118 ntags 1119 reference: 1120 RFC XXXX (RFC Ed.: replace XXX with actual RFC number and remove 1121 this note.) 1123 8. Security Considerations 1125 The YANG module defined in this memo is designed to be accessed via 1126 the NETCONF protocol [RFC6241]. The lowest NETCONF layer is the 1127 secure transport layer and the mandatory-to-implement secure 1128 transport is SSH [RFC6242]. 1130 This document adds the ability to associate data node tag meta-data 1131 with YANG modules. This document does not define any actions based 1132 on these associations, and none are yet defined, and therefore it 1133 does not by itself introduce any new security considerations. 1135 Users of the data node tag-meta data may define various actions to be 1136 taken based on the data node tag meta-data. These actions and their 1137 definitions are outside the scope of this document. Users will need 1138 to consider the security implications of any actions they choose to 1139 define. 1141 9. References 1143 9.1. Normative References 1145 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1146 Requirement Levels", BCP 14, RFC 2119, 1147 DOI 10.17487/RFC2119, March 1997, 1148 . 1150 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1151 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1152 . 1154 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 1155 Writing an IANA Considerations Section in RFCs", BCP 26, 1156 RFC 8126, DOI 10.17487/RFC8126, June 2017, 1157 . 1159 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1160 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1161 May 2017, . 1163 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1164 and R. Wilton, "Network Management Datastore Architecture 1165 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 1166 . 1168 [RFC8407] Bierman, A., "Guidelines for Authors and Reviewers of 1169 Documents Containing YANG Data Models", BCP 216, RFC 8407, 1170 DOI 10.17487/RFC8407, October 2018, 1171 . 1173 9.2. Informative References 1175 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1176 DOI 10.17487/RFC3688, January 2004, 1177 . 1179 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1180 the Network Configuration Protocol (NETCONF)", RFC 6020, 1181 DOI 10.17487/RFC6020, October 2010, 1182 . 1184 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1185 and A. Bierman, Ed., "Network Configuration Protocol 1186 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1187 . 1189 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 1190 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 1191 . 1193 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 1194 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 1195 . 1197 Authors' Addresses 1199 Ran Tao 1200 Huawei 1202 Email: taoran20@huawei.com 1204 Qin Wu 1205 Huawei 1206 101 Software Avenue, Yuhua District 1207 Nanjing, Jiangsu 210012 1208 China 1210 Email: bill.wu@huawei.com 1212 Benoit Claise 1213 Cisco 1214 De Kleetlaan 6a b1 1215 Diegem 1831 1216 Belgium 1218 Email: bclaise@cisco.com 1220 Liang Geng 1221 China Mobile 1222 32 Xuanwumen West St, Xicheng District 1223 Beijing 10053 1225 Email: gengliang@chinamobile.com 1227 Zongpeng Du 1228 China Mobile 1229 32 Xuanwumen West St, Xicheng District 1230 Beijing 10053 1232 Email: duzongpeng@chinamobile.com