package com.github.trace_machina.nativelink.remote_execution
Get desktop application:
View/edit binary Protocol Buffers messages
service WorkerApi
worker_api.proto:31/ This API describes how schedulers communicate with Worker nodes. / / When a worker node comes online it must be pre-configured with the / endpoint of the scheduler it will register with. Once the worker / connects to the scheduler it must send a `ConnectWorkerRequest` / command to the scheduler. The scheduler will then use this information / to determine which jobs the worker can process.
rpc ConnectWorker (stream , stream )
worker_api.proto:41/ Registers this worker and informs the scheduler what properties / this worker supports. The response must be listened on the client / side for updates from the server. This is performed as a single / bi-directional call to ensure that the worker is always talking to the / same scheduler instance even if there's a load balancer in front. / The first message on the UpdateForScheduler stream will be a / ConnectWorkerRequest which will notify the scheduler of the available / properties and the first response will be a ConnectionResult to tell / the worker what worker ID to place in action results.
message
worker_api.proto:298/ Communication from the worker to the scheduler.
oneof update
connect_worker_request = 1
/ The initial request sent to the scheduler informing it of the / supported properties of this worker.
keep_alive_request = 2
/ Message used to let the scheduler know that it is still alive as / well as check to see if the scheduler is still alive. The scheduler / may close the connection if the worker has not sent any messages / after some amount of time (configured in the scheduler's / configuration).
going_away_request = 3
/ Informs the scheduler that the service is going offline and / should stop issuing any new actions on this worker. / / The worker may stay connected even after sending this command / and may even send an `ExecuteResult` after sending this command. / It is up to the scheduler implementation to decide how to handle / this case. / / Any job that was running on this instance likely needs to be / executed again, but up to the scheduler on how or when to handle / this case.
execute_result = 4
/ Informs the scheduler about the result of an execution request.
execute_complete = 5
/ Notify that the execution has completed, but result is uploading.
execute_accepted = 6
/ The worker took the action.
execute_declined = 7
/ The worker will not run the action.
message
worker_api.proto:270/ Communication from the scheduler to the worker.
oneof update
connection_result = 1
/ This will be sent only as the first item in the stream after the node / has connected.
keep_alive = 2
/ Message used to let the worker know that it is still alive as well / as check to see if the worker is still alive. The worker / may close the connection if the scheduler has not sent any messages / after some amount of time (configured in the scheduler's / configuration).
start_action = 3
/ Informs the worker about some work it should begin performing the / requested action.
disconnect = 4
/ Informs the worker that it has been disconnected from the pool. / The worker may discard any outstanding work that is being executed.
kill_operation_request = 5
/ Instructs the worker to kill a specific running operation.
message
worker_api.proto:167/ Resource usage observed by the worker while running one action.
Used in: ,
uint64 peak_memory_kb = 1
/ Peak resident memory observed for the action process tree.
bool sampled = 2
/ Whether this value came from worker-side sampling.
string operation_id = 3
/ The operation ID that was sampled.
string worker_id = 4
/ The worker ID that observed the resource usage.
uint64 cpu_time_ms = 5
/ Total CPU time consumed by the action process tree, in milliseconds. / User and system time combined, summed across every process in the / action's process group.
uint64 wall_time_ms = 6
/ Wall time from spawn to exit, in milliseconds; cores used is / cpu_time_ms / wall_time_ms.
uint64 peak_disk_kb = 7
/ Peak bytes under the action's work directory, in KiB. Not yet / measured; zero.
ResourceOutcome outcome = 8
/ How the action ended.
bool enforced = 9
/ True when a worker-side limit, not the kernel or a timeout, ended / the action.
optional reserved = 10
/ What the action was admitted with, from its platform properties.
message
worker_api.proto:76/ Represents the initial request sent to the scheduler informing the / scheduler about this worker's capabilities and metadata.
Used in:
repeated properties = 1
/ The list of properties this worker can support. The exact / implementation is driven by the configuration matrix between the / worker and scheduler. / / The scheduler may reject this worker if any property keys that / the scheduler is not configured to support, or may simply ignore / the unsupported properties. / / The details on how to use this property can be found here: / https://github.com/TraceMachina/nativelink/blob/3147265047544572e3483c985e4aab0f9fdded38/nativelink-config/src/cas_server.rs
string worker_id_prefix = 2
/ Prefix to use for worker IDs. This is primarily used for debugging / or for other systems to identify workers. The scheduler will always / append this prefix to the assigned worker_id followed by a UUIDv6.
uint64 max_inflight_tasks = 3
/ Maximum number of inflight tasks this worker can cope with at one time / The default (0) means unlimited.
bool admits_when_idle = 4
/ The worker admits any action while it holds nothing else, whatever / it reads free, rather than declining it for load. A scheduler can / then read a decline for load as coming from a busy worker. Absent / (false) from older workers.
message
worker_api.proto:207/ Result sent back from the server when a node connects.
Used in:
string worker_id = 1
/ The worker ID to place in the action results generated by this worker.
bool dispatch_ack = 2
/ The scheduler understands ExecuteAccepted and ExecuteDeclined. A / worker sends them only to a scheduler that says so: an older / scheduler would drop them, and a declined action would then wait on / a worker that never runs it.
string memory_property = 3
/ The platform property the scheduler reads an action's memory / reservation from, when it vetoes placement on the worker's reported / free memory (`live_memory_veto`). The worker declines a dispatch for / load against the same property, so the two sides cannot disagree. / Empty when the scheduler does not veto; the worker then never / declines for load.
message
worker_api.proto:230/ The worker took the action it was sent and is about to run it. Until / this arrives the scheduler has only charged its ledger on the send.
Used in:
string operation_id = 1
message
worker_api.proto:135/ The result of an ExecutionComplete.
Used in:
string operation_id = 1
/ The operation ID that was executed.
message
worker_api.proto:238/ The worker will not run the action it was sent. The scheduler restores / its ledger and requeues the action without counting an attempt, and / pauses the worker until it reports room again.
Used in:
string operation_id = 1
ExecuteDeclined.Reason reason = 2
string detail = 3
/ Free text for the log.
uint64 needed_kb = 4
/ For LOAD: what the action asked for and what the worker had, in KiB.
uint64 free_kb = 5
Used in:
REASON_UNSPECIFIED = 0
AT_CAPACITY = 1
/ The worker already has `max_inflight_tasks` actions.
LOAD = 2
/ The action's memory reservation is more than the worker has free.
SHUTTING_DOWN = 3
/ The worker is shutting down, or is single-use and already took / its action.
message
worker_api.proto:108/ The result of an ExecutionRequest.
Used in:
string instance_name = 1
/ The `instance_name` this task was initially assigned to. This is set by the client / that initially sent the job as part of the RBE protocol.
string operation_id = 2
/ The operation ID that was executed.
oneof result
/ The actual response data.
execute_response = 3
/ Result of the execution. See `build.bazel.remote.execution.v2.ExecuteResponse` / for details.
internal_error = 4
/ An internal error. This is only present when an internal error happened that / was not recoverable. If the execution job failed but at no fault of the worker / it should not use this field and should send the error via execute_response.
optional resource_usage = 5
/ Worker-observed resource usage for this action execution.
message
worker_api.proto:65/ Request object for going away requests.
Used in:
bool drain = 2
/ The worker is shutting down but still running actions: stop / dispatching to it and let those finish. It leaves the pool when its / stream closes. Without this the scheduler removes the worker at / once and requeues everything it holds.
NextId: 3.
message
worker_api.proto:368/ This is a special message used to save actions into the CAS that can be used / by programs like bb_browser to inspect the history of a build. / Note: Ensure this is always compatible with: / https://github.com/buildbarn/bb-remote-execution/blob/e95e066eb624dc9099682394ec18c12e218e8fc4/pkg/proto/cas/cas.proto#L23
optional action_digest = 1
optional execute_response = 3
message
worker_api.proto:57/ Request object for keep alive requests.
Used in:
optional load = 1
/ The worker's spare capacity as of this keepalive.
message
worker_api.proto:264/ Request to kill a running operation sent from the scheduler to a worker.
Used in:
string operation_id = 1
/ The the operation id for the operation to be killed.
message
worker_api.proto:159/ The reservation an action was admitted under, echoed by the worker so / the measurement and the number it was measured against travel together.
Used in:
uint64 cpu_count = 1
uint64 memory_kb = 2
uint64 disk_kb = 3
/ How an action ended, as the worker saw it. Separate from the exit code: / a kill by the worker or the kernel is a sizing fact, not a tool failure.
Used in:
RESOURCE_OUTCOME_UNKNOWN = 0
COMPLETED = 1
/ The process exited on its own, whatever its exit code.
KILLED_MEMORY = 2
/ Killed for memory: by the worker's reservation enforcement, or by / the kernel with the last sample within 10% of the memory limit.
KILLED_DISK = 3
/ Killed for disk. Reserved for disk enforcement.
KILLED_TIMEOUT = 4
/ Killed by the action timeout.
KILLED_EXTERNAL = 5
/ Killed from outside: a scheduler cancel, or a signal nobody here sent.
message
worker_api.proto:339Used in: ,
optional execute_request = 1
/ The action information used to execute job.
string operation_id = 4
/ Id of the operation.
optional queued_timestamp = 3
/ The time at which the command was added to the queue to allow population / of the ActionResult.
optional platform = 5
/ The post-computed platform properties that the scheduler has reserved for / the action.
string worker_id = 6
/ The ID of the worker that is executing the action.
optional request_metadata = 8
/ Original execution metadata, including the build tool and invocation. / Workers must not infer a Buck2 file session from an action digest alone.
message
worker_api.proto:47/ What a worker has to spare, sent with every keepalive so the scheduler / can veto a placement the admission ledger would allow. Absent from / older workers.
Used in:
uint64 free_memory_kb = 1
/ Memory the worker could still give an action, in KiB: the cgroup / limit less its working set (current usage less the page cache the / kernel can drop at once), or MemAvailable without a limit.