telemetry.proto

/* ----------------------------------------------------------------------------
 *
 * August 2016
 *
 * Copyright (c) 2016 by Cisco Systems, Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 * ----------------------------------------------------------------------------
 */

syntax = "proto3";
package telemetry;

// Telemetry message is the outermost payload message used to stream
// telemetry in a Model Driven Telemetry (MDT) system. MDT provides a
// mechanism for an external entity to subscribe to a data set defined in
// a Yang model and receive periodic or event-based updates of the data
// set from an MDT-capable device.
message Telemetry {
  //
  // node_id_str is a string encoded unique node ID of the MDT-capable
  // device producing the message. (node_id_uuid alternative is not currently
  // produced in IOS-XR)
  oneof node_id {
    string node_id_str = 1;
    // bytes node_id_uuid = 2;
  }
  //
  // subscription_id_str is the name of the subscription against which
  // this content is being produced. (subscription_id alternative is not
  //  currently produced in IOS-XR)
  oneof subscription {
    string   subscription_id_str = 3;
    // uint32   subscription_id = 4;
  }
  //
  // sensor_path is not currently produced in IOS-XR
  // string   sensor_path = 5;
  //
  // encoding_path is the Yang path leading to the content in this message.
  // The Yang tree encoded in the content section of this message is rooted
  // at the point described by the encoding_path.
  string   encoding_path = 6;
  //
  // model_version is not currently produced in IOS-XR
  // string   model_version = 7;
  //
  // collection_id identifies messages belonging to a collection round.
  // Multiple message may be generated from a collection round.
  uint64   collection_id = 8;
  //
  // collection_start_time is the time when the collection identified by
  // the collection_id begins - encoded as milliseconds since the epoch.
  // If a single collection is spread over multiple Telemetry Messages,
  // collection_start_time may be encoded in the first Telemetry Message
  // for the collection only.
  uint64   collection_start_time = 9;
  //
  // msg_timestamp is the time when the data encoded in the Telemetry
  // message is generated - encoded as milliseconds since the epoch.
  uint64   msg_timestamp = 10;
  //
  // data_gpbkv contains the payload data if data is being encoded in the
  // self-describing GPB-KV format.
  repeated TelemetryField data_gpbkv = 11;
  //
  // data_gpb contains the payload data if data is being encoded as
  // serialised GPB messages.
  TelemetryGPBTable data_gpb = 12;
  //
  // collection_end_time is the timestamp when the last Telemetry message
  // for a collection has been encoded - encoded as milliseconds since the
  // epoch. If a single collection is spread over multiple Telemetry
  // messages, collection_end_time is encoded in the last Telemetry Message
  // for the collection only.
  uint64 collection_end_time = 13;
  //
  // heartbeat_sequence_number is not currently produced in IOS-XR
  // uint64   heartbeat_sequence_number = 14; // not produced
}

//
// TelemetryField messages are used to export content in the self
// describing GPB KV form. The TelemetryField message is sufficient to
// decode telemetry messages for all models. KV-GPB encoding is very
// similar in concept, to JSON encoding
message TelemetryField {
  //
  // timestamp represents the starting time of the generation of data
  // starting from this key, value pair in this message - encoded as
  // milliseconds since the epoch. It is encoded when different from the
  // msg_timestamp in the containing Telemetry Message. This field can be
  // omitted if the value is the same as a TelemetryField message up the
  // hierarchy within the same Telemetry Message as well.
  uint64         timestamp = 1;
  //
  // name: string encoding of the name in the key, value pair. It is
  // the corresponding YANG element name.
  string         name = 2;
  //
  // value_by_type, if present, for the corresponding YANG element
  // represented by the name field in the same TelemetryField message. The
  // value is encoded to the matching type as defined in the YANG model.
  // YANG models often define new types (derived types) using one or more
  // base types.  The types included in the oneof grouping is sufficient to
  // represent such derived types. Derived types represented as a Yang
  // container are encoded using the nesting primitive defined in this
  // encoding proposal.
  oneof value_by_type {
    bytes          bytes_value = 4;
    string         string_value = 5;
    bool           bool_value = 6;
    uint32         uint32_value = 7;
    uint64         uint64_value = 8;
    sint32         sint32_value = 9;
    sint64         sint64_value = 10;
    double         double_value = 11;
    float          float_value = 12;
  }
  //
  // The Yang model may include nesting (e.g hierarchy of containers). The
  // next level of nesting, if present, is encoded, starting from fields.
  repeated TelemetryField fields = 15;
}

// TelemetryGPBTable contains a repeated number of TelemetryRowGPB,
// each of which represents content from a subtree instance in the
// the YANG model. For example; a TelemetryGPBTable might contain
// the interface statistics of a collection of interfaces.
message TelemetryGPBTable {
  repeated TelemetryRowGPB row = 1;
}

//
// TelemetryRowGPB, in conjunction with the Telemetry encoding_path and
// model_version, unambiguously represents the root of a subtree in
// the YANG model, and content from that subtree encoded in serialised
// GPB messages. For example; a TelemetryRowGPB might contain the
// interface statistics of one interface. Per encoding-path .proto
// messages are required to decode keys/content pairs below.
message TelemetryRowGPB {
  //
  // timestamp at which the data for this instance of the TelemetryRowGPB
  // message was generated by an MDT-capable device - encoded as
  // milliseconds since the epoch.  When included, this is typically
  // different from the msg_timestamp in the containing Telemetry message.
  uint64 timestamp = 1;
  //
  // keys: if the encoding-path includes one or more list elements, and/or
  // ends in a list element, the keys field is a GPB encoded message that
  // contains the sequence of key values for each such list element in the
  // encoding-path traversed starting from the root.  The set of keys
  // unambiguously identifies the instance of data encoded in the
  // TelemetryRowGPB message. Corresponding protobuf message definition will
  // be required to decode the byte stream. The encoding_path field in
  // Telemetry message, together with model_version field should be
  // sufficient to identify the corresponding protobuf message.
  bytes keys = 10;
  //
  // content: the content field is a GPB encoded message that contains the
  // data for the corresponding encoding-path. A separate decoding pass
  // would be performed by consumer with the content field as a GPB message
  // and the matching .proto used to decode the message. Corresponding
  // protobuf message definition will be required to decode the byte
  // stream. The encoding_path field in Telemetry message, together with
  // model_version field should be sufficient to identify the corresponding
  // protobuf message. The decoded combination of keys (when present) and
  // content, unambiguously represents an instance of the data set, as
  // defined in the Yang model, identified by the encoding-path in the
  // containing Telemetry message.
bytes content = 11;
}