log_annotation.proto

// Copyright (c) 2019 Boston Dynamics, Inc.  All rights reserved.
//
// Downloading, reproducing, distributing or otherwise using the SDK Software
// is subject to the terms and conditions of the Boston Dynamics Software
// Development Kit License (20191101-BDSDK-SL).

syntax = "proto3";
package bosdyn.api;

option java_outer_classname = "LogAnnotationProto";

import "bosdyn/api/header.proto";
import "google/protobuf/timestamp.proto";

message AddLogAnnotationRequest {
     /// Common request/response header.
    RequestHeader header = 1;

    LogAnnotations annotations = 2;
}

/// A container for elements to be added to the robot's logs.
message LogAnnotations {
    /// Text messages to be added to the log.
    repeated LogAnnotationTextMessage text_messages = 1;

    /// Messages from the robot operator to be added to the log.
    repeated LogAnnotationOperatorMessage operator_messages = 2;

    /// One or more binary blobs to add to the log.
    repeated LogAnnotationLogBlob blob_data = 3;

}

/// A text message to add to the robot's logs.
/// These could be internal text-log messages from a client for use in debugging, for
///  example.
message LogAnnotationTextMessage {
    /// String annotation message to add to the log.
    string message = 1;

    /// The timestamp of the annotation.  This must be in robot time.
    google.protobuf.Timestamp timestamp = 2;

    /// The service responsible for the annotation. May be omitted.
    string service = 3;

    enum Level {
        /// Invalid, do not use.
        LEVEL_UNKNOWN = 0;

        /// Events likely of interest only in a debugging context.
        LEVEL_DEBUG = 1;

        /// Informational message during normal operation.
        LEVEL_INFO = 2;

        /// Information about an unexpected but recoverable condition.
        LEVEL_WARN = 3;

        /// Information about an operation which did not succeed.
        LEVEL_ERROR = 4;
    }
    Level level = 4;  /// Significance of the message.

    /// Optional tag to identify from what code/module this message originated from.
    string tag = 5;

    /// Optional source file name originating the log message.
    string filename = 6;

    /// Optional source file line number originating the log message.
    int32 line_number = 7;
}

/// An operator message to be added to the robot's logs.
/// These are notes especially intended to mark when logs should be preserved and reviewed
///  to ensure that robot hardware and/or software is working as intended.
message LogAnnotationOperatorMessage {
    /// String annotation message to add to the log.
    string message = 1;

    /// The timestamp of the annotation.  This must be in robot time.
    google.protobuf.Timestamp timestamp = 2;
}


/// A unit of binary data to be entered in a log.
message LogAnnotationLogBlob {
    /// Timestamp of data in robot clock time.
    google.protobuf.Timestamp timestamp = 1;
    /// A general label for this blob.
    /// This is distinct from type_id, which identifies how the blob is to be parsed.
    string channel = 2;
    /// A description of the data's content and its encoding.
    /// This should be sufficient for deciding how to deserialize the data.
    /// For example, this could be the full name of a protobuf message type.
    string type_id = 3;
    /// Raw data.
    bytes data = 4;
}



message AddLogAnnotationResponse {
    /// Common request/response header.
    ResponseHeader header = 1;

    enum Status {
        /// Unknown / unexpected error.
        STATUS_UNKNOWN = 0;

        /// Successful response.
        STATUS_OK = 1;

        /// You sent an invalid annotation somehow.
        STATUS_INVALID = 2;

        /// Sequence ID was not 1 + the last one, comms problem?
        STATUS_WRONG_SEQUENCE_ID = 5;
    }
    
    Status status = 2;
}