github.com/tiagovtristao/plz@v13.4.0+incompatible/src/follow/proto/build_event.proto

// Defines the remote streaming protocol for build events.
syntax = "proto3";

package proto.build_event;

service PlzEvents {
    // Receives information about the state of the server's configuration.
    rpc ServerConfig(ServerConfigRequest) returns (ServerConfigResponse);
    // Receives build events from the remote server.
    rpc BuildEvents(BuildEventRequest) returns (stream BuildEventResponse);
    // Receives a stream of information about the server's resource usage.
    rpc ResourceUsage(ResourceUsageRequest) returns (stream ResourceUsageResponse);
}

message ServerConfigRequest{
}

message ServerConfigResponse{
    // The total number of threads that the server is configured to run.
    int32 num_threads = 1;
    // The original targets that the server was requested to run.
    repeated BuildLabel original_targets = 2;
    // True if the server is running tests.
    bool tests = 3;
    // True if the server is running test coverage.
    bool coverage = 4;
    // The most recent event for each server thread.
    // May be shorter than num_threads since some threads may not have had an event yet.
    repeated BuildEventResponse last_events = 5;
    // The time that the build started, as nanoseconds since 1970.
    int64 start_time = 6;
}

message BuildEventRequest{
}

message BuildEventResponse{
    // Internal id of the thread (goroutine, really) that generated this event.
    // These can be used to chain together consecutive events by the same worker.
    // Ids are guaranteed to be allocated sequentially, starting from 0 and are
    // strictly less than num_threads in the corresponding ServerConfigResponse.
    // You aren't necessarily guaranteed to observe events on any or all threads
    // though.
    int32 thread_id = 1;
    // Timestamp of this event, in nanoseconds since the Unix epoch.
    int64 timestamp = 2;
    // Build label that this event relates to.
    BuildLabel build_label = 3;
    // Status of the build.
    BuildResultStatus status = 4;
    // Error, only populated for failure statuses.
    string error = 5;
    // Description of what's going on.
    string description = 6;
    // If the target was a test, this will contain the results of it.
    TestSuite test_results = 7;
    // Labels of the target
    repeated string labels = 8;
    // Number of tasks that are currently "activated", i.e. to be done before the build ends.
    // These are somewhat nebulously defined but can provide a measure of progress, as long as
    // you don't mind this number increasing through the build, tasks taking wildly different
    // amounts of time, and that there isn't a 1:1 correspondence between tasks and these messages.
    int64 num_active = 9;
    // Number of tasks that have been completed so far.
    int64 num_done = 10;
}

message BuildLabel{
    string package_name = 1;
    string name = 2;
}

// A BuildResultStatus describes what has just happened in the event.
enum BuildResultStatus {
    // Build result is unknown. In normal operation this is never set.
    Unknown = 0;
    // Please is beginning to parse a package.
    PackageParsing = 1;
    // The package has been parsed successfully.
    PackageParsed = 2;
    // The package has been parsed, but it failed.
    ParseFailed = 3;
    // Please has started building a target.
    TargetBuilding = 4;
    // Please has reached a target, and the input flags requested it to stop here
    // i.e. the request was something like plz build --prepare or --shell etc
    //      which precludes continuing to actually build the target.
    //      This is not a failure state.
    TargetBuildStopped = 5;
    // The target has been successfully built.
    TargetBuilt = 6;
    // The target was built by retrieving it from the disk, remote or other cache.
    TargetCached = 7;
    // The build of the target failed.
    TargetBuildFailed = 8;
    // Please is beginning to test a target.
    TargetTesting = 9;
    // The target has finished testing and all tests passed.
    TargetTested = 10;
    // The target has finished testing but some tests failed.
    TargetTestFailed = 11;
}

message TestSuite {
    // The package name of the test suite.
    string package = 1;
    // The name of the test suite.
    string name = 2;
    // True if the test results were cached.
    bool cached = 3;
    // Duration that the test ran for, in nanoseconds.
    int64 duration = 4;
    // True if the test failed due to a timeout.
    bool timed_out = 5;
    // The test cases that make up this test suite.
    repeated TestCase test_cases = 6;
    // Any system properties that were set at the time of execution.
    map<string, string> properties = 7;
    // Timestamp of the start of test execution.
    string timestamp = 8;
}

message TestCase {
    // The class name of the test.
    string class_name = 1;
    // The name of the test.
    string name = 2;
    // The separate executions that make up this test case.
    repeated TestExecution test_executions = 3;
}

message TestExecution {
    // The failure, if any, from this attempt at running the test.
    TestFailure failure = 1;
    // The error, if any, from this attempt at running the test.
    TestFailure error = 2;
    // The reason for skipping the test, if any.
    TestSkip skip = 3;
    // Stdout from executing the test.
    string stdout = 4;
    // Stderr from executing the test.
    string stderr = 5;
    // How long this test took to run (in nanoseconds).
    int64 duration = 6;
}

message TestFailure {
    string type = 1;
    string message = 2;
    string traceback = 3;
}

message TestSkip {
    string message = 1;
}

message ResourceUsageRequest{
}

message ResourceUsageResponse{
    // Total number of CPUs available to the system.
    int32 num_cpus = 1;
    // CPU usage that is measured as "in use", excluding I/O, as a percentage.
    double cpu_use = 2;
    // I/O wait, as a percentage of CPU time.
    double io_wait = 3;
    // Total amount of memory available
    uint64 mem_total = 4;
    // Total amount of memory in use.
    uint64 mem_used = 5;
    // Number of inferior worker processes.
    int32 num_worker_processes = 6;
}