src/developer/system_monitor/lib/proto/dockyard.proto

// Copyright 2018 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

syntax = "proto3";

package dockyard_proto;

// The dockyard service definition.
service Dockyard {
  // Sends initial set up data.
  rpc Init(InitRequest) returns (InitReply) {}

  // Ask the Dockyard what the ID is for the given path.
  rpc GetDockyardIdsForPaths(DockyardPaths) returns (DockyardIds) {}

  // Sends a batch of log messages.
  rpc SendLogs(stream LogBatch) returns (stream EmptyMessage) {}

  // Sends a single JSON inspection message.
  rpc SendInspectJson(stream InspectJson) returns (stream EmptyMessage) {}

  // Sends a single sample.
  rpc SendSample(stream RawSample) returns (stream EmptyMessage) {}

  // Sends a list of samples.
  rpc SendSamples(stream RawSamples) returns (stream EmptyMessage) {}

  // Informs Dockyard that the UTC clock has started.
  rpc UtcClockStarted(UtcClockStartedRequest) returns (UtcClockStartedReply) {}
}

// Introduction from the Harvester to the Dockyard.
message InitRequest {
  // Device name (e.g. a four word string).
  string device_name = 1;
  // Use `dockyard::DOCKYARD_VERSION` for this value.
  uint32 version = 2;
  // Current time on the device, in nanoseconds.
  uint64 device_time_ns = 3;
  // The Fuchsia OS revision (generally a git hash).
  string fuchsia_version = 4;
}

// Introduction from the Dockyard to the Harvester
message InitReply {
  // The `dockyard::DOCKYARD_VERSION`. The version will be checked by the
  // Dockyard. Sending this version to the Harvester is for reporting in the
  // log.
  uint32 version = 1;
}

// A non-message. Used for stream protocols to say that nothing is returned.
message EmptyMessage {}

// A path is a colon separated label. E.g. "cpu:0:busy_time". Paths are
// converted to an ID to reduce cpu, memory, and bandwidth usage.
message DockyardPaths {
  repeated string path = 1;
}

// A dockyard ID is an integer reference to a dockyard path (e.g. in a
// |DockyardPathMessage|).
message DockyardIds {
  repeated uint64 id = 1;
}

// Sample data going from the Harvester to the Dockyard. This message defines
// a type for use by other messages. It is not intended to be used on its own.
message Sample {
  uint64 key = 1;
  uint64 value = 2;
}

// Sample data going from the Harvester to the Dockyard. A single sample with a
// time stamp.
// |time| is in nanoseconds.
message RawSample {
  uint64 time = 1;
  Sample sample = 2;
}

// Sample data going from the Harvester to the Dockyard. A list of samples with
// a common timestamp. This is an optimization over sending a burst of separate
// samples with `RawSample`.
// |time| is in nanoseconds.
message RawSamples {
  uint64 time = 1;
  repeated Sample sample = 2;
}

// Component inspection data in JSON format.
// |time| is in nanoseconds.
// |id| is a dockyard ID for a path, as returned by GetDockyardIdsForPaths()
// |json| is a JSON format utf-8 string.
message InspectJson {
  uint64 time = 1;
  uint64 dockyard_id = 2;
  string json = 3;
}

// Structured log message(s) in a JSON array.
message LogJson {
  // A JSON format utf-8 string.
  string json = 1;
}

// A nested batch of structured logging json(arrays of structured log messages).
message LogBatch {
  // Current monotonic time in nanoseconds.
  uint64 monotonic_time = 1;

  // Current nanoseconds since epoch.
  uint64 time = 2;

  // List of LogJson in this batch.
  repeated LogJson log_json = 3;
}

// Tells Dockyard that the UTC clock has started and what the current time is.
message UtcClockStartedRequest {
  // Current time on the device, in nanoseconds.
  uint64 device_time_ns = 1;
}

// Response to a UtcClockStartedRequest which is defined for potential future use.
message UtcClockStartedReply {}