state

Documentation

Index

• Variables
• func Create(ctx context.Context, e *Entry) error
• func CreateEntriesForTesting(ctx context.Context, entries []*Entry) (commitTimestamp time.Time, err error)
• func EstimateChunks(ctx context.Context, project string) (int, error)
• func ReadLastUpdated(ctx context.Context, keys []ChunkKey) ([]time.Time, error)
• func ReadProjects(ctx context.Context) ([]string, error)
• func UpdateClustering(ctx context.Context, previous *Entry, update *clustering.ClusterResults) error
• type ChunkKey
  • func (k ChunkKey) String() string
• type Entry
  • func Read(ctx context.Context, project, chunkID string) (*Entry, error)
  • func ReadAllForTesting(ctx context.Context, project string) ([]*Entry, error)
  • func ReadNextN(ctx context.Context, project string, opts ReadNextOptions, n int) ([]*Entry, error)
• type EntryBuilder
  • func NewEntry(uniqifier int) *EntryBuilder
  • func (b *EntryBuilder) Build() *Entry
  • func (b *EntryBuilder) WithAlgorithmsVersion(version int64) *EntryBuilder
  • func (b *EntryBuilder) WithChunkIDPrefix(prefix string) *EntryBuilder
  • func (b *EntryBuilder) WithConfigVersion(version time.Time) *EntryBuilder
  • func (b *EntryBuilder) WithProject(project string) *EntryBuilder
  • func (b *EntryBuilder) WithRulesVersion(version time.Time) *EntryBuilder
• type ReadNextOptions

Variables

var EndOfTable = strings.Repeat("ff", 16)

EndOfTable is the highest possible chunk ID that can be stored.

var NotFoundErr = errors.New("clustering state row not found")

NotFound is the error returned by Read if the row could not be found.

Functions

func Create

func Create(ctx context.Context, e *Entry) error

Create inserts clustering state for a chunk. Must be called in the context of a Spanner transaction.

func CreateEntriesForTesting

func CreateEntriesForTesting(ctx context.Context, entries []*Entry) (commitTimestamp time.Time, err error)

CreateEntriesForTesting creates the given entries, for testing.

func EstimateChunks

func EstimateChunks(ctx context.Context, project string) (int, error)

EstimateChunks estimates the total number of chunks in the ClusteringState table for the given project.

func ReadLastUpdated

func ReadLastUpdated(ctx context.Context, keys []ChunkKey) ([]time.Time, error)

ReadLastUpdated reads the last updated time of the specified chunks. If the chunk does not exist, the zero time value time.Time{} is returned. Unless an error is returned, the returned slice will be of the same length as chunkIDs. The i-th LastUpdated time returned will correspond to the i-th chunk ID requested.

func ReadProjects

func ReadProjects(ctx context.Context) ([]string, error)

ReadProjects read all distinct projects with a clustering state entry..

func UpdateClustering

func UpdateClustering(ctx context.Context, previous *Entry, update *clustering.ClusterResults) error

UpdateClustering updates the clustering results on a chunk.

To avoid clobbering other concurrent updates, the caller should read the LastUpdated time of the chunk in the same transaction as it is updated (i.e. using ReadLastUpdated) and verify it matches the previous entry passed.

The update uses the previous entry to avoid writing cluster data if it has not changed, which optimises the performance of minor reclusterings.

Types

type ChunkKey

type ChunkKey struct {
	Project string
	ChunkID string
}

ChunkKey represents the identify of a chunk.

func (ChunkKey) String

func (k ChunkKey) String() string

String returns a string representation of the key, for use in dictionaries.

type Entry

type Entry struct {
	// Project is the LUCI Project the chunk belongs to.
	Project string
	// ChunkID is the identity of the chunk of test results. 32 lowercase hexadecimal
	// characters assigned by the ingestion process.
	ChunkID string
	// PartitionTime is the start of the retention period of the test results in the chunk.
	PartitionTime time.Time
	// ObjectID is the identity of the object in GCS containing the chunk's test results.
	// 32 lowercase hexadecimal characters.
	ObjectID string
	// Clustering describes the latest clustering of test results in
	// the chunk.
	Clustering clustering.ClusterResults
	// LastUpdated is the Spanner commit time the row was last updated. Output only.
	LastUpdated time.Time
}

Entry represents the clustering state of a chunk, consisting of:

• Metadata about what test results were clustered.
• Metadata about how the test results were clustered (the algorithms and failure association rules used).
• The clusters each test result are in.

func Read

func Read(ctx context.Context, project, chunkID string) (*Entry, error)

Read reads clustering state for a chunk. Must be called in the context of a Spanner transaction. If no clustering state exists, the method returns the error NotFound.

func ReadAllForTesting

func ReadAllForTesting(ctx context.Context, project string) ([]*Entry, error)

ReadAllForTesting reads all state entries in the given project (up to 1 million records) for testing.

func ReadNextN

func ReadNextN(ctx context.Context, project string, opts ReadNextOptions, n int) ([]*Entry, error)

ReadNextN reads the n consecutively next clustering state entries matching ReadNextOptions.

type EntryBuilder

type EntryBuilder struct {
	// contains filtered or unexported fields
}

EntryBuilder provides methods to build a new Entry.

func NewEntry

func NewEntry(uniqifier int) *EntryBuilder

NewEntry creates a new entry builder with the given uniqifier. The uniqifier affects the ChunkID, AlgorithmVersion, RulesVersion and Algorithms.

func (*EntryBuilder) Build

func (b *EntryBuilder) Build() *Entry

Build returns the built entry.

func (*EntryBuilder) WithAlgorithmsVersion

func (b *EntryBuilder) WithAlgorithmsVersion(version int64) *EntryBuilder

WithAlgorithmsVersion specifies the algorithms version for the entry.

func (*EntryBuilder) WithChunkIDPrefix

func (b *EntryBuilder) WithChunkIDPrefix(prefix string) *EntryBuilder

WithChunkIDPrefix specifies the start of the ChunkID to use. The remaining ChunkID will be derived from the uniqifier.

func (*EntryBuilder) WithConfigVersion

func (b *EntryBuilder) WithConfigVersion(version time.Time) *EntryBuilder

WithConfigVersion specifies the config version for the entry.

func (*EntryBuilder) WithProject

func (b *EntryBuilder) WithProject(project string) *EntryBuilder

WithProject specifies the LUCI project for the entry.

func (*EntryBuilder) WithRulesVersion

func (b *EntryBuilder) WithRulesVersion(version time.Time) *EntryBuilder

WithRulesVersion specifies the rules version for the entry.

type ReadNextOptions

type ReadNextOptions struct {
	// The exclusive lower bound of the range of ChunkIDs to read.
	// To read from the start of the table, leave this blank ("").
	StartChunkID string
	// The inclusive upper bound of the range of ChunkIDs to read.
	// To specify the end of the table, use the constant EndOfTable.
	EndChunkID string
	// The minimum AlgorithmsVersion that re-clustering wants to achieve.
	// If a row has an AlgorithmsVersion less than this value, it will
	// be eligble to be read.
	AlgorithmsVersion int64
	// The minimum ConfigVersion that re-clustering wants to achieve.
	// If a row has an RulesVersion less than this value, it will
	// be eligble to be read.
	ConfigVersion time.Time
	// The minimum RulesVersion that re-clustering wants to achieve.
	// If a row has an RulesVersion less than this value, it will
	// be eligble to be read.
	RulesVersion time.Time
}

ReadNextOptions specifies options for ReadNextN.