ray/src/ray/protobuf/gcs.proto

// Copyright 2017 The Ray Authors.
//
// 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 ray.rpc;

import "src/ray/protobuf/common.proto";

option java_package = "io.ray.runtime.generated";

// These indexes are mapped to strings in ray_redis_module.cc.
enum TablePrefix {
  TABLE_PREFIX_MIN = 0;
  UNUSED = 1;
  TASK = 2;
  RAYLET_TASK = 3;
  CLIENT = 4;
  OBJECT = 5;
  ACTOR = 6;
  FUNCTION = 7;
  TASK_RECONSTRUCTION = 8;
  HEARTBEAT = 9;
  HEARTBEAT_BATCH = 10;
  ERROR_INFO = 11;
  JOB = 12;
  PROFILE = 13;
  TASK_LEASE = 14;
  ACTOR_CHECKPOINT = 15;
  ACTOR_CHECKPOINT_ID = 16;
  NODE_RESOURCE = 17;
  DIRECT_ACTOR = 18;
  WORKER_FAILURE = 19;
  TABLE_PREFIX_MAX = 20;
}

// The channel that Add operations to the Table should be published on, if any.
enum TablePubsub {
  TABLE_PUBSUB_MIN = 0;
  NO_PUBLISH = 1;
  TASK_PUBSUB = 2;
  RAYLET_TASK_PUBSUB = 3;
  CLIENT_PUBSUB = 4;
  OBJECT_PUBSUB = 5;
  ACTOR_PUBSUB = 6;
  HEARTBEAT_PUBSUB = 7;
  HEARTBEAT_BATCH_PUBSUB = 8;
  ERROR_INFO_PUBSUB = 9;
  TASK_LEASE_PUBSUB = 10;
  JOB_PUBSUB = 11;
  NODE_RESOURCE_PUBSUB = 12;
  DIRECT_ACTOR_PUBSUB = 13;
  WORKER_FAILURE_PUBSUB = 14;
  TABLE_PUBSUB_MAX = 15;
}

enum GcsChangeMode {
  APPEND_OR_ADD = 0;
  REMOVE = 1;
}

message GcsEntry {
  GcsChangeMode change_mode = 1;
  bytes id = 2;
  repeated bytes entries = 3;
}

message ObjectTableData {
  // The size of the object.
  uint64 object_size = 1;
  // The node manager ID that this object appeared on or was evicted by.
  bytes manager = 2;
}

message TaskReconstructionData {
  // The ID of task.
  bytes task_id = 1;
  // The number of times this task has been reconstructed so far.
  uint64 num_reconstructions = 2;
  // The node manager that is trying to reconstruct the task.
  bytes node_manager_id = 3;
}

message TaskTableData {
  Task task = 1;
}

message ActorTableData {
  // State of an actor.
  enum ActorState {
    // Actor is pending.
    PENDING = 0;
    // Actor is alive.
    ALIVE = 1;
    // Actor is dead, now being restarted.
    // After reconstruction finishes, the state will become alive again.
    RESTARTING = 2;
    // Actor is already dead and won't be restarted.
    DEAD = 3;
  }
  // The ID of the actor that was created.
  bytes actor_id = 1;
  // The ID of the caller of the actor creation task.
  bytes parent_id = 2;
  // The dummy object ID returned by the actor creation task. If the actor
  // dies, then this is the object that should be restarted for the actor
  // to be recreated.
  bytes actor_creation_dummy_object_id = 3;
  // The ID of the job that created the actor.
  bytes job_id = 4;
  // Current state of this actor.
  ActorState state = 6;
  // Max number of times this actor should be restarted,
  // a value of -1 indicates an infinite number of reconstruction attempts.
  int64 max_restarts = 7;
  // Number of restarts that have already been performed on this actor.
  uint64 num_restarts = 8;
  // The address of the the actor.
  Address address = 9;
  // The address of the the actor's owner (parent).
  Address owner_address = 10;
  // Whether the actor is persistent.
  bool is_detached = 11;
  // Name of the actor. Only populated if is_detached is true.
  string name = 12;
  // Timestamp that the actor is created or reconstructed.
  double timestamp = 13;
  // The task specification of this actor's creation task.
  TaskSpec task_spec = 14;
  // Resource mapping ids acquired by the leased worker. This field is only set when this
  // actor already has a leased worker.
  repeated ResourceMapEntry resource_mapping = 15;
}

message ErrorTableData {
  // The ID of the job that the error is for.
  bytes job_id = 1;
  // The type of the error.
  string type = 2;
  // The error message.
  string error_message = 3;
  // The timestamp of the error message.
  double timestamp = 4;
}

message ProfileTableData {
  // Represents a profile event.
  message ProfileEvent {
    // The type of the event.
    string event_type = 1;
    // The start time of the event.
    double start_time = 2;
    // The end time of the event. If the event is a point event, then this should
    // be the same as the start time.
    double end_time = 3;
    // Additional data associated with the event. This data must be serialized
    // using JSON.
    string extra_data = 4;
  }

  // The type of the component that generated the event, e.g., worker or
  // object_manager, or node_manager.
  string component_type = 1;
  // An identifier for the component that generated the event.
  bytes component_id = 2;
  // An identifier for the node that generated the event.
  string node_ip_address = 3;
  // This is a batch of profiling events. We batch these together for
  // performance reasons because a single task may generate many events, and
  // we don't want each event to require a GCS command.
  repeated ProfileEvent profile_events = 4;
}

message ResourceTableData {
  // The total capacity of this resource type.
  double resource_capacity = 1;
}

message GcsNodeInfo {
  // State of a node.
  enum GcsNodeState {
    // Node is alive.
    ALIVE = 0;
    // Node is dead.
    DEAD = 1;
  }

  // The ID of node.
  bytes node_id = 1;
  // The IP address of the node manager.
  string node_manager_address = 2;
  // The IPC socket name of raylet.
  string raylet_socket_name = 3;
  // The IPC socket name of the node's plasma store.
  string object_store_socket_name = 4;
  // The port at which the node manager is listening for TCP
  // connections from other node managers.
  int32 node_manager_port = 5;
  // The port at which the object manager is listening for TCP
  // connections from other object managers.
  int32 object_manager_port = 6;

  // Current state of this node.
  GcsNodeState state = 7;

  // The Hostname address of the node manager.
  string node_manager_hostname = 8;
}

message HeartbeatTableData {
  // Node manager client id
  bytes client_id = 1;
  // Resource capacity currently available on this node manager.
  map<string, double> resources_available = 2;
  // Total resource capacity configured for this node manager.
  map<string, double> resources_total = 3;
  // Aggregate outstanding resource load on this node manager.
  map<string, double> resource_load = 4;
  // Object IDs that are in use by workers on this node manager's node.
  repeated bytes active_object_id = 5;
  // Whether this node manager is requesting global GC.
  bool should_global_gc = 6;
}

message HeartbeatBatchTableData {
  repeated HeartbeatTableData batch = 1;
}

// Data for a lease on task execution.
message TaskLeaseData {
  // The task ID.
  bytes task_id = 1;
  // Node manager client ID.
  bytes node_manager_id = 2;
  // The time that the lease was last acquired at. NOTE(swang): This is the
  // system clock time according to the node that added the entry and is not
  // synchronized with other nodes.
  uint64 acquired_at = 3;
  // The period that the lease is active for.
  uint64 timeout = 4;
}

message JobTableData {
  // The job ID.
  bytes job_id = 1;
  // Whether it's dead.
  bool is_dead = 2;
  // The UNIX timestamp corresponding to this event (job added or removed).
  int64 timestamp = 3;
  // IP address of the driver that started this job.
  string driver_ip_address = 4;
  // Process ID of the driver running this job.
  int64 driver_pid = 5;
}

// This table stores the actor checkpoint data. An actor checkpoint
// is the snapshot of an actor's state in the actor registration.
// See `actor_registration.h` for more detailed explanation of these fields.
message ActorCheckpointData {
  // ID of this checkpoint.
  bytes checkpoint_id = 1;
  // ID of this actor.
  bytes actor_id = 2;
  // The dummy object ID of actor's most recently executed task.
  bytes execution_dependency = 3;
  // A list of IDs of this actor's handles.
  repeated bytes handle_ids = 4;
  // The task counters of the above handles.
  repeated uint64 task_counters = 5;
  // The frontier dependencies of the above handles.
  repeated bytes frontier_dependencies = 6;
  // A list of unreleased dummy objects from this actor.
  repeated bytes unreleased_dummy_objects = 7;
  // The numbers of dependencies for the above unreleased dummy objects.
  repeated uint32 num_dummy_object_dependencies = 8;
}

// This table stores the actor-to-available-checkpoint-ids mapping.
message ActorCheckpointIdData {
  // ID of this actor.
  bytes actor_id = 1;
  // IDs of this actor's available checkpoints.
  repeated bytes checkpoint_ids = 2;
  // A list of the timestamps for each of the above `checkpoint_ids`.
  repeated uint64 timestamps = 3;
}

message WorkerFailureData {
  // Address of the worker that failed.
  Address worker_address = 1;
  // The UNIX timestamp at which the worker failed.
  int64 timestamp = 3;
  // Is intentional disconnect
  bool intentional_disconnect = 4;
}

message ResourceMap {
  map<string, ResourceTableData> items = 1;
}

message ObjectTableDataList {
  repeated ObjectTableData items = 1;
}

message ObjectLocationInfo {
  bytes object_id = 1;
  repeated ObjectTableData locations = 2;
}

// A notification message about one object's locations being changed.
message ObjectLocationChange {
  bool is_add = 1;
  ObjectTableData data = 2;
}

// A notification message about one node's resources being changed.
message NodeResourceChange {
  // ID of the node whose resources have changed.
  bytes node_id = 1;
  // Labels of the updated resources and their latest capacities.
  map<string, double> updated_resources = 2;
  // Labels of the resources that were deleted.
  repeated string deleted_resources = 3;
}

message PubSubMessage {
  bytes id = 1;
  bytes data = 2;
}

// This enum type is used as object's metadata to indicate the object's creating
// task has failed because of a certain error.
// TODO(hchen): We may want to make these errors more specific. E.g., we may want
// to distinguish between intentional and expected actor failures, and between
// worker process failure and node failure.
enum ErrorType {
  // Indicates that a task failed because the worker died unexpectedly while executing it.
  WORKER_DIED = 0;
  // Indicates that a task failed because the actor died unexpectedly before finishing it.
  ACTOR_DIED = 1;
  // Indicates that an object is lost and cannot be restarted.
  // Note, this currently only happens to actor objects. When the actor's state is already
  // after the object's creating task, the actor cannot re-run the task.
  // TODO(hchen): we may want to reuse this error type for more cases. E.g.,
  // 1) A object that was put by the driver.
  // 2) The object's creating task is already cleaned up from GCS (this currently
  //    crashes raylet).
  OBJECT_UNRECONSTRUCTABLE = 2;
  // Indicates that a task failed due to user code failure.
  TASK_EXECUTION_EXCEPTION = 3;
  // Indicates that the object has been placed in plasma. This error shouldn't ever be
  // exposed to user code; it is only used internally to indicate the result of a direct
  // call has been placed in plasma.
  OBJECT_IN_PLASMA = 4;
  // Indicates that an object has been cancelled.
  TASK_CANCELLED = 5;
  // Inidicates that creating the GCS service failed to create the actor.
  ACTOR_CREATION_FAILED = 6;
}