control.proto

// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
// or more contributor license agreements. Licensed under the Elastic License;
// you may not use this file except in compliance with the Elastic License.

syntax = "proto3";

package proto;

option cc_enable_arenas = true;
option go_package = "pkg/agent/control/proto;proto";

// Status codes for the current state.
enum Status {
  STARTING = 0;
  CONFIGURING = 1;
  HEALTHY = 2;
  DEGRADED = 3;
  FAILED = 4;
  STOPPING = 5;
  UPGRADING = 6;
  ROLLBACK = 7;
}

// Action status codes for restart and upgrade response.
enum ActionStatus {
  // Action was successful.
  SUCCESS = 0;
  // Action failed.
  FAILURE = 1;
}

// pprof endpoint that can be requested.
enum PprofOption {
	ALLOCS = 0;
	BLOCK = 1;
	CMDLINE = 2;
	GOROUTINE = 3;
	HEAP = 4;
	MUTEX = 5;
	PROFILE = 6;
	THREADCREATE = 7;
	TRACE = 8;
}

// Empty message.
message Empty {
}

// Version response message.
message VersionResponse {
  // Current running version.
  string version = 1;
  // Current running commit.
  string commit = 2;
  // Current running build time.
  string buildTime = 3;
  // Current running version is a snapshot.
  bool snapshot = 4;
}

message RestartResponse {
  // Response status.
  ActionStatus status = 1;
  // Error message when it fails to trigger restart.
  string error = 2;
}

// Upgrade request message.
message UpgradeRequest {
  // (Optional) Version to upgrade to.
  //
  // If not provided Elastic Agent will auto discover the latest version in the same major
  // to upgrade to. If wanting to upgrade to a new major that major must be present in the
  // this version field.
  string version = 1;

  // (Optional) Use a different source URI then configured.
  //
  // If provided the upgrade process will use the provided sourceURI instead of the configured
  // sourceURI in the configuration.
  string sourceURI = 2;
}

// A upgrade response message.
message UpgradeResponse {
  // Response status.
  ActionStatus status = 1;

  // Version that is being upgraded to.
  string version = 2;

  // Error message when it fails to trigger upgrade.
  string error = 3;
}

// Current status of the application in Elastic Agent.
message ApplicationStatus {
  // Unique application ID.
  string id = 1;
  // Application name.
  string name = 2;
  // Current status.
  Status status = 3;
  // Current status message.
  string message = 4;
  // Current status payload.
  string payload = 5;
}

// Current metadata for a running process.
message ProcMeta {
  string process = 1;
  string name = 2;
  string hostname = 3;
  string id = 4;
  string ephemeral_id = 5;
  string version = 6;
  string build_commit = 7;
  string build_time = 8;
  string username = 9;
  string user_id = 10;
  string user_gid = 11;
  string architecture = 12;
  string route_key = 13;
  bool elastic_licensed = 14;
  string error = 15;
}

// Status is the current status of Elastic Agent.
message StatusResponse {
  // Overall status of Elastic Agent.
  Status status = 1;
  // Overall status message of Elastic Agent.
  string message = 2;
  // Status of each application in Elastic Agent.
  repeated ApplicationStatus applications = 3;
}

// ProcMetaResponse is the current running version infomation for all processes.
message ProcMetaResponse {
  repeated ProcMeta procs = 1;
}

// PprofRequest is a request for pprof data from and http/pprof endpoint.
message PprofRequest {
	// The profiles that are requested
	repeated PprofOption pprofType = 1;
	// A string representing a time.Duration to apply to trace, and profile options.
	string traceDuration = 2;
	// The application that will be profiled, if empty all applications are profiled.
	string appName = 3;
	// The route key to match for profiling, if empty all are profiled.
	string routeKey = 4;
}

// PprofResult is the result of a pprof request for a given application/route key.
message PprofResult {
	string appName = 1;
	string routeKey = 2;
	PprofOption pprofType = 3;
	bytes result = 4;
	string error = 5;
}

// PprofResponse is a wrapper to return all pprof responses.
message PprofResponse {
	repeated PprofResult results = 1;
}

// MetricsResponse is the result of a request for the metrics buffer endpoint for a application/route key
message MetricsResponse {
	string appName = 1;
	string routeKey = 2;
	bytes result = 3;
	string error = 4;
}

// ProcMetricsResponse is a wrapper to return all metrics buffer responses
message ProcMetricsResponse {
	repeated MetricsResponse result = 1;
}

service ElasticAgentControl {
  // Fetches the currently running version of the Elastic Agent.
  rpc Version(Empty) returns (VersionResponse);

  // Fetches the currently status of the Elastic Agent.
  rpc Status(Empty) returns (StatusResponse);

  // Restart restarts the current running Elastic Agent.
  rpc Restart(Empty) returns (RestartResponse);

  // Upgrade starts the upgrade process of Elastic Agent.
  rpc Upgrade(UpgradeRequest) returns (UpgradeResponse);

  // Gather all running process metadata.
  rpc ProcMeta(Empty) returns (ProcMetaResponse);

  // Gather requested pprof data from specified applications.
  rpc Pprof(PprofRequest) returns (PprofResponse);

  // Gather all running process metrics.
  rpc ProcMetrics(Empty) returns (ProcMetricsResponse);
}