Live run event protocol

This reference is generated from the versioned wire definition during the documentation build. It describes the service, event variants, fields, and enum values shipped by Once.

The client publishes ordered batches and the service acknowledges the contiguous durable frontier. The server may return a dashboard link after run creation.

service RunEventService#

Every call carries the bearer token in the authorization metadata. Clients also send the opaque project id, the same value as RunStarted.project_id, in the optional once-project-id metadata, because a reconnect does not always resend RunStarted. See RFC 0008, "Identity and redaction".

NameTypeNumberDescription
rpc GetServerCapabilities(GetServerCapabilitiesRequest) returns (ServerCapabilities)call
rpc GetArgvHashKey(GetArgvHashKeyRequest) returns (ArgvHashKey)call
rpc PublishRunEvents(stream RunEventBatch) returns (stream BatchAck)call
rpc GetRunAck(GetRunAckRequest) returns (RunEventAck)call

message GetServerCapabilitiesRequest#

NameTypeNumberDescription

message GetRunAckRequest#

NameTypeNumberDescription
run_idstring1

message GetArgvHashKeyRequest#

NameTypeNumberDescription
project_idstring1

message ServerCapabilities#

NameTypeNumberDescription
supported_protocol_versionsrepeated string1
max_batch_bytesuint322
max_event_bytesuint323
max_unacked_eventsuint324
max_log_chunk_bytesuint325
required_featuresrepeated string6
log_ingestion_availablebool7
raw_event_retention_availablebool8
finalization_grace_msuint329
dedup_retention_secondsuint3210
safe_literal_allowlist_versionstring11

message ArgvHashKey#

NameTypeNumberDescription
key_idstring1
key_bytesbytes2
expires_at_epoch_msint643
grace_after_expiry_msuint324

message RunEventBatch#

NameTypeNumberDescription
run_idstring1
batch_idstring2
gap_advancesrepeated GapAdvance3
seq_fromuint644
eventsrepeated RunEvent5
producer_dropped_eventsuint646Cumulative count dropped by the producer's event bus before assignment of sequence numbers. Unlike gap_advances, these have no sequence range.

message GapAdvance#

NameTypeNumberDescription
first_dropped_sequint641
last_dropped_sequint642
reasonstring3

message BatchAck#

NameTypeNumberDescription
run_idstring1
batch_idstring2
dispositionAckDisposition3
acked_sequint644
expected_next_sequint645
observed_high_water_sequint646
retry_after_msuint327
max_in_flight_batchesuint328
finalizationRunFinalization9
dashboard_urlstring10Canonical absolute dashboard link, available after durable run creation.

message RunEventAck#

NameTypeNumberDescription
run_idstring1
acked_sequint642
expected_next_sequint643
observed_high_water_sequint644
finalizationRunFinalization5
dashboard_urlstring6

enum AckDisposition#

NameTypeNumberDescription
ACK_DISPOSITION_UNSPECIFIEDvalue0
ACK_DISPOSITION_ACCEPTEDvalue1
ACK_DISPOSITION_REJECTED_STALEvalue2
ACK_DISPOSITION_REJECTED_INVALIDvalue3
ACK_DISPOSITION_NEEDS_RESYNCvalue4

enum RunFinalization#

NameTypeNumberDescription
RUN_FINALIZATION_UNSPECIFIEDvalue0
RUN_FINALIZATION_ACTIVEvalue1
RUN_FINALIZATION_FINALIZINGvalue2
RUN_FINALIZATION_FINALIZEDvalue3
RUN_FINALIZATION_FINALIZATION_PENDINGvalue4
RUN_FINALIZATION_LOSTvalue5

message ContentRef#

NameTypeNumberDescription
hash_algorithmHashAlgorithm1
digestbytes2Raw digest bytes, not hexadecimal text.
size_bytesuint643
namespacestring4
media_typestring5

enum HashAlgorithm#

NameTypeNumberDescription
HASH_ALGORITHM_UNSPECIFIEDvalue0
HASH_ALGORITHM_BLAKE3value1
HASH_ALGORITHM_SHA256value2

message RunEvent#

NameTypeNumberDescription
sequint641
epoch_msint642
mono_nsint643
payloadone of
run_startedRunStarted10
run_finalizingRunFinalizing11
run_completedRunCompleted12
run_heartbeatRunHeartbeat13
graph_compiledGraphCompiled20
target_instanceTargetInstance21
target_queuedTargetQueued30
target_startedTargetStarted31
target_phaseTargetPhase32
target_waitTargetWait33
target_completedTargetCompleted34
target_cancelledTargetCancelled35
target_retriedTargetRetried36
action_completedActionCompleted37
target_phase_completedTargetPhaseCompleted38
action_attempt_startedActionAttemptStarted39
action_attempt_completedActionAttemptCompleted45
test_suite_startedTestSuiteStarted40
test_suite_completedTestSuiteCompleted41
test_case_startedTestCaseStarted42
test_case_completedTestCaseCompleted43
test_case_retriedTestCaseRetried44
log_chunkLogChunk50
log_truncatedLogTruncated51
cache_probeCacheProbe60
cache_miss_reasonCacheMissReason61
cache_uploadCacheUpload62
cache_downloadCacheDownload63
cache_store_reusedCacheStoreReused64
artifact_publishedArtifactPublished70
diagnostic_emittedDiagnosticEmitted71
system_sampledSystemSampled80

message RunStarted#

NameTypeNumberDescription
once_versionstring1
protocol_versionstring2
host_classstring3
git_revstring4
git_dirtybool5
argv_normalizedrepeated ArgvToken6
argv_hash_key_idstring7
safe_literal_allowlist_versionstring8
cwd_relativestring9
env_fingerprintstring10
root_graph_digestContentRef11
project_idstring12
effective_limitsEffectiveLimits13
is_cibool14Whether the run happened on CI rather than a developer machine. The dashboard splits runs on this the way it does for the other build systems, which all report the same distinction.
git_branchstring15The branch the run was built from, empty when it cannot be determined. CI checkouts are usually on a detached HEAD, where git alone reports "HEAD" rather than a name, so the provider's own branch variable is preferred over asking git.

message ArgvToken#

NameTypeNumberDescription
tokenone of
safe_literalstring1
flag_keystring2
named_valueNamedValue3
opaque_value_hashstring4

message NamedValue#

NameTypeNumberDescription
keystring1
value_shape_hashstring2

message EffectiveLimits#

NameTypeNumberDescription
max_batch_bytesuint321
max_event_bytesuint322
max_unacked_eventsuint323
max_log_chunk_bytesuint324
log_ingestion_enabledbool5
raw_event_retention_enabledbool6

message RunFinalizing#

NameTypeNumberDescription
declared_drain_msint641

message RunCompleted#

NameTypeNumberDescription
resultRunResult1
cancellation_reasonstring2
wall_msint643
totalsRunTotals4
producer_dropped_eventsuint645

enum RunResult#

NameTypeNumberDescription
RUN_RESULT_UNSPECIFIEDvalue0
RUN_RESULT_SUCCEEDEDvalue1
RUN_RESULT_FAILEDvalue2
RUN_RESULT_CANCELLEDvalue3
RUN_RESULT_TIMED_OUTvalue4
RUN_RESULT_INFRASTRUCTURE_ERRORvalue5

message RunTotals#

NameTypeNumberDescription
targets_by_resultmap<string, uint32>1
cases_by_resultmap<string, uint32>2
cache_hit_ratedouble3
cache_bytes_downloadeduint644
cache_bytes_uploadeduint645
cache_bytes_saveduint646

message RunHeartbeat#

NameTypeNumberDescription

message GraphCompiled#

NameTypeNumberDescription
graph_digestContentRef1
target_countuint322
kind_histogrammap<string, uint32>3
rootsrepeated string4

message TargetInstance#

NameTypeNumberDescription
target_instance_idstring1
target_idstring2
configuration_digestContentRef3

message TargetQueued#

NameTypeNumberDescription
target_execution_idstring1
target_instance_idstring2
kindstring3
capabilitystring4
action_digestContentRef5
input_digestContentRef6
dep_target_executionsrepeated string7
attemptuint328

message TargetStarted#

NameTypeNumberDescription
target_execution_idstring1
worker_classstring2

message TargetPhase#

NameTypeNumberDescription
target_execution_idstring1
phasePhase2

enum Phase#

NameTypeNumberDescription
PHASE_UNSPECIFIEDvalue0
PHASE_QUEUEDvalue1
PHASE_CACHE_CHECKINGvalue2
PHASE_PREPARINGvalue3
PHASE_EXECUTINGvalue4
PHASE_CAPTURINGvalue5
PHASE_PUBLISHINGvalue6

message TargetWait#

NameTypeNumberDescription
target_execution_idstring1
reasonWaitReason2
blocking_target_execution_idstring3
resource_kindstring4

enum WaitReason#

NameTypeNumberDescription
WAIT_REASON_UNSPECIFIEDvalue0
WAIT_REASON_DEPENDENCY_WAITvalue1
WAIT_REASON_RESOURCE_WAITvalue2
WAIT_REASON_WORKER_WAITvalue3
WAIT_REASON_THROTTLEDvalue4
WAIT_REASON_INFRASTRUCTUREvalue5

message TargetCompleted#

NameTypeNumberDescription
target_execution_idstring1
resultTargetResult2
was_cachedbool3
exit_codeoptional int324
evidence_digestContentRef5
duration_msint646

enum TargetResult#

NameTypeNumberDescription
TARGET_RESULT_UNSPECIFIEDvalue0
TARGET_RESULT_SUCCEEDEDvalue1
TARGET_RESULT_FAILEDvalue2
TARGET_RESULT_SKIPPEDvalue3
TARGET_RESULT_CANCELLEDvalue4
TARGET_RESULT_TIMED_OUTvalue5
TARGET_RESULT_INFRASTRUCTURE_ERRORvalue6

message TargetCancelled#

NameTypeNumberDescription
target_execution_idstring1
reasonstring2

message TargetRetried#

NameTypeNumberDescription
previous_target_execution_idstring1
new_target_execution_idstring2
new_attemptuint323
reasonstring4

message ActionPresentation#

Ecosystem-owned context. Omission retains legacy labels and source paths.

NameTypeNumberDescription
packageActionPackage1
platformsrepeated ActionPlatform2
contextrepeated ActionContext3

message ActionPackage#

NameTypeNumberDescription
ecosystemstring1
namestring2
versionstring3
revisionstring4
digeststring5
originstring6workspace, registry, git, path, or a future producer-owned origin.

message ActionPlatform#

NameTypeNumberDescription
schemestring1
idstring2
labelstring3
usagestring4product or build-tool. This is not execution-worker placement.

message ActionContext#

NameTypeNumberDescription
keystring1
valuestring2
labelstring3

message ActionCompleted#

Exactly one declared action outcome. Identity within a run is the tuple (target_execution_id, capability, action_index). The index is zero-based declaration order, never completion order; identifier is a diagnostic label. A new target attempt must use a new target_execution_id. Cached target reuse emits the retained actions with current-run timing, not old spans.

NameTypeNumberDescription
target_execution_idstring1
capabilitystring2"build", "test", ...
action_indexuint323position within the target's ordered action list
identifierstring4Starlark-declared identity, may be empty
resultTargetResult5
was_cachedbool6
duration_msint647
exit_codeint328
start_at_epoch_msint649Wall-clock start time of the action, in epoch milliseconds. When present the projector prefers this over envelope.epoch_ms - duration_ms, which collapses many actions that all completed inside one millisecond bucket.
worker_idstring10Stable identifier of the worker (tokio task / OS thread / target execution scheduler) that ran this action. The dashboard groups rows in the flame graph by worker, matching Bazel's per-tid rendering.
prepare_msint6411Split of duration_ms into the two phases the CLI observes. prepare_ms covers arg files, input fingerprinting, and action digest; execute_ms covers cache probe + (on a miss) command execution and output upload. The server renders each as its own sub-span on the worker's lane so a cache-heavy build shows what filled the wall clock instead of a sea of 1 ms dashes. Zero when unknown (cached-replay actions).
execute_msint6412
cache_keystring13Hex digest the action probed against the content-addressable store, action_digest. Shown as the "Cache key" column on the Cacheable Actions view of the dashboard.
selected_attemptuint3214Zero means no attempt executed in this run, as with retained target reuse. Otherwise this selects one attempt from the matching tuple below.
display_nameoptional string15Presentation only; does not replace identifier or affect cache identity.
source_filesrepeated string16Repository-relative presentation paths using forward slashes, never host paths. Includes untracked or downloaded sources; consumers must consult source_file_statuses before linking at RunStarted.git_rev.
source_file_statusesrepeated SourceFileStatus17Entry i describes source_files[i] at RunStarted.git_rev. Classifying clients send one status per path, including UNKNOWN on lookup failure. Empty means legacy metadata. A nonempty length mismatch is invalid for linking: consumers must show every path without a repository link.
presentationActionPresentation18Optional bounded presentation data. Never action identity or cache inputs.
historyActionHistoryKey19Optional producer-owned logical identity for cross-run history. Never execution identity, observations, or action-result cache inputs.

message ActionHistoryKey#

NameTypeNumberDescription
namespacestring1Versioned producer namespace (ASCII token, at most 64 bytes).
keystring2Opaque stable key (at most 128 bytes); not a cache digest or run id.

enum SourceFileStatus#

Presentation only: these values must not affect action or cache identity.

NameTypeNumberDescription
SOURCE_FILE_STATUS_UNSPECIFIEDvalue0
SOURCE_FILE_STATUS_COMMITTEDvalue1A blob (regular file or symlink) at the path in RunStarted.git_rev.
SOURCE_FILE_STATUS_NOT_COMMITTEDvalue2The commit tree was read successfully and contains no blob at the path.
SOURCE_FILE_STATUS_UNKNOWNvalue3No usable commit tree, including failed or bounded-out lookups.

message ActionAttemptStarted#

The tuple (target_execution_id, capability, action_index, attempt) is a run-local identity. An attempt begins when a worker starts preparing it; a later retry uses the next attempt number and may use another worker.

NameTypeNumberDescription
target_execution_idstring1
capabilitystring2
action_indexuint323
attemptuint324
worker_idstring5

message ActionAttemptCompleted#

NameTypeNumberDescription
target_execution_idstring1
capabilitystring2
action_indexuint323
attemptuint324
resultTargetResult5
exit_codeint326
duration_msint647
was_cachedbool8

message TargetPhaseCompleted#

Observed target-level work, excluded from declared-action counts. Phase names are extensible and ecosystem-neutral. Unknown names are shown as opaque labels. worker_id identifies a run-local scheduling lane, not a physical host or a promise of thread affinity.

NameTypeNumberDescription
target_execution_idstring1
phasestring2
worker_idstring3
start_at_epoch_msint644
duration_msint645

message TestSuiteStarted#

NameTypeNumberDescription
target_execution_idstring1
suite_idstring2
planned_case_countoptional uint323

message TestSuiteCompleted#

NameTypeNumberDescription
target_execution_idstring1
suite_idstring2
totalsTestTotals3
result_report_digestContentRef4

message TestTotals#

NameTypeNumberDescription
passeduint321
faileduint322
skippeduint323
erroreduint324
timed_outuint325
cancelleduint326
flaky_final_passuint327
flaky_final_failuint328
unknownuint329

message TestCaseStarted#

NameTypeNumberDescription
test_case_execution_idstring1
target_execution_idstring2
case_idstring3
namestring4
class_namestring5
filestring6
parametersstring7
tagsrepeated string8
attemptuint329

message TestCaseCompleted#

NameTypeNumberDescription
test_case_execution_idstring1
resultTestCaseResult2
was_flakybool3
duration_msint644
failureTestFailure5
case_idstring6Self-describing so retrospective results do not require a fabricated start event or a server-side join to identify the case.
namestring7
suite_idstring8
attemptuint329
observed_duration_msoptional int6410Prefer this presence-aware measurement; the legacy duration_ms is zero when a retrospective report omits timing.

enum TestCaseResult#

NameTypeNumberDescription
TEST_CASE_RESULT_UNSPECIFIEDvalue0
TEST_CASE_RESULT_PASSEDvalue1
TEST_CASE_RESULT_FAILEDvalue2
TEST_CASE_RESULT_SKIPPEDvalue3
TEST_CASE_RESULT_TIMED_OUTvalue4
TEST_CASE_RESULT_ERROREDvalue5
TEST_CASE_RESULT_CANCELLEDvalue6
TEST_CASE_RESULT_UNKNOWNvalue7

message TestCaseRetried#

NameTypeNumberDescription
previous_test_case_execution_idstring1
new_test_case_execution_idstring2
new_attemptuint323
reasonstring4

message TestFailure#

NameTypeNumberDescription
messagestring1
expectedstring2
actualstring3
stack_digestContentRef4

message LogChunk#

NameTypeNumberDescription
scopeLogScope1
streamStream2
offsetint643
bytesbytes4

message LogTruncated#

NameTypeNumberDescription
scopeLogScope1
streamStream2
bytes_droppedint643
since_offsetint644

message LogScope#

NameTypeNumberDescription
scopeone of
runRunScope1
target_execution_idstring2
test_case_execution_idstring3

message RunScope#

NameTypeNumberDescription

enum Stream#

NameTypeNumberDescription
STREAM_UNSPECIFIEDvalue0
STREAM_STDOUTvalue1
STREAM_STDERRvalue2

message CacheProbe#

NameTypeNumberDescription
cache_decision_idstring1
target_execution_idstring2
action_digestContentRef3
tierstring4
tier_indexuint325
outcomeCacheOutcome6
duration_msint647
error_classstring8

enum CacheOutcome#

NameTypeNumberDescription
CACHE_OUTCOME_UNSPECIFIEDvalue0
CACHE_OUTCOME_HITvalue1
CACHE_OUTCOME_MISSvalue2
CACHE_OUTCOME_ERRORvalue3
CACHE_OUTCOME_BYPASSEDvalue4

message CacheMissReason#

NameTypeNumberDescription
cache_decision_idstring1
target_execution_idstring2
primary_reasonMissReasonKind3
all_reasonsrepeated MissReasonKind4
analysis_statusMissAnalysisStatus5
differing_inputsrepeated string6
differing_inputs_total_countuint327
differing_inputs_truncatedbool8
baseline_resolutionBaselineResolution9

enum MissReasonKind#

NameTypeNumberDescription
MISS_REASON_KIND_UNSPECIFIEDvalue0
MISS_REASON_KIND_FIRST_SEENvalue1
MISS_REASON_KIND_INPUTS_CHANGEDvalue2
MISS_REASON_KIND_COMMAND_CHANGEDvalue3
MISS_REASON_KIND_ENV_CHANGEDvalue4
MISS_REASON_KIND_TOOL_CHANGEDvalue5
MISS_REASON_KIND_SALT_CHANGEDvalue6
MISS_REASON_KIND_UNKNOWNvalue7

enum MissAnalysisStatus#

NameTypeNumberDescription
MISS_ANALYSIS_STATUS_UNSPECIFIEDvalue0
MISS_ANALYSIS_STATUS_COMPLETEvalue1
MISS_ANALYSIS_STATUS_PARTIALvalue2
MISS_ANALYSIS_STATUS_TRUNCATEDvalue3
MISS_ANALYSIS_STATUS_UNAVAILABLEvalue4

message BaselineResolution#

NameTypeNumberDescription
kindone of
referenceBaselineReference1
none_availableBaselineNoneAvailable2
not_attemptedBaselineNotAttempted3
unavailableBaselineUnavailable4

message BaselineReference#

NameTypeNumberDescription
previous_run_idstring1
previous_target_instance_idstring2
previous_target_execution_idstring3
previous_action_digestContentRef4
selection_reasonstring5

message BaselineNoneAvailable#

NameTypeNumberDescription

message BaselineNotAttempted#

NameTypeNumberDescription
skip_reasonstring1

message BaselineUnavailable#

NameTypeNumberDescription
failure_reasonstring1

message CacheUpload#

NameTypeNumberDescription
cache_decision_idstring1
target_execution_idstring2
contentContentRef3
tierstring4
kindstring5
duration_msint646
bytes_transferreduint647

message CacheDownload#

NameTypeNumberDescription
cache_decision_idstring1
target_execution_idstring2
contentContentRef3
tierstring4
kindstring5
duration_msint646
bytes_transferreduint647

message CacheStoreReused#

NameTypeNumberDescription
cache_decision_idstring1
target_execution_idstring2
contentContentRef3
tierstring4
kindstring5
bytes_saveduint646

message ArtifactPublished#

NameTypeNumberDescription
target_execution_idstring1
kindstring2
contentContentRef3
workspace_relative_pathstring4

message DiagnosticEmitted#

NameTypeNumberDescription
target_execution_idstring1
severitySeverity2
toolstring3
codestring4
messagestring5
primaryLocation6
relatedrepeated Location7
fingerprintstring8
snippetContentRef9

message Location#

NameTypeNumberDescription
filestring1
start_lineuint322
start_columnuint323
end_lineuint324
end_columnuint325

enum Severity#

NameTypeNumberDescription
SEVERITY_UNSPECIFIEDvalue0
SEVERITY_NOTEvalue1
SEVERITY_WARNINGvalue2
SEVERITY_ERRORvalue3

message SystemSampled#

Periodic host-resource sample published while a run executes so the dashboard's timeline can plot CPU, memory, and network usage over wall-clock. Sampled at a bounded cadence (1 Hz by default) from a single background task on the client. The projector stores each sample as one row and derives the timeline series at read time.

NameTypeNumberDescription
at_epoch_msint641The sample's own wall-clock instant. Enveloping RunEvent.epoch_ms is for display only; RunEvent.seq defines stream order.
cpu_percentfloat2Whole-host CPU utilisation from 0 to 100. Averaged across cores so a 4-core machine at full load reports 100, not 400.
memory_bytesuint643Whole-host memory usage in bytes, matching what a process manager would report as "used".
network_in_bytes_per_seconduint644Network transfer rate at sample time, in bytes per second, summed across all interfaces. Direction is the transport's own point of view: in is bytes coming into the host, out is bytes leaving.
network_out_bytes_per_seconduint645
resource_idstring6A run-local identity, never a hostname or globally stable device key.
scopeResourceScope7
interval_msuint328Actual interval used to derive rates; zero means unavailable.

enum ResourceScope#

NameTypeNumberDescription
RESOURCE_SCOPE_UNSPECIFIEDvalue0
RESOURCE_SCOPE_HOSTvalue1
RESOURCE_SCOPE_CONTAINERvalue2
RESOURCE_SCOPE_PROCESSvalue3
RESOURCE_SCOPE_WORKERvalue4