1/* ---------------------------------------------------------------------------- 2 * telemetry_bis.proto - Telemetry protobuf definitions 3 * 4 * August 2016 5 * 6 * Copyright (c) 2016 by Cisco Systems, Inc. 7 * 8 * Licensed under the Apache License, Version 2.0 (the "License"); 9 * you may not use this file except in compliance with the License. 10 * You may obtain a copy of the License at 11 * 12 * http://www.apache.org/licenses/LICENSE-2.0 13 * 14 * Unless required by applicable law or agreed to in writing, software 15 * distributed under the License is distributed on an "AS IS" BASIS, 16 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 17 * See the License for the specific language governing permissions and 18 * limitations under the License. 19 * ---------------------------------------------------------------------------- 20 */ 21 22syntax = "proto3"; 23package telemetry; 24 25// Telemetry message is the outermost payload message used to stream 26// telemetry in a Model Driven Telemetry (MDT) system. MDT provides a 27// mechanism for an external entity to subscribe to a data set defined in 28// a Yang model and receive periodic or event-based updates of the data 29// set from an MDT-capable device. 30message Telemetry { 31 // 32 // node_id_str is a string encoded unique node ID of the MDT-capable 33 // device producing the message. (node_id_uuid alternative is not currently 34 // produced in IOS-XR) 35 oneof node_id { 36 string node_id_str = 1; 37 // bytes node_id_uuid = 2; 38 } 39 // 40 // subscription_id_str is the name of the subscription against which 41 // this content is being produced. (subscription_id alternative is not 42 // currently produced in IOS-XR) 43 oneof subscription { 44 string subscription_id_str = 3; 45 // uint32 subscription_id = 4; 46 } 47 // 48 // sensor_path is not currently produced in IOS-XR 49 // string sensor_path = 5; 50 // 51 // encoding_path is the Yang path leading to the content in this message. 52 // The Yang tree encoded in the content section of this message is rooted 53 // at the point described by the encoding_path. 54 string encoding_path = 6; 55 // 56 // model_version is not currently produced in IOS-XR 57 // string model_version = 7; 58 // 59 // collection_id identifies messages belonging to a collection round. 60 // Multiple message may be generated from a collection round. 61 uint64 collection_id = 8; 62 // 63 // collection_start_time is the time when the collection identified by 64 // the collection_id begins - encoded as milliseconds since the epoch. 65 // If a single collection is spread over multiple Telemetry Messages, 66 // collection_start_time may be encoded in the first Telemetry Message 67 // for the collection only. 68 uint64 collection_start_time = 9; 69 // 70 // msg_timestamp is the time when the data encoded in the Telemetry 71 // message is generated - encoded as milliseconds since the epoch. 72 uint64 msg_timestamp = 10; 73 // 74 // data_gpbkv contains the payload data if data is being encoded in the 75 // self-describing GPB-KV format. 76 repeated TelemetryField data_gpbkv = 11; 77 // 78 // data_gpb contains the payload data if data is being encoded as 79 // serialised GPB messages. 80 TelemetryGPBTable data_gpb = 12; 81 // 82 // collection_end_time is the timestamp when the last Telemetry message 83 // for a collection has been encoded - encoded as milliseconds since the 84 // epoch. If a single collection is spread over multiple Telemetry 85 // messages, collection_end_time is encoded in the last Telemetry Message 86 // for the collection only. 87 uint64 collection_end_time = 13; 88 // 89 // heartbeat_sequence_number is not currently produced in IOS-XR 90 // uint64 heartbeat_sequence_number = 14; // not produced 91} 92 93// 94// TelemetryField messages are used to export content in the self 95// describing GPB KV form. The TelemetryField message is sufficient to 96// decode telemetry messages for all models. KV-GPB encoding is very 97// similar in concept, to JSON encoding 98message TelemetryField { 99 // 100 // timestamp represents the starting time of the generation of data 101 // starting from this key, value pair in this message - encoded as 102 // milliseconds since the epoch. It is encoded when different from the 103 // msg_timestamp in the containing Telemetry Message. This field can be 104 // omitted if the value is the same as a TelemetryField message up the 105 // hierarchy within the same Telemetry Message as well. 106 uint64 timestamp = 1; 107 // 108 // name: string encoding of the name in the key, value pair. It is 109 // the corresponding YANG element name. 110 string name = 2; 111 // 112 // value_by_type, if present, for the corresponding YANG element 113 // represented by the name field in the same TelemetryField message. The 114 // value is encoded to the matching type as defined in the YANG model. 115 // YANG models often define new types (derived types) using one or more 116 // base types. The types included in the oneof grouping is sufficient to 117 // represent such derived types. Derived types represented as a Yang 118 // container are encoded using the nesting primitive defined in this 119 // encoding proposal. 120 oneof value_by_type { 121 bytes bytes_value = 4; 122 string string_value = 5; 123 bool bool_value = 6; 124 uint32 uint32_value = 7; 125 uint64 uint64_value = 8; 126 sint32 sint32_value = 9; 127 sint64 sint64_value = 10; 128 double double_value = 11; 129 float float_value = 12; 130 } 131 // 132 // The Yang model may include nesting (e.g hierarchy of containers). The 133 // next level of nesting, if present, is encoded, starting from fields. 134 repeated TelemetryField fields = 15; 135} 136 137// TelemetryGPBTable contains a repeated number of TelemetryRowGPB, 138// each of which represents content from a subtree instance in the 139// the YANG model. For example; a TelemetryGPBTable might contain 140// the interface statistics of a collection of interfaces. 141message TelemetryGPBTable { 142 repeated TelemetryRowGPB row = 1; 143} 144 145// 146// TelemetryRowGPB, in conjunction with the Telemetry encoding_path and 147// model_version, unambiguously represents the root of a subtree in 148// the YANG model, and content from that subtree encoded in serialised 149// GPB messages. For example; a TelemetryRowGPB might contain the 150// interface statistics of one interface. Per encoding-path .proto 151// messages are required to decode keys/content pairs below. 152message TelemetryRowGPB { 153 // 154 // timestamp at which the data for this instance of the TelemetryRowGPB 155 // message was generated by an MDT-capable device - encoded as 156 // milliseconds since the epoch. When included, this is typically 157 // different from the msg_timestamp in the containing Telemetry message. 158 uint64 timestamp = 1; 159 // 160 // keys: if the encoding-path includes one or more list elements, and/or 161 // ends in a list element, the keys field is a GPB encoded message that 162 // contains the sequence of key values for each such list element in the 163 // encoding-path traversed starting from the root. The set of keys 164 // unambiguously identifies the instance of data encoded in the 165 // TelemetryRowGPB message. Corresponding protobuf message definition will 166 // be required to decode the byte stream. The encoding_path field in 167 // Telemetry message, together with model_version field should be 168 // sufficient to identify the corresponding protobuf message. 169 bytes keys = 10; 170 // 171 // content: the content field is a GPB encoded message that contains the 172 // data for the corresponding encoding-path. A separate decoding pass 173 // would be performed by consumer with the content field as a GPB message 174 // and the matching .proto used to decode the message. Corresponding 175 // protobuf message definition will be required to decode the byte 176 // stream. The encoding_path field in Telemetry message, together with 177 // model_version field should be sufficient to identify the corresponding 178 // protobuf message. The decoded combination of keys (when present) and 179 // content, unambiguously represents an instance of the data set, as 180 // defined in the Yang model, identified by the encoding-path in the 181 // containing Telemetry message. 182bytes content = 11; 183} 184