idnits 2.17.1 draft-tao-netmod-yang-node-tags-04.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 61 instances of too long lines in the document, the longest one being 16 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 223 has weird spacing: '...latency tunne...' == Line 225 has weird spacing: '...et-loss tunne...' == Line 227 has weird spacing: '...latency tunne...' == Line 229 has weird spacing: '...latency tunne...' == Line 231 has weird spacing: '...-packet tun...' == (7 more instances...) -- The document date (August 10, 2020) is 1354 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) No issues found here. Summary: 2 errors (**), 0 flaws (~~), 7 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: February 11, 2021 Cisco 6 L. Geng 7 Z. Du 8 China Mobile 9 August 10, 2020 11 Self Explanation Data Object Tags 12 draft-tao-netmod-yang-node-tags-04 14 Abstract 16 This document defines a method to tag data objects associated with 17 operation and management data in YANG Modules. This YANG data object 18 tagging method can be used to identify characteristics data and 19 correlate data objects from different data sources and provide input, 20 instruction, indication to selection filter and filter queries of 21 operational state on a server during a "pub/sub" service for YANG 22 datastore updates. When the state of all subscriptions of a 23 particular Subscriber to be fetched is huge, the amount of data to be 24 streamed out to the destination can be greatly reduced and only 25 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 February 11, 2021. 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 Self Explanation Tags Use Cases . . . . . . . . 4 72 1.1.1. Network Performance Data Collection . . . . . . . . . 4 73 1.1.2. Context Information Tagging . . . . . . . . . . . . . 7 74 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 8 75 2. Data Object Tag Values . . . . . . . . . . . . . . . . . . . 8 76 2.1. IETF Tags Prefix . . . . . . . . . . . . . . . . . . . . 8 77 2.2. Vendor Tags Prefix . . . . . . . . . . . . . . . . . . . 9 78 2.3. User Tags Prefix . . . . . . . . . . . . . . . . . . . . 9 79 2.4. Reserved Tags Prefix . . . . . . . . . . . . . . . . . . 9 80 3. Data Object Tag Management . . . . . . . . . . . . . . . . . 9 81 3.1. Module Design Tagging . . . . . . . . . . . . . . . . . . 9 82 3.2. Implementation Tagging . . . . . . . . . . . . . . . . . 10 83 3.3. User Tagging . . . . . . . . . . . . . . . . . . . . . . 10 84 4. Tags Module Structure . . . . . . . . . . . . . . . . . . . . 10 85 4.1. Tags Module Tree . . . . . . . . . . . . . . . . . . . . 10 86 5. YANG Module . . . . . . . . . . . . . . . . . . . . . . . . . 10 87 6. Guidelines to Model Writers . . . . . . . . . . . . . . . . . 18 88 6.1. Define Standard Tags . . . . . . . . . . . . . . . . . . 18 89 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 90 7.1. YANG Data Node Tag Prefixes Registry . . . . . . . . . . 19 91 7.2. IETF YANG Data Node Tags Registry . . . . . . . . . . . . 20 92 7.3. Updates to the IETF XML Registry . . . . . . . . . . . . 25 93 7.4. Updates to the YANG Module Names Registry . . . . . . . . 25 94 8. Security Considerations . . . . . . . . . . . . . . . . . . . 25 95 9. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 26 96 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 26 97 10.1. Normative References . . . . . . . . . . . . . . . . . . 26 98 10.2. Informative References . . . . . . . . . . . . . . . . . 27 99 Appendix A. NETCONF Example . . . . . . . . . . . . . . . . . . 27 100 Appendix B. Non-NMDA State Module . . . . . . . . . . . . . . . 28 101 Appendix C. Targeted data object subscription example . . . . . 36 102 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 39 104 1. Introduction 106 As described [I.D-ietf-netmod-module-tags], the use of tags for 107 classification and organization is fairly ubiquitous not only within 108 IETF protocols, but in the internet itself (e.g., "#hashtags"). A 109 module tag defined in [I.D-ietf-netmod-module-tags] is a string 110 associated only with a module name at module level. 112 At the time of writing this document (2020), there are many data 113 models that have been specified or are being specified by various 114 different SDOs and Open Souce community. They cover many of the 115 networking protocols and techniques. However data objects defined by 116 these technology specific data models might represent a portion of 117 fault, configuration, accounting, performance, security management 118 categories information (e.g., performance metric specific data object 119 type) in various different ways, lack consistent classification 120 criteria and representation granularity,e.g., sensor data in hardware 121 model is defined with fine granularity with value scale and value 122 precision while interface model only provides statistics data for 123 specific interface type. 125 This document defines data object self explanation tags and 126 associates them with data nodes within YANG module, which 128 o Provide dictionary meaning for specific targeted data nodes; 130 o Indicate relationship between data nodes within the same YANG 131 module or from different YANG modules; 133 o Identify key performance metric scale, precision, statistics 134 operation; 136 o Identify specific service or feature, data source. 138 The data object self explanation tags can be used by the client to 139 identify characteristics data and correlate data objects from 140 different data sources and provide input, instruction, indication to 141 selection filter and filter queries of configuration or operational 142 state on a server based on these data object tags,.e.g.,return 143 specific object type of operational state related to system- 144 management. NETCONF clients can discover data objects with self 145 explanation data object tags supported by a NETCONF server via operation. The data object self explanation tag capability 147 can also be advertised via capability notification Model [I- 148 D.netconf-notification-capabilities] by the NETCONF server or some 149 place where offline document are kept. These self explanation tags 150 may be registered as well as assigned during the module definition; 151 assigned by implementations; or dynamically defined and set by users. 153 This document defines a YANG module [RFC7950] which augments module 154 tag model and provides a list of data object entries to allow for 155 adding or removing of self explanation tags as well as viewing the 156 set of self explanation tags associated with a data node within YANG 157 modules. 159 This document defines an extension statement to be used to indicate 160 self explanation tags that SHOULD be added by the module 161 implementation automatically (i.e., outside of configuration). 163 The YANG data model in this document conforms to the Network 164 Management Datastore Architecture defined in [RFC8342]. 166 1.1. Data Node Self Explanation Tags Use Cases 168 The following is a list of already implemented and potential use 169 cases. 171 1.1.1. Network Performance Data Collection 173 Among Data object tags, performance metric tag can be used to capture 174 performance metric and properties associated with YANG data nodes or 175 data objects modelled with YANG (See Figure 1). 177 ----- ----- 178 // \\ // \\ 179 | Property+------+ +-------+ Property| 180 \\ A // | | \\ B // 181 -----+ +--V----------------V---+ ----- 182 | YANG Data Node | 183 | /Data Object A | 184 /---\ +--^----------------^---+ /---\ 185 / \ | | / \ 186 |Metric +-------+ +--------|Metric | 187 \ A / \ B / 188 \-+-/ \-+-/ 189 +-------------+ | 190 | |-------------- 191 | Metric Group| 192 /----\ | |-------------+ 193 / \ +-------------+ | 194 |Property| | 195 \ D / | 196 \--+-/ /----\ 197 | +----------------------+ / \ 198 | | YANG Data Node <-------| Metric | 199 +---| /Data Object B | \ C / 200 +----------------------+ \----/ 202 Figure 1 204 The use of performance metric tags would be to help filter discrete 205 categories of YANG data objects across different YANG modules 206 supported by a device and capture network performance data. If data 207 objects across YANG modules are suitably tagged and learnt by the 208 client from a live server, the client can extract paths to all 209 interested data objects and then use an XPath query to list all 210 related data objects which reflect network characteristics(see 211 Figure 2). 213 +-----------+---------------+-----------+-----------------------+ 214 | Object | Property | Metric | Metric Module | 215 | Name | Name | Group | Name | 216 | | | | | 217 |tunnel-svc | name | - | - tunnel | 218 | | | | | 219 |tunnel-svc | create-time | - | - tunnel | 220 | | | | | 221 |tunnel-svc | modified-time | - | - | 222 | | | | | 223 |tunnel-svc | - |lsp-ping-pm| avg-latency tunnel-pm| 224 | | | | | 225 |tunnel-svc | - |lsp-ping-pm| packet-loss tunnel-pm| 226 | | | | | 227 |tunnel-svc | - |lsp-ping-pm| min-latency tunnel-pm| 228 | | | | | 229 |tunnel-svc | - |lsp-ping-pm| max-latency tunnel-pm| 230 | | | |transmitted | 231 |tunnel-svc | - |lsp-ping-pm| -packet tunnel-pm| 232 +-----------+---------------+-----------+-----------------------+ 233 +---------------------------------------------------------+ 234 | Metric Metric Metric Metric Operation | 235 | Group Name Precision Scale Type | 236 | | 237 | lsp-ping-pm avg- 1 1 avg | 238 | latency | 239 | | 240 | lsp-ping-pm packet- 1 1 avg | 241 | loss | 242 | | 243 | | 244 | lsp-ping-pm min- 1 1 min | 245 | latency | 246 | | 247 | | 248 | lsp-ping-pm max- 1 1 max | 249 | latency | 250 | | 251 | | 252 | lsp-ping-pm transmitted 1 1 | 253 +---------------------------------------------------------+ 255 Figure 2 257 1.1.2. Context Information Tagging 259 Performance metric tags can also be used to help correlate data 260 objects with the same characteristics when clients are interacting 261 with various different devices with the different categories of YANG 262 data node across different YANG modules. For example, one management 263 client could mark some specific data node across modules implemented 264 in various different devices with the same metric group tag as 265 context information, so consistent representation and reporting can 266 be provided for YANG data nodes belonging to the same metric group 267 (see Figure 2). 269 Another example is the management client could mark some data node 270 across different level of YANG modules implemented in the device, the 271 management system separately with the same service tag (e.g., L3VPN 272 Service) as context information, so root cause can be identified 273 efficiently during network failure troubleshooting (See Figure 3) 275 +--------------+ 276 | Parent object| 277 +-------^------+ 278 | 279 ----- +-----+-----+ ----- 280 // \\ |Service Tag| // \\ 281 | Property+------+ ++--------+-+ +-------+ Property| 282 \\ A // | | | | \\ B // 283 -----+ +--V---V-+ +-V---V--+ ----- 284 | Child | | Child | 285 |ObjectA | |ObjectB | 286 /---\ +--^-----+ +-----^--+ /---\ 287 / \ | | / \ 288 |Metric +-------+ +--------|Metric | 289 \ A / \ B / 290 \---/ \---/ 292 Figure 3 294 +-----------------------------------------------------------+ 295 | Service Metric Metric Module Level | 296 | Tag Group Name | 297 | | 298 | L3VPN L3VPN maximum L3VPN Service | 299 | -routes | 300 | | 301 | L3VPN OSPF-Process total-active OSPF Device | 302 | routes | 303 | | 304 | total-active | 305 | L3VPN RIP-Process routes RIP Device | 306 | | 307 | total-active | 308 | L3VPN BGP-Process routes BGP Device | 309 | | 310 +-----------------------------------------------------------+ 312 Figure 4 314 1.2. Terminology 316 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 317 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 318 "OPTIONAL" in this document are to be interpreted as described in BCP 319 14 [RFC2119] [RFC8174] when, and only when, they appear in all 320 capitals, as shown here. 322 2. Data Object Tag Values 324 All data object tags SHOULD begin with a prefix indicating who owns 325 their definition. An IANA registry (Section 7.1) is used to support 326 registering data node tag prefixes. Currently 3 prefixes are 327 defined. 329 No further structure is imposed by this document on the value 330 following the registered prefix, and the value can contain any YANG 331 type 'string' characters except carriage-returns, newlines and tabs. 332 Therefore, designers, implementers, and users are free to add or not 333 add any structure they may require to their own tag values. 335 2.1. IETF Tags Prefix 337 An IETF tag is a data object tag that has the prefix "ietf:". All 338 IETF data node tags are registered with IANA in a registry defined 339 later in this document (Section 7.2). 341 2.2. Vendor Tags Prefix 343 A vendor tag is a tag that has the prefix "vendor:". These tags are 344 defined by the vendor that implements the module, and are not 345 registered; however, it is RECOMMENDED that the vendor include extra 346 identification in the tag to avoid collisions such as using the 347 enterprise or organization name following the "vendor:" prefix (e.g., 348 vendor:vendor-defined-classifier). 350 2.3. User Tags Prefix 352 A user tag is any tag that has the prefix "user:". These tags are 353 defined by the user/administrator and are not meant to be registered. 354 Users are not required to use the "user:" prefix; however, doing so 355 is RECOMMENDED as it helps avoid prefix collisions. 357 2.4. Reserved Tags Prefix 359 Any tag not starting with the prefix "ietf:", "vendor:" or "user:" is 360 reserved for future use. These tag values are not invalid, but 361 simply reserved in the context of specifications (e.g., RFCs). 363 3. Data Object Tag Management 365 Tags can become associated with a data object within YANG module in a 366 number of ways. Tags may be defined and associated at module design 367 time, at implementation time without the need of live server, or via 368 user administrative control . As the main consumer of data node tags 369 are users, users may also remove any tag from a live server, no 370 matter how the tag became associated with a data node within a YANG 371 module. 373 3.1. Module Design Tagging 375 A data node definition MAY indicate a set of data object tags to be 376 added by the module implementer. These design time tags are 377 indicated using the node-tag extension statement. 379 If the data node is defined in an IETF standards track document, the 380 data object tags MUST be IETF Tags (2.1). Thus, new data node can 381 drive the addition of new IETF tags to the IANA registry defined in 382 Section 7.2, and the IANA registry can serve as a check against 383 duplication. 385 3.2. Implementation Tagging 387 An implementation MAY include additional tags associated with data 388 node within a YANG module. These tags SHOULD be IETF Tags (i.e., 389 registered) or vendor specific tags. 391 3.3. User Tagging 393 Data object tags of any kind, with or without a prefix, can be 394 assigned and removed by the user from a live server using normal 395 configuration mechanisms. In order to remove a data object tag from 396 the operational datastore, the user adds a matching "masked-tag" 397 entry for a given data node within the ietf-data-node-tags Module. 399 4. Tags Module Structure 401 4.1. Tags Module Tree 403 The tree associated with the "ietf-data-object-tags" module follows. 404 The meaning of the symbols can be found in [RFC8340]. 406 module: ietf-data-object-tags 407 augment /tags:module-tags/tags:module: 408 +--rw data-object-tags 409 +--rw data-object* [object-name] 410 +--rw object-name nacm:node-instance-identifier 411 +--rw tag* tags:tag 412 +--rw masked-tag* tags:tag 414 5. YANG Module 416 file "ietf-data-object-tags@2019-05-03.yang" 417 module ietf-data-object-tags { 418 yang-version 1.1; 419 namespace "urn:ietf:params:xml:ns:yang:ietf-data-object-tags"; 420 prefix ntags; 422 import ietf-netconf-acm { 423 prefix nacm; 424 } 425 import ietf-module-tags { 426 prefix tags; 427 } 429 organization 430 "IETF NetMod Working Group (NetMod)"; 431 contact 432 "WG Web: 433 WG List: 434 Editor: Qin Wu 435 Editor: Benoit Claise 436 Editor: Liang Geng 437 Editor: Zongpeng Du "; 438 description 439 "This module describes a mechanism associating self-explanation 440 tags with YANG data node within YANG modules. Tags may be IANA 441 assigned or privately defined. 443 Copyright (c) 2020 IETF Trust and the persons identified as 444 authors of the code. All rights reserved. 446 Redistribution and use in source and binary forms, with or 447 without modification, is permitted pursuant to, and subject to 448 the license terms contained in, the Simplified BSD License set 449 forth in Section 4.c of the IETF Trust's Legal Provisions 450 Relating to IETF Documents 451 (https://trustee.ietf.org/license-info). 453 This version of this YANG module is part of RFC XXXX 454 (https://tools.ietf.org/html/rfcXXXX); see the RFC itself for 455 full legal notices."; 457 revision 2019-05-03 { 458 description 459 "Initial revision."; 460 reference 461 "RFC XXXX: YANG Data Node Tags"; 462 } 464 typedef metric-precision { 465 type int8 { 466 range "-8 .. 9"; 467 } 468 description 469 "A node using this data type represents a sensor value 470 precision range. 472 A node of this type SHOULD be defined together with nodes of 473 type measurement-units and type measurement-scale. Together, 474 associated nodes of these three types are used to identify the 475 semantics of a node of type sensor-value. 477 If a node of this type contains a value in the range 1 to 9, 478 it represents the number of decimal places in the fractional 479 part of an associated sensor-value fixed-point number. 480 If a node of this type contains a value in the range -8 to -1, 481 it represents the number of accurate digits in the associated 482 sensor-value fixed-point number. 484 The value zero indicates the associated sensor-value node is 485 not a fixed-point number. 487 Server implementers must choose a value for the associated 488 sensor-value-precision node so that the precision and accuracy 489 of the associated sensor-value node is correctly indicated. 491 For example, a component representing a temperature sensor 492 that can measure 0 to 100 degrees C in 0.1 degree 493 increments, +/- 0.05 degrees, would have a 494 sensor-value-precision value of '1', a sensor-value-scale 495 value of 'units', and a sensor-value ranging from '0' to 496 '1000'. The sensor-value would be interpreted as 497 'degrees C * 10'."; 498 reference 499 "RFC 3433: Entity Sensor Management Information Base - 500 EntitySensorPrecision"; 501 } 503 typedef metric-scale { 504 type enumeration { 505 enum yocto { 506 value 1; 507 description 508 "Measurement scaling factor of 10^-24."; 509 } 510 enum zepto { 511 value 2; 512 description 513 "Measurement scaling factor of 10^-21."; 514 } 515 enum atto { 516 value 3; 517 description 518 "Measurement scaling factor of 10^-18."; 519 } 520 enum femto { 521 value 4; 522 description 523 "Measurement scaling factor of 10^-15."; 524 } 525 enum pico { 526 value 5; 527 description 528 "Measurement scaling factor of 10^-12."; 530 } 531 enum nano { 532 value 6; 533 description 534 "Measurement scaling factor of 10^-9."; 535 } 536 enum micro { 537 value 7; 538 description 539 "Measurement scaling factor of 10^-6."; 540 } 541 enum milli { 542 value 8; 543 description 544 "Measurement scaling factor of 10^-3."; 545 } 546 enum units { 547 value 9; 548 description 549 "Measurement scaling factor of 10^0."; 550 } 551 enum kilo { 552 value 10; 553 description 554 "Measurement scaling factor of 10^3."; 555 } 556 enum mega { 557 value 11; 558 description 559 "Measurement scaling factor of 10^6."; 560 } 561 enum giga { 562 value 12; 563 description 564 "Measurement scaling factor of 10^9."; 565 } 566 enum tera { 567 value 13; 568 description 569 "Measurement scaling factor of 10^12."; 570 } 571 enum peta { 572 value 14; 573 description 574 "Measurement scaling factor of 10^15."; 575 } 576 enum exa { 577 value 15; 578 description 579 "Measurement scaling factor of 10^18."; 580 } 581 enum zetta { 582 value 16; 583 description 584 "Measurement scaling factor of 10^21."; 585 } 586 enum yotta { 587 value 17; 588 description 589 "Measurement scaling factor of 10^24."; 590 } 591 } 592 description 593 "A node using this data type represents a data scaling factor, 594 represented with an International System of Units (SI) prefix. 595 The actual data units are determined by examining a node of 596 this type together with the associated sensor-value-type. 598 A node of this type SHOULD be defined together with nodes of 599 type sensor-value-type and type sensor-value-precision. 600 Together, associated nodes of these three types are used to 601 identify the semantics of a node of type sensor-value."; 602 reference 603 "RFC 3433: Entity Sensor Management Information Base - 604 EntitySensorDataScale"; 605 } 607 extension opm-tag { 608 argument tag; 609 description 610 "The argument 'tag' is of type 'tag'. This extension statement 611 is used by module authors to indicate the opm tags that SHOULD be 612 added automatically by the system. Opm Tag is used to classify 613 operation and management data into object type, property, metric group and metric 614 As such the origin of the value for the pre-defined tags should be 615 set to 'system'[RFC8342]."; 616 } 618 extension metric-scale { 619 argument tag; 620 description 621 "The argument 'tag' is of type 'tag'. The metric-scale tag can be 622 used to provide an additional data scale factor(e.g., Measurement 623 scaling factor of 10^0, 10^-3,10^3) information associated with 624 the performance metric data object. 626 A node using metric scale tag SHOULD be defined together with nodes of 627 type metric unit and type metric precision. 628 Together, associated nodes of these three types are used to 629 identify the semantics of the performance metric data object."; 630 reference 631 "RFC 3433: Entity Sensor Management Information Base - 632 EntitySensorDataScale"; 633 } 635 extension metric-precision { 636 argument tag; 637 description 638 "The argument 'tag' is of type 'tag'. The metric-precision can be 639 used to provide an additional sensor value precision range (e.g., 640 the range -8 to -1, 0, the range 1 to 9) information associated 641 with the performance metric data object. 643 A node using metric precision tag SHOULD be defined together with 644 nodes of type metric unit and type metric scale. Together, associated 645 nodes of these three types are used to identify the semantics of the 646 performance metric data object. 648 If a node of this type contains a value in the range 1 to 9, 649 it represents the number of decimal places in the fractional 650 part of an associated sensor-value fixed-point number. 651 If a node of this type contains a value in the range -8 to -1, 652 it represents the number of accurate digits in the associated 653 sensor-value fixed-point number. 655 The value zero indicates the associated sensor-value node is 656 not a fixed-point number. 658 Server implementers must choose a value for the associated 659 metric precision tag so that the precision and accuracy 660 of the associated sensor-value node is correctly indicated. 662 For example, a component representing a temperature sensor 663 that can measure 0 to 100 degrees C in 0.1 degree 664 increments, +/- 0.05 degrees, would have a 665 sensor-value-precision value of '1', a sensor-value-scale 666 value of 'units', and a sensor-value ranging from '0' to 667 '1000'. The sensor-value would be interpreted as 668 'degrees C * 10'."; 669 reference 670 "RFC 3433: Entity Sensor Management Information Base - 671 EntitySensorDataScale"; 672 } 673 extension operation-type { 674 argument tag; 675 description 676 "The argument 'tag' is of type 'tag'.The statistics-operation can be 677 used to provide an additional statistics operation type(e.g., sum, 678 min, max,sum,last, threshold) information associated with the performance metric 679 data object. 681 If the operation type is threshold type, the corresponding 682 data object support threshold handling,e.g.,scan all interfaces 683 for a certain type every 5 seconds and check the counters or 684 status to cross threshold, return an array of interface entries 685 that match the search. 687 If the operation type is average,min,max,sum,last, 688 it indicate the data object supports statistics operation, e.g., 689 scan all interfaces for a certain type every 5 seconds up to 60 seconds, 690 only return min, average, max, sum value of specific data object rather than 691 the values that are current at the end of 60 seconds."; 692 } 694 extension metric-group { 695 argument tag; 696 description 697 "The argument 'tag' is of type 'tag'.The metric-group can be 698 used to provide correlation between different metric information 699 associated with YANG data node."; 700 } 702 extension service-tag { 703 argument tag; 704 description 705 "The argument 'tag' is of type 'tag'.The service-tag can be 706 used to provide a service classification information (e.g., tunnel, 707 l3vpn,l2vpn) information associated with YANG data node."; 708 } 710 extension task-tag { 711 argument tag; 712 description 713 "The argument 'tag' is of type 'tag'.The task-tag can be 714 used to provide a task classification information (e.g., fault management, 715 performance measurement) information associated with YANG data node."; 716 } 718 extension data-source { 719 argument tag; 720 description 721 "The argument 'tag' is of type 'tag'.The data-source-type can be 722 used to provide an additional data source type (e.g., connectivity, 723 resource, hardware,qos,policy) information associated with 724 the performance metric data node tag."; 725 } 727 extension multi-source-tag { 728 argument tag; 729 description 730 "The argument 'tag' is of type 'tag'.The multi-source-tag can be 731 used to identify multiple source aggregation tye(e.g., line card, 732 member link in an aggregated Ethernet interface) related to performance 733 metric related data node or interface related to data node). 735 Two source aggregation source types are supported, one is aggregation 736 which groups data from two or multiple different data objects, 737 the other is membership which identify each data object(e.g., 738 linecard, member link from multiple source aggregation."; 739 } 741 augment "/tags:module-tags/tags:module" { 742 description 743 "Augment the Module Tags module with data node tag attributes"; 744 container data-object-tags { 745 description 746 "Contains the list of self explanation data nodes and their associated tags"; 747 list data-object { 748 key "object-name"; 749 description 750 "A list of self explanation nodes and their associated tags"; 751 leaf object-name { 752 type nacm:node-instance-identifier; 753 mandatory true; 754 description 755 "The YANG data node name."; 756 } 757 leaf-list tag { 758 type tags:tag; 759 description 760 "Tags associated with the data node within YANG module. See 761 the IANA 'YANG Data Node Tag Prefixes' registry for reserved 762 prefixes and the IANA'IETF YANG Data Node Tags' registry for 763 IETF tags. 765 The 'operational' state [RFC8342] view of this list is 766 constructed using the following steps: 768 1) System tags (i.e., tags of 'system' origin) are added. 770 2) User configured tags (i.e., tags of 'intended' origin) 771 are added. 772 3) Any tag that is equal to a masked-tag is removed."; 773 } 774 leaf-list masked-tag { 775 type tags:tag; 776 description 777 "The list of tags that should not be associated with the data 778 node within YANG module. The user can remove (mask) tags from the 779 operational state datastore [RFC8342] by adding them to 780 this list. It is not an error to add tags to this list 781 that are not associated with the data node within YANG module, 782 but they have no operational effect."; 783 } 784 } 785 } 786 } 787 } 789 791 6. Guidelines to Model Writers 793 This section updates [RFC8407]. 795 6.1. Define Standard Tags 797 A module MAY indicate, using node-tag extension statements, a set of 798 tags that are to be automatically associated with it (i.e., not added 799 through configuration). 801 module example-module-A { 802 //... 803 import ietf-data-node-tags { prefix ntags; } 804 container top { 805 ntags:opm-tag "ietf:object-type"; 806 list X { 807 leaf foo { 808 ntags:opm-tag "ietf:property"; 809 } 810 } 811 container Y { 812 ntags:opm-tag "ietf:metric"; 813 leaf bar { 814 ntags:statistics-operation "ietf:avg"; 815 ntags:metric-scale "ietf:milli"; 816 } 817 } 818 } 819 // ... 820 } 822 The module writer can use existing standard tags, or use new tags 823 defined in the model definition, as appropriate. For IETF 824 standardized modules new data node tags MUST be assigned in the IANA 825 registry defined below, see Section Section 7.2. 827 7. IANA Considerations 829 7.1. YANG Data Node Tag Prefixes Registry 831 IANA is asked to create a new registry "YANG Data Node Tag Prefixes" 832 grouped under a new "Protocol" category named "YANG Data Node Tag 833 Prefixes". 835 This registry allocates tag prefixes. All YANG data node tags SHOULD 836 begin with one of the prefixes in this registry. 838 Prefix entries in this registry should be short strings consisting of 839 lowercase ASCII alpha-numeric characters and a final ":" character. 841 The allocation policy for this registry is Specification Required 842 [RFC8126]. The Reference and Assignee values should be sufficient to 843 identify and contact the organization that has been allocated the 844 prefix. 846 The initial values for this registry are as follows. 848 +----------+----------------------------------+-----------+----------+ 849 | Prefix | Description | Reference | Assignee | 850 +----------+----------------------------------+-----------+----------+ 851 | ietf: | IETF Tags allocated in the IANA | [This | IETF | 852 | | IETF YANG Data Node Tags registry| document] | | 853 | | | | | 854 |vendor: | Non-registered tags allocated by | [This | IETF | 855 | | the module implementer. | document] | | 856 | | | | | 857 | user: | Non-registered tags allocated by | [This | IETF | 858 | | and for the user. | document] | | 859 +----------+----------------------------------+-----------+----------+ 861 Other standards organizations (SDOs) wishing to allocate their own 862 set of tags should allocate a prefix from this registry. 864 7.2. IETF YANG Data Node Tags Registry 866 IANA is asked to create four new registries "IETF YANG Data Node 867 Tags","IETF Metric Precision Tags","IETF Statistics Operation 868 Tags","Node Service Tag" grouped under a new "Protocol" category 869 "IETF YANG Data Node Tags". These four registries should be included 870 below "YANG Data Node Tag Prefixes" when listed on the same page. 872 Four registries allocate tags that have the registered prefix 873 "ietf:". New values should be well considered and not achievable 874 through a combination of already existing IETF tags. 876 The allocation policy for these four registries is IETF Review 877 [RFC8126]. 879 The initial values for these eight registries are as follows. 881 +----------------------------+--------------------------+-----------+ 882 | Data Node Tag | Description | Reference | 883 +----------------------------+--------------------------+-----------+ 884 | | | | 885 | ietf:object-type | Relates to object type | [This | 886 | | (e.g., interfaces). | document] | 887 | | | | 888 | ietf:metric | Relates to performance | [This | 889 | | metric info | document] | 890 | | (e.g., ifstatistics). | | 891 | | | | 892 | | | | 893 | ietf:property | Represents a object | [This | 894 | | property | document] | 895 | | (e.g.,ifindex). | | 896 +----------------------------+--------------------------+-----------+ 897 +----------------------------+--------------------------+-----------+ 898 | Metric Precision | Description | Reference | 899 +----------------------------+--------------------------+-----------+ 900 |ietf:minus-eight |Relates to metric precision [This | 901 | | of performance metric | document] | 902 | | | | 903 |ietf:minus-seven |Relates to metric precision [This | 904 | | of performance metric | document] | 905 | | | | 906 |ietf:minus-six |Relates to metric precision [This | 907 | | of performance metric | document] | 908 | | | | 909 |ietf:minus-five |Relates to metric precision [This | 910 | | of performance metric | document] | 911 | | | | 912 |ietf:minus-four |Relates to metric precision [This | 913 | | of performance metric | document] | 914 | | | | 915 |ietf:minus-three |Relates to metric precision [This | 916 | | of performance metric | document] | 917 | | | | 918 |ietf:minus-two |Relates to metric precision [This | 919 | | of performance metric | document] | 920 | | | | 921 |ietf:minus-one |Relates to metric precision [This | 922 | | of performance metric | document] | 923 | | | | 924 |ietf:zero |Relates to metric precision [This | 925 | | of performance metric | document] | 926 | | | | 927 |ietf:one |Relates to metric precision [This | 928 | | of performance metric | document] | 929 | | | | 930 |ietf:two |Relates to metric precision [This | 931 | | of performance metric | document] | 932 | | | | 933 |ietf:three |Relates to metric precision [This | 934 | | of performance metric | document] | 935 | | | | 936 |ietf:four | Relates to metric precision [This | 937 | | of performance metric | document] | 938 | | | | 939 |ietf:five | Relates to metric precision [This | 940 | | of performance metric | document] | 941 | | | | 942 |ietf:six | Relates to metric precision [This | 943 | | of performance metric | document] | 944 | | | | 945 |ietf:seven | Relates to metric precision [This | 946 | | of performance metric | document] | 947 | | | | 948 |ietf:eight | Relates to metric precision [This | 949 | | of performance metric | document] | 950 | | | | 951 |ietf:nine | Relates to metric precision [This | 952 | | of performance metric | document] | 953 +----------------------------+--------------------------+-----------+ 954 +----------------------------+--------------------------+-----------+ 955 | Metric scale | Description | Reference | 956 +----------------------------+--------------------------+-----------+ 957 |ietf:yocto | Relates to metric scale | [This | 958 | | of performance metric | document] | 959 | | | | 960 |ietf:zepto | Relates to metric scale | [This | 961 | | of performance metric | document] | 962 | | | | 963 |ietf:atto | Relates to metric scale | [This | 964 | | of performance metric | document] | 965 | | | | 966 |ietf: femto | Relates to metric scale | [This | 967 | | of performance metric | document] | 968 | | | | 969 |ietf: pico | Relates to metric scale | [This | 970 | | of performance metric | document] | 971 | | | | 972 |ietf: nano | Relates to metric scale | [This | 973 | | of performance metric | document] | 974 | | | | 975 |ietf: micro | Relates to metric scale | [This | 976 | | of performance metric | document] | 977 | | | | 978 |ietf: milli | Relates to metric scale | [This | 979 | | of performance metric | document] | 980 | | | | 981 |ietf: units | Relates to metric scale | [This | 982 | | of performance metric | document] | 983 | | | | 984 |ietf: kilo | Relates to metric scale | [This | 985 | | of performance metric | document] | 986 | | | | 987 |ietf: mega | Relates to metric scale | [This | 988 | | of performance metric | document] | 989 | | | | 990 |ietf: giga | Relates to metric scale | [This | 991 | | of performance metric | document] | 992 | | | | 993 |ietf: tera | Relates to metric scale | [This | 994 | | of performance metric | document] | 995 | | | | 996 |ietf: peta | Relates to metric scale | [This | 997 | | of performance metric | document] | 998 | | | | 999 |ietf: exa | Relates to metric scale | [This | 1000 | | of performance metric | document] | 1001 | | | | 1002 |ietf: zetta | Relates to metric scale | [This | 1003 | | of performance metric | document] | 1004 | | | | 1005 |ietf: yotta | Relates to metric scale | [This | 1006 | | of performance metric | document] | 1007 +----------------------------+--------------------------+-----------+ 1008 +----------------------------+--------------------------+-----------+ 1009 | Operation Type Tag | Description | Reference | 1010 +----------------------------+--------------------------+-----------+ 1011 |ietf:normal | Relates to statistics | [This | 1012 | | operation(e.g.,average, | document] | 1013 | | min, max, normal,etc) | | 1014 |ietf:avg | Relates to statistics | [This | 1015 | | operation(e.g.,average, | document] | 1016 | | min, max, sum,etc) | | 1017 |ietf:sum | Relates to statistics | [This | 1018 | | operation(e.g.,average, | document] | 1019 | | min, max, sum,etc) | | 1020 |ietf:min | Relates to statistics | [This | 1021 | | operation(e.g.,average, | document] | 1022 | | min, max, sum,etc) | | 1023 |ietf:max | Relates to statistics | [This | 1024 | | operation(e.g.,average, | document] | 1025 | | min, max, sum,etc) | | 1026 |ietf:threshold | Relates to statistics | [This | 1027 | | operation(e.g.,average, | document] | 1028 | | min, max, threshold,etc) | | 1029 +----------------------------+--------------------------+-----------+ 1030 +----------------------------+--------------------------+-----------+ 1031 | Metric Group Tag | Description | Reference | 1032 +----------------------------+--------------------------+-----------+ 1033 | ietf:delay | Represent metric group | [This | 1034 | |(e.g., loss, jitter,delay)| document] | 1035 | | | | 1036 | ietf:jitter | Represent metric group | [This | 1037 | |(e.g., loss, jitter,delay)| document] | 1038 | | | | 1039 | ietf:loss | Represent metric group | [This | 1040 | |(e.g., loss, jitter,delay)| document] | 1041 +----------------------------+--------------------------+-----------+ 1042 +----------------------------+--------------------------+-----------+ 1043 | Multiple Source Tag | Description | Reference | 1044 +----------------------------+--------------------------+-----------+ 1045 |ietf:member |Relates to multiple source| [This | 1046 | |aggregation type(e.g., | document] | 1047 | |lag, linecard, sub inf) | | 1048 | | | | 1049 |ietf:agg |Relates to multiple source| [This | 1050 | |aggregation type(e.g.,agg)| document] | 1051 +----------------------------+--------------------------+-----------+ 1052 +----------------------------+--------------------------+-----------+ 1053 | Data Source Tag | Description | Reference | 1054 +----------------------------+--------------------------+-----------+ 1055 | | | | 1056 | ietf:service-flow | Relates to data source | [This | 1057 | | type(e.g., microburst). | document] | 1058 | | | | 1059 | ietf:topo | Relates to data source | [This | 1060 | | type(e.g., topology). | document] | 1061 | | | | 1062 | ietf:resource | Relates to data source | [This | 1063 | | type info | document] | 1064 | | (e.g., interface,queue). | | 1065 | | | | 1066 | ietf:policy | Relates to data source | [This | 1067 | | type info | document] | 1068 | |(e.g., acl, routing policy| | 1069 | | | | 1070 | ietf:hardware | Relates to data source | [This | 1071 | | type | document] | 1072 | | (e.g.,optical module). | | 1073 +----------------------------+--------------------------+-----------+ 1074 +----------------------------+--------------------------+-----------+ 1075 | Service Tag | Description | Reference | 1076 +----------------------------+--------------------------+-----------+ 1077 |ietf:l3vpn | Relates to service | [This | 1078 | | offering(e.g.,l3vpn | document] | 1079 | | l2vpn,tunnel,etc) | | 1080 |ietf:l2vpn | Relates to service | [This | 1081 | | offering(e.g.,l3vpn | document] | 1082 | | l2vpn,tunnel,etc) | | 1083 |ietf:te-tunnel | Relates to service | [This | 1084 | | offering(e.g.,l3vpn | document] | 1085 | | l2vpn,tunnel,etc) | | 1086 +----------------------------+--------------------------+-----------+ 1087 +----------------------------+--------------------------+-----------+ 1088 | Task Tag | Description | Reference | 1089 +----------------------------+--------------------------+-----------+ 1090 |ietf:vpn-diag | Relates to vpn serivce | [This | 1091 | | diagonostic function | document] | 1092 | | | | 1093 |ietf:vpn-fullfilment | Relates to vpn service | [This | 1094 | | fullfillment function | document] | 1095 | | | | 1096 |ietf:vpn-assurance | Relates to vpn service | [This | 1097 | | assurance function | document] | 1098 +----------------------------+--------------------------+-----------+ 1100 7.3. Updates to the IETF XML Registry 1102 This document registers a URI in the "IETF XML Registry" [RFC3688]. 1103 Following the format in [RFC3688], the following registration has 1104 been made: 1106 URI: 1107 urn:ietf:params:xml:ns:yang:ietf-self-explaination-object-tags 1108 Registrant Contact: 1109 The IESG. 1110 XML: 1111 N/A; the requested URI is an XML namespace. 1113 7.4. Updates to the YANG Module Names Registry 1115 This document registers one YANG module in the "YANG Module Names" 1116 registry [RFC6020]. Following the format in [RFC6020], the following 1117 registration has been made: 1119 name: 1120 ietf-self-explaination-object-tags 1121 namespace: 1122 urn:ietf:params:xml:ns:yang:ietf-self-explaination-object-tags 1123 prefix: 1124 ntags 1125 reference: 1126 RFC XXXX (RFC Ed.: replace XXX with actual RFC number and remove 1127 this note.) 1129 8. Security Considerations 1131 The YANG module defined in this memo is designed to be accessed via 1132 the NETCONF protocol [RFC6241]. The lowest NETCONF layer is the 1133 secure transport layer and the mandatory-to-implement secure 1134 transport is SSH [RFC6242]. 1136 This document adds the ability to associate data node tag meta-data 1137 with YANG modules. This document does not define any actions based 1138 on these associations, and none are yet defined, and therefore it 1139 does not by itself introduce any new security considerations. 1141 Users of the data node tag-meta data may define various actions to be 1142 taken based on the data node tag meta-data. These actions and their 1143 definitions are outside the scope of this document. Users will need 1144 to consider the security implications of any actions they choose to 1145 define. 1147 9. Contributors 1149 The authors would like to thank Ran Tao for his major contributions 1150 to the initial modeling and use cases. 1152 10. References 1154 10.1. Normative References 1156 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1157 Requirement Levels", BCP 14, RFC 2119, 1158 DOI 10.17487/RFC2119, March 1997, 1159 . 1161 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1162 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1163 . 1165 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 1166 Writing an IANA Considerations Section in RFCs", BCP 26, 1167 RFC 8126, DOI 10.17487/RFC8126, June 2017, 1168 . 1170 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1171 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1172 May 2017, . 1174 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1175 and R. Wilton, "Network Management Datastore Architecture 1176 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 1177 . 1179 [RFC8407] Bierman, A., "Guidelines for Authors and Reviewers of 1180 Documents Containing YANG Data Models", BCP 216, RFC 8407, 1181 DOI 10.17487/RFC8407, October 2018, 1182 . 1184 10.2. Informative References 1186 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1187 DOI 10.17487/RFC3688, January 2004, 1188 . 1190 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1191 the Network Configuration Protocol (NETCONF)", RFC 6020, 1192 DOI 10.17487/RFC6020, October 2010, 1193 . 1195 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1196 and A. Bierman, Ed., "Network Configuration Protocol 1197 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1198 . 1200 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 1201 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 1202 . 1204 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 1205 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 1206 . 1208 Appendix A. NETCONF Example 1210 The following is a fictional NETCONF example result from a query of 1211 the data object tags list. For the sake of brevity only a few module 1212 results are imagined. 1214 1215 1216 1217 ietf-interfaces 1218 1219 1220 1221 /if:interfaces/if:interface/if:statistics/if:in-errors 1222 1223 ietf:metric 1224 ietf:avg 1225 1226 1227 /if:interfaces/if:interface/if:last-change 1228 ietf:property 1229 1230 1231 /if:interfaces/if:interface/if:type 1232 ietf:object-type 1233 1234 1235 1236 1237 ietf-ip 1238 1239 1240 /if:interfaces/if:interface/ip:ipv4/ip:mtu 1241 ietf:metric 1242 ietf:normal 1243 1244 1245 /if:interfaces/if:interface/ip:ipv4/ip:enable 1246 ietf:property 1247 1248 1249 /if:interfaces/if:interface/ip:ipv4 1250 ietf:object-type 1251 1252 1253 1254 1255 1257 Appendix B. Non-NMDA State Module 1259 As per [RFC8407] the following is a non-NMDA module to support 1260 viewing the operational state for non-NMDA compliant servers. 1262 file "ietf-data-object-tags-state@2019-05-03.yang" 1263 module ietf-data-object-tags-state { 1264 yang-version 1.1; 1265 namespace "urn:ietf:params:xml:ns:yang:ietf-data-object-tags"; 1266 prefix ntags; 1268 import ietf-netconf-acm { 1269 prefix nacm; 1270 } 1271 import ietf-module-tags { 1272 prefix tags; 1273 } 1275 organization 1276 "IETF NetMod Working Group (NetMod)"; 1277 contact 1278 "WG Web: 1279 WG List: 1280 Editor: Qin Wu 1281 Editor: Benoit Claise 1282 Editor: Liang Geng 1283 Editor: Zongpeng Du "; 1284 description 1285 "This module describes a mechanism associating self-explanation 1286 tags with YANG data node within YANG modules. Tags may be IANA 1287 assigned or privately defined. 1289 Copyright (c) 2020 IETF Trust and the persons identified as 1290 authors of the code. All rights reserved. 1292 Redistribution and use in source and binary forms, with or 1293 without modification, is permitted pursuant to, and subject to 1294 the license terms contained in, the Simplified BSD License set 1295 forth in Section 4.c of the IETF Trust's Legal Provisions 1296 Relating to IETF Documents 1297 (https://trustee.ietf.org/license-info). 1299 This version of this YANG module is part of RFC XXXX 1300 (https://tools.ietf.org/html/rfcXXXX); see the RFC itself for 1301 full legal notices."; 1303 revision 2019-05-03 { 1304 description 1305 "Initial revision."; 1306 reference 1307 "RFC XXXX: YANG Data Node Tags"; 1308 } 1309 typedef metric-precision { 1310 type int8 { 1311 range "-8 .. 9"; 1312 } 1313 description 1314 "A node using this data type represents a sensor value 1315 precision range. 1317 A node of this type SHOULD be defined together with nodes of 1318 type measurement-units and type measurement-scale. Together, 1319 associated nodes of these three types are used to identify the 1320 semantics of a node of type sensor-value. 1322 If a node of this type contains a value in the range 1 to 9, 1323 it represents the number of decimal places in the fractional 1324 part of an associated sensor-value fixed-point number. 1325 If a node of this type contains a value in the range -8 to -1, 1326 it represents the number of accurate digits in the associated 1327 sensor-value fixed-point number. 1329 The value zero indicates the associated sensor-value node is 1330 not a fixed-point number. 1332 Server implementers must choose a value for the associated 1333 sensor-value-precision node so that the precision and accuracy 1334 of the associated sensor-value node is correctly indicated. 1336 For example, a component representing a temperature sensor 1337 that can measure 0 to 100 degrees C in 0.1 degree 1338 increments, +/- 0.05 degrees, would have a 1339 sensor-value-precision value of '1', a sensor-value-scale 1340 value of 'units', and a sensor-value ranging from '0' to 1341 '1000'. The sensor-value would be interpreted as 1342 'degrees C * 10'."; 1343 reference 1344 "RFC 3433: Entity Sensor Management Information Base - 1345 EntitySensorPrecision"; 1346 } 1348 typedef metric-scale { 1349 type enumeration { 1350 enum yocto { 1351 value 1; 1352 description 1353 "Measurement scaling factor of 10^-24."; 1354 } 1355 enum zepto { 1356 value 2; 1357 description 1358 "Measurement scaling factor of 10^-21."; 1359 } 1360 enum atto { 1361 value 3; 1362 description 1363 "Measurement scaling factor of 10^-18."; 1364 } 1365 enum femto { 1366 value 4; 1367 description 1368 "Measurement scaling factor of 10^-15."; 1369 } 1370 enum pico { 1371 value 5; 1372 description 1373 "Measurement scaling factor of 10^-12."; 1374 } 1375 enum nano { 1376 value 6; 1377 description 1378 "Measurement scaling factor of 10^-9."; 1379 } 1380 enum micro { 1381 value 7; 1382 description 1383 "Measurement scaling factor of 10^-6."; 1384 } 1385 enum milli { 1386 value 8; 1387 description 1388 "Measurement scaling factor of 10^-3."; 1389 } 1390 enum units { 1391 value 9; 1392 description 1393 "Measurement scaling factor of 10^0."; 1394 } 1395 enum kilo { 1396 value 10; 1397 description 1398 "Measurement scaling factor of 10^3."; 1399 } 1400 enum mega { 1401 value 11; 1402 description 1403 "Measurement scaling factor of 10^6."; 1404 } 1405 enum giga { 1406 value 12; 1407 description 1408 "Measurement scaling factor of 10^9."; 1409 } 1410 enum tera { 1411 value 13; 1412 description 1413 "Measurement scaling factor of 10^12."; 1414 } 1415 enum peta { 1416 value 14; 1417 description 1418 "Measurement scaling factor of 10^15."; 1419 } 1420 enum exa { 1421 value 15; 1422 description 1423 "Measurement scaling factor of 10^18."; 1424 } 1425 enum zetta { 1426 value 16; 1427 description 1428 "Measurement scaling factor of 10^21."; 1429 } 1430 enum yotta { 1431 value 17; 1432 description 1433 "Measurement scaling factor of 10^24."; 1434 } 1435 } 1436 description 1437 "A node using this data type represents a data scaling factor, 1438 represented with an International System of Units (SI) prefix. 1439 The actual data units are determined by examining a node of 1440 this type together with the associated sensor-value-type. 1442 A node of this type SHOULD be defined together with nodes of 1443 type sensor-value-type and type sensor-value-precision. 1444 Together, associated nodes of these three types are used to 1445 identify the semantics of a node of type sensor-value."; 1446 reference 1447 "RFC 3433: Entity Sensor Management Information Base - 1448 EntitySensorDataScale"; 1449 } 1451 extension opm-tag { 1452 argument tag; 1453 description 1454 "The argument 'tag' is of type 'tag'. This extension statement 1455 is used by module authors to indicate the opm tags that SHOULD be 1456 added automatically by the system. Opm Tag is used to classify 1457 operation and management data into object type, property, metric 1458 group and metric. As such the origin of the value for the 1459 pre-defined tags should be 1460 set to 'system'[RFC8342]."; 1461 } 1463 extension metric-scale { 1464 argument tag; 1465 description 1466 "The argument 'tag' is of type 'tag'. The metric-scale tag can be 1467 used to provide an additional data scale factor(e.g., Measurement 1468 scaling factor of 10^0, 10^-3,10^3) information associated with 1469 the performance metric data object. 1471 A node using metric scale tag SHOULD be defined together with nodes of 1472 type metric unit and type metric precision. 1473 Together, associated nodes of these three types are used to 1474 identify the semantics of the performance metric data object."; 1475 reference 1476 "RFC 3433: Entity Sensor Management Information Base - 1477 EntitySensorDataScale"; 1478 } 1480 extension metric-precision { 1481 argument tag; 1482 description 1483 "The argument 'tag' is of type 'tag'. The metric-precision can be 1484 used to provide an additional sensor value precision range (e.g., 1485 the range -8 to -1, 0, the range 1 to 9) information associated 1486 with the performance metric data object. 1488 A node using metric precision tag SHOULD be defined together with 1489 nodes of type metric unit and type metric scale. Together, associated 1490 nodes of these three types are used to identify the semantics of the 1491 performance metric data object. 1493 If a node of this type contains a value in the range 1 to 9, 1494 it represents the number of decimal places in the fractional 1495 part of an associated sensor-value fixed-point number. 1496 If a node of this type contains a value in the range -8 to -1, 1497 it represents the number of accurate digits in the associated 1498 sensor-value fixed-point number. 1500 The value zero indicates the associated sensor-value node is 1501 not a fixed-point number. 1503 Server implementers must choose a value for the associated 1504 metric precision tag so that the precision and accuracy 1505 of the associated sensor-value node is correctly indicated. 1507 For example, a component representing a temperature sensor 1508 that can measure 0 to 100 degrees C in 0.1 degree 1509 increments, +/- 0.05 degrees, would have a 1510 sensor-value-precision value of '1', a sensor-value-scale 1511 value of 'units', and a sensor-value ranging from '0' to 1512 '1000'. The sensor-value would be interpreted as 1513 'degrees C * 10'."; 1514 reference 1515 "RFC 3433: Entity Sensor Management Information Base - 1516 EntitySensorDataScale"; 1517 } 1519 extension operation-type { 1520 argument tag; 1521 description 1522 "The argument 'tag' is of type 'tag'.The statistics-operation can be 1523 used to provide an additional statistics operation type(e.g., sum, 1524 min, max,sum,last, threshold) information associated with the performance metric 1525 data object. 1527 If the operation type is threshold type, the corresponding 1528 data object support threshold handling,e.g.,scan all interfaces 1529 for a certain type every 5 seconds and check the counters or 1530 status to cross threshold, return an array of interface entries 1531 that match the search. 1533 If the operation type is average,min,max,sum,last, 1534 it indicate the data object supports statistics operation, e.g., 1535 scan all interfaces for a certain type every 5 seconds up to 60 seconds, 1536 only return min, average, max, sum value of specific data object rather than 1537 the values that are current at the end of 60 seconds."; 1538 } 1540 extension service-tag { 1541 argument tag; 1542 description 1543 "The argument 'tag' is of type 'tag'.The service-tag can be 1544 used to provide a service classification information (e.g., tunnel, 1545 l3vpn,l2vpn) information associated with YANG data node."; 1546 } 1548 extension task-tag { 1549 argument tag; 1550 description 1551 "The argument 'tag' is of type 'tag'.The task-tag can be 1552 used to provide a task classification information (e.g., fault management, 1553 performance measurement) information associated with YANG data node."; 1554 } 1556 extension data-source { 1557 argument tag; 1558 description 1559 "The argument 'tag' is of type 'tag'.The data-source-type can be 1560 used to provide an additional data source type (e.g., connectivity, 1561 resource, hardware,qos,policy) information associated with 1562 the performance metric data node tag."; 1563 } 1565 extension multi-source-tag { 1566 argument tag; 1567 description 1568 "The argument 'tag' is of type 'tag'.The multi-source-tag can be 1569 used to identify multiple source aggregation tye(e.g., line card, 1570 member link in an aggregated Ethernet interface) related to performance 1571 metric related data node or interface related to data node). 1573 Two source aggregation source types are supported, one is aggregation 1574 which groups data from two or multiple different data objects, 1575 the other is membership which identify each data object(e.g., 1576 linecard, member link from multiple source aggregation."; 1577 } 1579 augment "/tags:module-tags/tags:module" { 1580 description 1581 "Augment the Module Tags module with data node tag attributes"; 1582 container data-object-tags { 1583 config false; 1584 status deprecated; 1585 description 1586 "Contains the list of self explanation data nodes and their associated tags"; 1587 list data-object { 1588 key "object-name"; 1589 status deprecated; 1590 description 1591 "A list of self explanation nodes and their associated tags"; 1592 leaf object-name { 1593 type nacm:node-instance-identifier; 1594 mandatory true; 1595 status deprecated; 1596 description 1597 "The YANG data node name."; 1598 } 1599 leaf-list tag { 1600 type tags:tag; 1601 status deprecated; 1602 description 1603 "Tags associated with the data node within YANG module. See 1604 the IANA 'YANG Data Node Tag Prefixes' registry for reserved 1605 prefixes and the IANA'IETF YANG Data Node Tags' registry for 1606 IETF tags. 1608 The 'operational' state [RFC8342] view of this list is 1609 constructed using the following steps: 1611 1) System tags (i.e., tags of 'system' origin) are added. 1612 2) User configured tags (i.e., tags of 'intended' origin) 1613 are added. 1614 3) Any tag that is equal to a masked-tag is removed."; 1615 } 1616 leaf-list masked-tag { 1617 type tags:tag; 1618 status deprecated; 1619 description 1620 "The list of tags that should not be associated with the data 1621 node within YANG module. The user can remove (mask) tags from the 1622 operational state datastore [RFC8342] by adding them to 1623 this list. It is not an error to add tags to this list 1624 that are not associated with the data node within YANG module, 1625 but they have no operational effect."; 1626 } 1627 } 1628 } 1629 } 1630 } 1631 1633 Appendix C. Targeted data object subscription example 1635 The following subsections provides targeted data object subscription 1636 example.The subscription "id" values of 22 used below is just an 1637 example. In production, the actual values of "id" might not be small 1638 integers. 1640 +-----------+ +-----------+ 1641 | Subscriber| | Publisher | 1642 +------+----+ +-----+-----+ 1643 | | 1644 | | 1645 |Telemery data Tagging Advertisement 1646 | (node-selector, opm-tag = metric) 1647 |<---------------------------------| 1648 | | 1649 | establish-subscription | 1650 | (datasore,node-selector) | 1651 |--------------------------------->| 1652 | | 1653 | | 1654 | | 1655 | RPC Reply: OK, id = 22 | 1656 |<---------------------------------| 1657 | | 1658 | | 1659 | | 1660 | Notification Message (for 22) | 1661 | <--------------------------------| 1662 | | 1663 | | 1664 | | 1666 The publisher advertise telemetry data node capability to the 1667 subscriber to instruct the receiver to subscribe targeted data object 1668 with specific characteristics (e.g., performance metric related data 1669 object) and specific data path corresponding to the targeted data 1670 object. 1672 The following XML example [W3C.REC-xml-20081126] illustrates the 1673 advertisment of the list of available target objects: 1675 1676 1678 acme-router-notification-capabilities 1679 1680 ietf-system-capabilities@2020-03-23 1681 ietf-notification-capabilities@2020-03-23 1682 ietf-data-export-capabilities@2020-03-23 1683 1684 1685 Defines the notification capabilities of an acme-router. 1686 The router only has running, and operational datastores. 1687 Every change can be reported on-change from running, but 1688 only config=true nodes and some config=false data from operational. 1689 Statistics are not reported based on timer based trigger and counter 1690 threshold based trigger. 1691 1692 1693 1698 1699 ds:operational 1700 1701 \ 1702 /if:interfaces/if:interface/if:statistics/if:in-errors\ 1703 1704 1705 counter 1706 metric 1707 avg 1708 1709 1710 1711 1712 1713 1715 With telemetry data tagging information carried in the Telemetry data 1716 Tagging Advertisement, the subscriber identifies targeted data object 1717 and associated data path to the datastore node and sends a establish- 1718 subscription RPC to subscribe specific data objects that are 1719 interests to the client application from the publisher. 1721 1723 1726 1728 ds:operational 1729 1730 1732 /if:interfaces/if:interface/if:statistics/if:in-errors 1733 1734 1735 500 1736 1737 1738 1740 The publisher returns specific object type of operational state 1741 related to the subscriber. 1743 Authors' Addresses 1745 Qin Wu 1746 Huawei 1747 101 Software Avenue, Yuhua District 1748 Nanjing, Jiangsu 210012 1749 China 1751 Email: bill.wu@huawei.com 1753 Benoit Claise 1754 Cisco 1755 De Kleetlaan 6a b1 1756 Diegem 1831 1757 Belgium 1759 Email: bclaise@cisco.com 1761 Liang Geng 1762 China Mobile 1763 32 Xuanwumen West St, Xicheng District 1764 Beijing 10053 1766 Email: gengliang@chinamobile.com 1767 Zongpeng Du 1768 China Mobile 1769 32 Xuanwumen West St, Xicheng District 1770 Beijing 10053 1772 Email: duzongpeng@chinamobile.com