buildgrid.server.build_events.storage module¶

exception buildgrid.server.build_events.storage.DuplicateStreamError¶

Bases: Exception

Error when encountering a name collision between event streams.

class buildgrid.server.build_events.storage.BuildEventStream(stream_id: google.devtools.build.v1.build_events_pb2.StreamId)¶

Bases: object

Internal representation of a stream of OrderedBuildEvents.

This class provides in-memory storage of the events in a given Build Event Stream. Many of these Build Event Streams may relate to the same build, or even to the same invocation of a tool.

Parameters: stream_id (StreamId) – A gRPC message defining the ID of this stream.

publish_event(event: google.devtools.build.v1.publish_build_event_pb2.OrderedBuildEvent) → None¶

Publish an OrderedBuildEvent into the stream.

Parameters: event (OrderedBuildEvent) – The event to publish to the stream. This is an OrderedBuildEvent message from the publish_build_event proto.

query_events(query: Optional[str] = None) → Iterator[google.devtools.build.v1.publish_build_event_pb2.OrderedBuildEvent]¶

Query the contents of this stream.

Filter the contents of the event stream by some query, returning an iterator of matching OrderedBuildEvents.

Note

The filtering functionality of this method is currently not implemented, and the iterator returned contains all the events in the stream no matter what query is used.

Parameters: query (str) – The filter string to use when querying events.

to_grpc_message() → buildgrid.v2.query_build_events_pb2.BuildEventStream¶

Convert this object to a BuildEventStream gRPC message.

This method converts this internal event stream representation into a QueryEventStreamsResponse.BuildEventStream gRPC message, as defined in the query_build_events proto.

class buildgrid.server.build_events.storage.BuildEventStreamStorage¶

Bases: object

In-memory storage of Build Event Streams.

This class stores a collection of Build Event Streams, and handles both creation of new streams and querying the streams which already exist based on their stream ID. Streams are stored in-memory and are lost on service restart, so shouldn’t be relied on as a source of persistent data when using this storage class.

This class is similar to the .*Instance classes used by other BuildGrid services, in that it is instantiated by the config parser and used by a .*Service class instantiated by the server class. Unlike the other instance classes however, this class doesn’t have an instance_name attribute due to the Build Events protos not having the concept of multiple instances.

register_instance_with_server(instance_name: str, server: Server)¶

Register this BuildEventStreamStorage with the BuildGrid server

This method doesn’t make a lot of sense here since this isn’t really an “instance” in the same sense as other services have in BuildGrid.

The Build Events protocol doesn’t have support for instance names, so this is the closest thing to an instance we have however. As such this method is implemented to avoid a special case in the config parsing.

The provided instance name is currently ignored.

Parameters

instance_name (str) – The name of the instance this service is defined in. Currently ignored.
server (Server) – The BuildGrid server to register this storage backend with.

new_stream(stream_id: google.devtools.build.v1.build_events_pb2.StreamId) → buildgrid.server.build_events.storage.BuildEventStream ¶

Create and return a new BuildEventStream with the given ID.

This method creates a new BuildEventStream with the given StreamId, and returns it. If a stream with that ID already exists in this BuildEventStreamStorage, then a DuplicateStreamError is raised.

Parameters: stream_id (StreamId) – The gRPC StreamId message containing the ID of the stream to create.

get_stream(stream_id: google.devtools.build.v1.build_events_pb2.StreamId) → buildgrid.server.build_events.storage.BuildEventStream ¶

Return a BuildEventStream with the given stream ID.

This method takes a stream ID, converts it to a stream key, and returns the stream with that key if one exists.

This method will create a new BuildEventStream if one with the given ID doesn’t exist.

Parameters: stream_id (StreamId) – The StreamID message from an event to get the BuildEventStream for.
Returns: A BuildEventStream with the given ID, or None.

get_matching_streams(stream_key_regex: str) → List[buildgrid.server.build_events.storage.BuildEventStream]¶

Return a list of event streams which match the given key pattern.

This method takes a regular expression as a string, and returns a list of BuildEventStream objects whose stream key (based on the events’ StreamId) matches the regex.

Parameters: stream_key_regex (str) – A regular expression to use to find matching streams.
Returns: List of BuildEventStream objects which have a key matching the given regex.