Path Energy Traffic Ratio API (PETRA)

Path Energy Traffic Ratio API (PETRA) Cisco

Barcelona Spain natal@cisco.com

Telefonica

Madrid Spain luismiguel.contrerasmurillo@telefonica.com

Independent Consultant

Spain marisol.ietf@gmail.com

All For Eco

jan.lindblad+ietf@for.eco

T-SYSTEMS

Madrid Spain ADRIAN.GALLEGO-SANCHEZ@t-systems.com

IETF GREEN energy, network, underlay This document describes an API to query a network regarding its Energy Traffic Ratio for a given path.

Energy management is becoming one of the major societal goals for the next decade, and networks are one of the major consumers of energy nowadays. Energy management of network services is thus one of the forefronts of innovation and action from network service stakeholders, involving manufacturers, operators and customers. In this line, there is a shared goal of achieving better energy awareness. As with any other network metric, the energy traffic ratio could be collected from the underlying network infrastructure. However, there is not a common or single definition of energy metrics towards network consumers so that can be uniformly reported, particularly in heterogeneous network scenarios. This document introduces an API to query networks about Energy Traffic Ratio.

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

This documents describes an API to query a network about the Energy Traffic Ratio for a given path. It takes as input the source and destination of a path along with the traffic throughput between and returns energy information related to the traffic on the path. This is energy computed by the infrastructure that is dynamically part of the traffic path. The API is agnostic to the actual hops and underlaying infrastructure that enables a path, which might change transparently to the API. This document only describes the API, the computation of the energy information to return is out of the scope of this document. In the current version of this document, source and destination endpoints can be IP addresses, IP prefixes, or MAC addresses.

This API allows to return a number of energy attributes associated with the path and the traffic. Currently the parameters that could be returned as energy information as part of the query are:

Watts per Gigabit: How many Watts are consumed per Gigabit of traffic traversing the path.

The API is envisioned in such a way that could be used recursively. That means, subpaths could report their energy consumption using PETRA and such energy consumption could be aggregated and reported for the overall path also using PETRA. Similarly, this API could be (recursively) used to provide energy information according to the definition of Service Models in an SDN context as described in . In that case, using Figure 3 in as reference (below), PETRA could be used between the Controller(s) and the Network Orchestrator(s), between the Network Orchestrator(s) and the Service Orchestrator, and between the Service Orchestrator and the Customer(s).

| Customer | Customer Service | Orchestrator | (a) | | related API | | ---------- ------------------ . . ########################## . . (b) ----------- . (b) . ......|Application| . . : | BSS/OSS | PETRA as . . : ----------- Service related API . Service Delivery . : . Model . : ------------------ ------------------ | | | | ############# | Network | | Network | | Orchestrator | | Orchestrator | | | | | .------------------ ------------------. PETRA as . : : . Network API . : Network Configuration : . . : Model : . ------------ ------------ ------------ ------------ | | | | | | | | ### | Controller | | Controller | | Controller | | Controller | | | | | | | | | ------------ ------------ ------------ ------------ : . . : : : . . Device : : : . . Configuration : : : . . Model : : --------- --------- --------- --------- --------- | Network | | Network | | Network | | Network | | Network | | Element | | Element | | Element | | Element | | Element | --------- --------- --------- --------- --------- ]]> While considering recursive usage, the aspect of double-counting shall also be taken into consideration. Double counting refers to the fact of counting more than once the same energy consumed. Organizations using PETRA in a recursive manner need to take appropriate measures to ensure no double-counting occurs across recursive calls to the API.

This is a posible definition of PETRA as a module following the YANG specification . The module uses the common YANG data types defined in , and imports the network slice model from and the power and energy model from .

This section uses the graphical representation of data models defined in .

file "ietf-petra@2026-07-06.yang" module ietf-petra { yang-version 1.1; namespace "urn:ietf:params:xml:ns:yang:ietf-petra"; prefix petra; import ietf-inet-types { prefix ietf-inet-types; reference "RFC 9911: Common YANG Data Types"; } import ietf-yang-types { prefix ietf-yang-types; reference "RFC 9911: Common YANG Data Types"; } import ietf-network-slice-service { prefix ietf-nss; revision-date 2026-05-27; reference "draft-ietf-teas-ietf-network-slice-nbi-yang-26: A YANG Data Model for the RFC 9543 Network Slice Service."; } import ietf-power-and-energy { prefix eo; reference "draft-bcmj-green-power-and-energy-yang: Power and Energy YANG Module."; } organization "IETF GREEN Working Group"; contact "WG Web: WG List: "; description "Initial YANG rendition of the PETRA Energy API, v1.0.1 Copyright (c) 2025 IETF Trust and the persons identified as authors of the code. All rights reserved. Redistribution and use in source and binary forms, with or without modification, is permitted pursuant to, and subject to the license terms contained in, the Revised BSD License set forth in Section 4.c of the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info). This version of this YANG module is part of RFC XXXX (https://www.rfc-editor.org/info/rfcXXXX); see the RFC itself for full legal notices. The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document are to be interpreted as described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, they appear in all capitals, as shown here. "; /* If you have an implementation of this YANG module, you could access it like something this over RESTCONF: $ curl --location --request POST \ 'https://localhost:8008/restconf/operations/ietf-petra:energy/query' \ --header 'Content-Type: application/yang-data+json' \ --user 'admin:admin' \ --data-raw '{ 'input' : { 'source': { 'ip-prefix': '10.10.10.0/24' }, 'destination': { 'ip-prefix': '10.20.20.0/24' }, 'throughput': '40' } }' And if all goes well, you might receive (besides all the HTTP headers) a reply body with something like this: { 'output': { 'success': { 'watts-per-gigabit': '191.855' } } } */ revision 2026-07-06 { description "Initial YANG rendition of the PETRA Energy API, v1.0.1"; reference "RFC XXXX: ..."; } grouping endpoint { description "Identifies one endpoint of an energy-measurement path."; choice identifier { mandatory true; description "Endpoint represented as an IP address, IP prefix, MAC address, or Service Demarcation Point (SDP) identifier."; case ip-address { leaf ip-address { type ietf-inet-types:ip-address; mandatory true; description "IPv4 or IPv6 address."; } } case ip-prefix { leaf ip-prefix { type ietf-inet-types:ip-prefix; mandatory true; description "IPv4 or IPv6 network prefix."; } } case mac-address { leaf mac-address { type ietf-yang-types:mac-address; mandatory true; description "IEEE 802 MAC address."; } } case sdp-id { leaf sdp-id { type leafref { path "/ietf-nss:network-slice-services" + "/ietf-nss:slice-service" + "/ietf-nss:sdps" + "/ietf-nss:sdp" + "/ietf-nss:id"; require-instance true; } mandatory true; description "Reference to a Service Demarcation Point (SDP) within the scope of a Network Slice Controller (NSC)."; } } } } grouping energy-metrics { description "Grouping for query result metrics."; leaf watts-per-gigabit { type decimal64 { fraction-digits 3; } units W/Gb; description "Watts consumed per Gigabit transmitted"; } leaf data-source-accuracy { type identityref { base eo:data-source-accuracy; } description "Accuracy classification of the watts-per-gigabit value, using the GREEN data-source-accuracy hierarchy. Implementations SHOULD populate this leaf to enable consumers to assess reliability. For path-aggregated values derived from multiple components, the RECOMMENDED value is the LEAST accurate accuracy class among all contributing energy objects."; } } container energy { description "PETRA API top level container."; action query { description "Query the network for energy consumption"; input { must "throughput or (time-window/start-time and time-window/end-time and data-transmitted)" { error-message "Provide either throughput or a time window with start and end times together with data-transmitted."; } container source { description "Source endpoint."; uses endpoint; } container destination { description "Destination endpoint."; uses endpoint; } choice traffic-characterization { default throughput; description "Characterizes the traffic either by its throughput or by the amount of data transmitted during a time window."; case throughput { leaf throughput { type decimal64 { fraction-digits 3; } units Gb/s; description "Throughput between source and destination (in gigabits per second)."; } } case time-window-and-data-transmitted { container time-window { description "Interval during which the data was transmitted."; leaf start-time { type ietf-yang-types:date-and-time; mandatory true; description "Start date and time of the interval."; } leaf end-time { type ietf-yang-types:date-and-time; mandatory true; description "End date and time of the interval."; } } leaf data-transmitted { type decimal64 { fraction-digits 3; } units Gb; mandatory true; description "Amount of data transmitted between source and destination during the time window (in gigabits)."; } } } } output { choice result { description "Choice of which kind of result the query gave."; container success { description "Successful operation"; uses energy-metrics; } container invalid-endpoint { presence "Indicates that an invalid endpoint was supplied."; description "Invalid source or destination endpoint supplied."; } } } } } } ]]>




    
      This section highlights deployment and operations considerations for PETRA, following the
        guidance in .

      
        Measurement method impact: PETRA results can differ depending on whether values are
          directly measured, estimated, or model-derived. Operators SHOULD document the
          methodology used for each exposed metric.
        Provenance: PETRA does not require provenance support. Deployments that require
          provenance assurance for the Energy Object telemetry used to derive a PETRA result can use
          the per-Energy-Object verification state defined in .
        Consumer intent differences: customer-facing use cases (for example, SD-WAN visibility
          and SLA reporting) prioritize repeatability and explainability, while operator
          optimization use cases may prioritize freshness and control-loop responsiveness.
        Recursive aggregation and double counting: recursive or multi-domain use of PETRA can
          count the same contribution more than once. Implementations SHOULD define aggregation
          boundaries and controls that avoid double counting across segments and administrative
          domains.
      
    


    
      The YANG module defined in this document is specified and reviewed following the
        guidance in . PETRA query exchanges can reveal operationally
        sensitive information related to endpoints, traffic, and energy behavior, and therefore
        require careful deployment controls.

      When this API is exposed over NETCONF  or RESTCONF , implementations inherit those protocols' security properties and
        deployment requirements.

      The Network Configuration Access Control Model (NACM)  provides
        the means to restrict access for particular NETCONF or RESTCONF users to a preconfigured
        subset of all available protocol operations and content.

      The module defines no particularly sensitive readable or writable datastore nodes. The
        "energy" container serves only as the parent of the "energy/query" action.

      Implementations and deployments SHOULD consider at least the following:

      
        Secure transport: mutual authentication, confidentiality, and integrity protection for PETRA exchanges MUST be
          provided by the underlying management protocol and transport.
        Authentication and authorization: servers MUST authenticate clients and MUST enforce
          authorization before processing requests. In particular, invocation of the
          "energy/query" action MUST be limited to authorized users.
        Input validation: implementations SHOULD validate endpoint identifiers and traffic
          characterization values to prevent invalid requests and abusive workloads.
        Information disclosure control: an "energy/query" request contains source and
          destination identifiers plus throughput or time-and-volume traffic information. A
          response can expose energy metrics, their accuracy, or whether the supplied endpoints are
          valid. Unauthorized invocation or observation can therefore disclose customer traffic and
          operational energy information or enable endpoint enumeration. Queries SHOULD be filtered according to policy and client privileges.
        Denial-of-service resilience: repeated or computationally expensive invocations of
          "energy/query" can consume controller or orchestrator resources. Implementations SHOULD
          apply rate limiting, quotas, and/or bounded processing.
        Privacy: where measurements can be correlated to customer behavior, operators SHOULD
          minimize retention and protect logs and telemetry generated by queries.
      

    

    
      Kudos to Elis Lulja for his help with the OpenAPI specification in early versions of this
        draft. Thanks to Fernando Sanz Garcia and Lori Jakab for their help and support on this
        work. 

        The contribution of Telefonica to this document has been supported by the Smart Networks and Services Joint Undertaking (SNS JU) under the European Union's Horizon Europe research and innovation projects 6Green (Grant Agreement no. 101096925) and Exigence (Grant Agreement no. 101139120). The contribution of A. Gallego Sánchez to this document has been partially supported by the Smart Networks and Services Joint Undertaking (SNS JU) under the European Union's Horizon Europe research and innovation project Sustain6G (Grant Agreement no. 101191936).
    

    

      IANA is requested to register the following URI in the "ns" registry within the "IETF XML Registry" group :

      URI: urn:ietf:params:xml:ns:yang:ietf-petra
      Registrant Contact: The IESG
      XML: N/A; the requested URI is an XML namespace.

      IANA is requested to register the following YANG module in the "YANG Module Names" registry  within the "YANG Parameters" registry group:

      Name: ietf-petra
      Maintained by IANA? N
      Namespace: urn:ietf:params:xml:ns:yang:ietf-petra
      Prefix: petra
      Reference: RFC XXXX



  

    

      &RFC2119;

      &RFC3688;

      &RFC7950;

      &RFC6241;

      &RFC6242;

      &RFC9911;

      &RFC8040;

      &RFC8174;

      &RFC8309;

      &RFC8340;

      &RFC8341;

      &I-D.belmq-green-framework;

      &I-D.ietf-teas-ietf-network-slice-nbi-yang;

      &I-D.bcmj-green-power-and-energy-yang;

    

    

      &RFC9907;

      &I-D.ietf-opsawg-rfc5706bis;

      &I-D.madpr-green-provenance;

    

    
      This section describes some use-cases where this specification might be useful. 

      
        Software-Defined Wide-Area Networks (SD-WAN) have become a common way for enterprises to provide cost-effective connectivity across their different geographically distributed sites. Typically, SD-WAN deployments operate as an overlay network that is established on top of an existing underlay connectivity network. One aspect to consider is that in many SD-WAN production deployments the operator of the overlay network and the operator of the underlay network are different organizations.

        This poses an additional challenge when trying to derive energy metrics. Even if the underlay network is instrumented to collect energy data, this data is opaque to the operator of the overlay network which has no access to underlay information. While operators of underlay networks offer certain general network metrics to overlay operators, no interface has been defined to allow the overlay operator to query the underlay network for energy information.

        In this context, the PETRA specification presented in this document enables the operator of the SD-WAN network to coordinate with the underlay operator to capture energy data. This in turns opens further use-cases, from observability and reporting to potentially overlay policies based on underlay energy data, further enabling an overall more energy-efficient operation of the network.

        In addition to energy considerations in SD-WAN deployments, PETRA can also be leveraged for broader energy-aware service routing. In this context, network controllers and service orchestrators, such as SD-WAN controllers, transport SDN controllers, 5G slice orchestrators, or multi-domain service orchestrators, can use PETRA metrics not only to balance latency, throughput, or load, but also to optimize path selection according to energy-efficiency objectives. For example, paths with the lowest energy-consumption could be preferred, enabling service differentiation where energy-efficient paths are explicitly prioritized. This extends the SD-WAN use case into a more general paradigm where routing decisions are jointly driven by network performance and energy impact.
      

      
        The concept of multilayer L3-L1 collection involves integrating data from different network layers to provide a comprehensive view of network operations. The use case of multilayer involves collecting and correlating data from Layer 3 (network layer) down to Layer 1 (physical layer). This multilayer approach allows for better network performance, optimization, and troubleshooting by providing end-to-end visibility.

        Leveraging PETRA API for multilayer L3-L1 collection use case enhances energy management by providing comprehensive visibility, enabling optimization, and supporting proactive management. This makes PETRA a useful tool for more accurate, efficient and effective energy management in modern networks.

      

      
        Another use case for PETRA could the negotiation of Service Level Agreements (SLAs) between operators and enterprise customers. By exposing PETRA-derived metrics such as watts-per-gigabit, providers can offer differentiated SLAs that explicitly include environmental targets. This enables customers to select network services not only based on performance guarantees (e.g. latency), but also on their environmental footprint (or a combination of both). Such SLAs empower customers to align their digital services with corporate energy-efficient and sustainability goals and reporting requirements, while operators can use PETRA to provide the energy metrics used for such services.
      

    

    
      The document Framework for Energy Efficiency Management  describes a reference model for energy management. The model includes an 'API Service Interface', labeled as interface (g) in the document, which "enables access for service consumption, enabling data retrieval, control, and integration through API". 

      In that context, PETRA is one example of such 'API Service Interface'. In the particular case of PETRA, the API might be used to consume from the Network controller, the Domain controller, or both.  describes a few use-cases that could make use of PETRA as an 'API Service Interface' within the Framework for Energy Efficiency Management .