rules

package
v0.0.0-...-261f787 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 19, 2024 License: Apache-2.0 Imports: 26 Imported by: 0

Documentation

Overview

Package rules contains methods to read and write failure association rules.

Index

Constants

View Source 
const LUCIAnalysisSystem = "system"

LUCIAnalysisSystem is the special user that identifies changes made by the LUCI Analysis system itself in audit fields.

View Source 
const MaxRuleDefinitionLength = 65536

MaxRuleDefinitionLength is the maximum length of a rule definition.

View Source 
const PolicyIDRePattern = `[a-z]([a-z0-9-]{0,62}[a-z0-9])?`

PolicyIDRePattern is the regular expression pattern that matches validly formed bug management policy IDs. Designed to conform to google.aip.dev/122 resource ID requirements.

View Source 
const RuleIDRePattern = `[0-9a-f]{32}`

RuleIDRe is the regular expression pattern that matches validly formed rule IDs.

Variables

View Source 
var NotExistsErr = errors.New("no matching rule exists")

NotExistsErr is returned by Read methods for a single failure association rule, if no matching rule exists.

View Source 
var PolicyIDRe = regexp.MustCompile(`^` + PolicyIDRePattern + `$`)

PolicyIDRe matches validly formed bug management policy IDs.

View Source 
var RuleIDRe = regexp.MustCompile(`^` + RuleIDRePattern + `$`)

RuleIDRe matches validly formed rule IDs.

View Source 
var StartingEpoch = time.Date(1900, time.January, 1, 0, 0, 0, 0, time.UTC)

StartingEpoch is the rule last updated time used for projects that have no rules (active or otherwise). It is deliberately different from the timestamp zero value to be discernible from "timestamp not populated" programming errors.

View Source 
var StartingVersion = Version{
	Predicates: StartingEpoch,
	Total:      StartingEpoch,
}

StartingEpoch is the rule version used for projects that have no rules (active or otherwise).

View Source 
var UserRe = regexp.MustCompile(`^system|([a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+)$`)

UserRe matches valid users. These are email addresses or the special value "system".

Functions

func ClearRulesUsers 

func ClearRulesUsers(ctx context.Context) error

ClearRulesUsers clears the columns CreationUser and LastAuditableUpdateUser in table FailureAssociationRule.

The retention policy is 63 days, but we delete it at 30 days to allow time to fix issues with the deletion process, as well as allow time for data to be wiped from the underlying storage media.

func Create 

func Create(rule *Entry, user string) (*spanner.Mutation, error)

Create creates a mutation to insert a new failure association rule.

func ExportRulesCron 

func ExportRulesCron(ctx context.Context, projectID string) error

ExportRulesCron is the entry-point to the export failure association rules. It is triggered by a cron job configured in cron.yaml.

func GenerateID 

func GenerateID() (string, error)

GenerateID returns a random 128-bit rule ID, encoded as 32 lowercase hexadecimal characters.

func ReadTotalActiveRules 

func ReadTotalActiveRules(ctx context.Context) (map[string]int64, error)

ReadTotalActiveRules reads the number active rules, for each LUCI Project. Only returns entries for projects that have any rules (at all). Combine with config if you need zero entries for projects that are defined but have no rules.

func SetForTesting 

func SetForTesting(ctx context.Context, t testing.TB, rs []*Entry) error

SetForTesting replaces the set of stored rules to match the given set.

func ToExternalBugManagementStatePB 

func ToExternalBugManagementStatePB(r *bugspb.BugManagementState) *pb.BugManagementState

ToExternalBugManagementStatePB converts the internal *bugspb.BugManagementState to its external (filtered) representation.

func Update 

func Update(rule *Entry, options UpdateOptions, user string) (*spanner.Mutation, error)

Update creates a mutation to update an existing failure association rule. Correctly specify the nature of your changes in UpdateOptions to ensure those changes are saved and that audit timestamps are updated.

func ValidateRuleDefinition 

func ValidateRuleDefinition(ruleDefinition string) error

Types

type Entry 

type Entry struct {

	// The LUCI Project for which this rule is defined.
	Project string
	// The unique identifier for the failure association rule,
	// as 32 lowercase hexadecimal characters.
	RuleID string

	// The rule predicate, defining which failures are being associated.
	RuleDefinition string
	// Whether the bug should be updated by LUCI Analysis, and whether failures
	// should still be matched against the rule.
	IsActive bool
	// The time the rule was last updated in a way that caused the
	// matched failures to change, i.e. because of a change to RuleDefinition
	// or IsActive. (By contrast, updating BugID does NOT change
	// the matched failures, so does NOT update this field.)
	// When this value changes, it triggers re-clustering.
	// Compare with RulesVersion on ReclusteringRuns to identify
	// reclustering state.
	// Output only.
	PredicateLastUpdateTime time.Time

	// BugID is the identifier of the bug that the failures are
	// associated with.
	BugID bugs.BugID
	// Whether this rule should manage the priority and verified status
	// of the associated bug based on the impact of the cluster defined
	// by this rule.
	IsManagingBug bool
	// Whether the bug priority should be updated based on the cluster's impact.
	// This flag is effective only if the IsManagingBug is true.
	// The default value will be false.
	IsManagingBugPriority bool
	// Tracks the last time the field `IsManagingBugPriority` was updated.
	// Defaults to nil which means the field was never updated.
	IsManagingBugPriorityLastUpdateTime time.Time

	// The suggested cluster this rule was created from (if any).
	// Until re-clustering is complete and has reduced the residual impact
	// of the source cluster, this cluster ID tells bug filing to ignore
	// the source cluster when determining whether new bugs need to be filed.
	SourceCluster clustering.ClusterID

	// State used to control automatic bug management.
	// Invariant: BugManagementState != nil
	BugManagementState *bugspb.BugManagementState

	// The time the rule was created. Output only.
	CreateTime time.Time
	// The user which created the rule. Output only.
	CreateUser string
	// The last time an auditable field was updated. An auditable field
	// is any field other than a system controlled data field. Output only.
	LastAuditableUpdateTime time.Time
	// The last user who updated an auditable field. An auditable field
	// is any field other than a system controlled data field. Output only.
	LastAuditableUpdateUser string
	// The time the rule was last updated. Output only.
	LastUpdateTime time.Time
}

Entry represents a failure association rule (a rule which associates failures with a bug). When the rule is used to match incoming test failures, the resultant cluster is known as a 'bug cluster' because the cluster is associated with a bug (via the failure association rule).

func Read 

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

Read reads the failure association rule with the given rule ID. If no rule exists, NotExistsErr will be returned.

func ReadActive 

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

ReadActive reads all active LUCI Analysis failure association rules in the given LUCI project.

func ReadAllForTesting 

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

ReadAllForTesting reads all LUCI Analysis failure association rules. This method is not expected to scale -- for testing use only.

func ReadByBug 

func ReadByBug(ctx context.Context, bugID bugs.BugID) ([]*Entry, error)

ReadByBug reads the failure association rules associated with the given bug. At most one rule will be returned per project.

func ReadDelta 

func ReadDelta(ctx context.Context, project string, sinceTime time.Time) ([]*Entry, error)

ReadDelta reads the changed failure association rules since the given timestamp, in the given LUCI project.

func ReadDeltaAllProjects 

func ReadDeltaAllProjects(ctx context.Context, sinceTime time.Time) ([]*Entry, error)

ReadDeltaAllProjects reads the changed failure association rules since the given timestamp for all LUCI projects.

func ReadMany 

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

ReadMany reads the failure association rules with the given rule IDs. The returned slice of rules will correspond one-to-one the IDs requested (so returned[i].RuleId == ids[i], assuming the rule exists, else returned[i] == nil). If a rule does not exist, a value of nil will be returned for that ID. The same rule can be requested multiple times.

func ReadWithMonorailForProject 

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

ReadWithMonorailForProject reads all LUCI Analysis failure association rules using monorail in the given LUCI Project.

This RPC was introduced for the specific purpose of supporting monorail migration for projects. As rules are never deleted by LUCI Analysis, and this method does no pagination, this style of method will cease to scale at some point.

It has implemented this way only because monorail has a limited remaining life and we seem able to get away with a pagination-free approach for now.

func (Entry) Clone 

func (r Entry) Clone() *Entry

Clone makes a deep copy of the rule.

type RuleBuilder 

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

RuleBuilder provides methods to build a failure asociation rule for testing.

func NewRule 

func NewRule(uniqifier int) *RuleBuilder

NewRule starts building a new Rule.

func (*RuleBuilder) Build 

func (b *RuleBuilder) Build() *Entry

func (*RuleBuilder) WithActive 

func (b *RuleBuilder) WithActive(active bool) *RuleBuilder

WithActive specifies whether the rule will be active.

func (*RuleBuilder) WithBug 

func (b *RuleBuilder) WithBug(bug bugs.BugID) *RuleBuilder

WithBug specifies the bug to use on the rule.

func (*RuleBuilder) WithBugManaged 

func (b *RuleBuilder) WithBugManaged(value bool) *RuleBuilder

WithBugManaged specifies whether the rule's bug will be managed by LUCI Analysis.

func (*RuleBuilder) WithBugManagementState 

func (b *RuleBuilder) WithBugManagementState(state *bugspb.BugManagementState) *RuleBuilder

WithBugManagementState specifies the bug management state for the rule.

func (*RuleBuilder) WithBugPriorityManaged 

func (b *RuleBuilder) WithBugPriorityManaged(isPriorityManaged bool) *RuleBuilder

WithBugPriorityManaged determines whether the rule's bug's priority is managed by LUCI Analysis.

func (*RuleBuilder) WithBugPriorityManagedLastUpdateTime 

func (b *RuleBuilder) WithBugPriorityManagedLastUpdateTime(isManagingBugPriorityLastUpdated time.Time) *RuleBuilder

func (*RuleBuilder) WithBugSystem 

func (b *RuleBuilder) WithBugSystem(bugSystem string) *RuleBuilder

WithBugSystem specifies the bug system to use on the rule.

func (*RuleBuilder) WithCreateTime 

func (b *RuleBuilder) WithCreateTime(value time.Time) *RuleBuilder

WithCreateTime specifies the creation time of the rule.

func (*RuleBuilder) WithCreateUser 

func (b *RuleBuilder) WithCreateUser(user string) *RuleBuilder

WithCreateUser specifies the "created" user on the rule.

func (*RuleBuilder) WithLastAuditableUpdateTime 

func (b *RuleBuilder) WithLastAuditableUpdateTime(value time.Time) *RuleBuilder

WithLastAuditableUpdateTime specifies the "last auditable update" time on the rule.

func (*RuleBuilder) WithLastAuditableUpdateUser 

func (b *RuleBuilder) WithLastAuditableUpdateUser(user string) *RuleBuilder

WithLastAuditableUpdateUser specifies the "last updated" user on the rule.

func (*RuleBuilder) WithLastUpdateTime 

func (b *RuleBuilder) WithLastUpdateTime(lastUpdated time.Time) *RuleBuilder

WithLastUpdateTime specifies the "last updated" time on the rule.

func (*RuleBuilder) WithPredicateLastUpdateTime 

func (b *RuleBuilder) WithPredicateLastUpdateTime(value time.Time) *RuleBuilder

WithPredicateLastUpdateTime specifies the "predicate last updated" time on the rule.

func (*RuleBuilder) WithProject 

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

WithProject specifies the project to use on the rule.

func (*RuleBuilder) WithRuleDefinition 

func (b *RuleBuilder) WithRuleDefinition(definition string) *RuleBuilder

WithRuleDefinition specifies the definition of the rule.

func (*RuleBuilder) WithRuleID 

func (b *RuleBuilder) WithRuleID(id string) *RuleBuilder

WithRuleID specifies the Rule ID to use on the rule.

func (*RuleBuilder) WithSourceCluster 

func (b *RuleBuilder) WithSourceCluster(value clustering.ClusterID) *RuleBuilder

WithSourceCluster specifies the source suggested cluster that triggered the creation of the rule.

type UpdateOptions 

type UpdateOptions struct {
	// IsAuditableUpdate should be set if any auditable field
	// (that is, any field other than a system-controlled data field)
	// has been updated.
	// If set, the values of these fields will be saved and
	// LastAuditableUpdate and LastAuditableUpdateUser will be updated.
	IsAuditableUpdate bool
	// PredicateUpdated should be set if IsActive and/or RuleDefinition
	// have been updated.
	// If set, these new values of these fields will be saved and
	// PredicateLastUpdated will be updated.
	PredicateUpdated bool
	// IsManagingBugPriorityUpdated should be set if IsManagingBugPriority
	// has been updated.
	// If set, the IsManagingBugPriorityLastUpdated will be updated.
	IsManagingBugPriorityUpdated bool
}

UpdateOptions are the options that are using during the update of a rule.

type Version 

type Version struct {
	// Predicates is the last time any rule changed its
	// rule predicate (RuleDefinition or IsActive).
	// Also known as "Rules Version" in clustering contexts.
	Predicates time.Time
	// Total is the last time any rule was updated in any way.
	// Pass to ReadDelta when seeking to read changed rules.
	Total time.Time
}

Version captures version information about a project's rules.

func ReadVersion 

func ReadVersion(ctx context.Context, projectID string) (Version, error)

ReadVersion reads information about when rules in the given project were last updated. This is used to version the set of rules retrieved by ReadActive and is typically called in the same transaction. It is also used to implement change detection on rule predicates for the purpose of triggering re-clustering.

Simply reading the last LastUpdated time of the rules read by ReadActive is not sufficient to version the set of rules read, as the most recent update may have been to mark a rule inactive (removing it from the set that is read).

If the project has no failure association rules, the timestamp StartingEpoch is returned.

Source Files

View all Source files

Directories

Path Synopsis
Package exporter provides methods to interact with the failure_assocation_rules BigQuery table.
 Package exporter provides methods to interact with the failure_assocation_rules BigQuery table.
Package lang parses failure association rule predicates.
 Package lang parses failure association rule predicates.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.