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