metrics

Documentation

Overview

Package metrics defines metrics for various build events, and utility functions to be used in other modules for the metric updates.

Index

• Variables
• func BuildCompleted(ctx context.Context, b *model.Build)
• func BuildCreated(ctx context.Context, b *model.Build)
• func BuildStarted(ctx context.Context, b *model.Build)
• func ExpiredLeaseReset(ctx context.Context, b *model.Build)
• func GetBaseFieldMap(bp *pb.Build, base pb.CustomMetricBase) (map[string]string, error)
• func GetCommonBaseFields(base pb.CustomMetricBase) ([]string, error)
• func GetCustomMetricsData(ctx context.Context, base pb.CustomMetricBase, name string, fvs []any) (any, error)
• func IsBuilderMetric(base pb.CustomMetricBase) bool
• func ReportBuilderMetrics(ctx context.Context) error
• func ValidateExtraFieldsWithBase(base pb.CustomMetricBase, extraFields []string) error
• func WithBuilder(ctx context.Context, project, bucket, builder string) context.Context
• func WithCustomMetrics(ctx context.Context, globalCfg *pb.SettingsCfg) (context.Context, error)
• func WithServiceInfo(ctx context.Context, service, job, instance string) context.Context
• type CustomMetric
• type CustomMetrics
  • func GetCustomMetrics(ctx context.Context) *CustomMetrics
  • func (cms *CustomMetrics) Flush(ctx context.Context, globalCfg *pb.SettingsCfg, mon monitor.Monitor) error
  • func (cms *CustomMetrics) Report(ctx context.Context, rs ...*Report) bool
• type Report

Variables

var (
	BaseFields = map[pb.CustomMetricBase]baseFields{
		pb.CustomMetricBase_CUSTOM_METRIC_BASE_COUNT:                     {/* contains filtered or unexported fields */},
		pb.CustomMetricBase_CUSTOM_METRIC_BASE_CREATED:                   {/* contains filtered or unexported fields */},
		pb.CustomMetricBase_CUSTOM_METRIC_BASE_STARTED:                   {/* contains filtered or unexported fields */},
		pb.CustomMetricBase_CUSTOM_METRIC_BASE_COMPLETED:                 {/* contains filtered or unexported fields */},
		pb.CustomMetricBase_CUSTOM_METRIC_BASE_CYCLE_DURATIONS:           {/* contains filtered or unexported fields */},
		pb.CustomMetricBase_CUSTOM_METRIC_BASE_RUN_DURATIONS:             {/* contains filtered or unexported fields */},
		pb.CustomMetricBase_CUSTOM_METRIC_BASE_SCHEDULING_DURATIONS:      {/* contains filtered or unexported fields */},
		pb.CustomMetricBase_CUSTOM_METRIC_BASE_CONSECUTIVE_FAILURE_COUNT: {/* contains filtered or unexported fields */},
		pb.CustomMetricBase_CUSTOM_METRIC_BASE_MAX_AGE_SCHEDULED:         {},
	}

	// V2 is a collection of metric objects for V2 metrics.
	// Note: when adding new metrics here, please also update bbInternalMetrics
	// in config/config.go.
	V2 = struct {
		BuildCount              metric.Int
		BuildCountCreated       metric.Counter
		BuildCountStarted       metric.Counter
		BuildCountCompleted     metric.Counter
		BuildDurationCycle      metric.CumulativeDistribution
		BuildDurationRun        metric.CumulativeDistribution
		BuildDurationScheduling metric.CumulativeDistribution
		BuilderPresence         metric.Bool
		ConsecutiveFailureCount metric.Int
		MaxAgeScheduled         metric.Float
	}{
		BuildCount: metric.NewIntWithOptions(
			"buildbucket/v2/builds/count",
			opt,
			"Number of pending/running prod builds",
			nil,
			generateBaseFields(pb.CustomMetricBase_CUSTOM_METRIC_BASE_COUNT)...,
		),
		BuildCountCreated: metric.NewCounterWithOptions(
			"buildbucket/v2/builds/created",
			opt,
			"Build creation",
			nil,
			generateBaseFields(pb.CustomMetricBase_CUSTOM_METRIC_BASE_CREATED)...,
		),
		BuildCountStarted: metric.NewCounterWithOptions(
			"buildbucket/v2/builds/started",
			opt,
			"Build start",
			nil,
			generateBaseFields(pb.CustomMetricBase_CUSTOM_METRIC_BASE_STARTED)...,
		),
		BuildCountCompleted: metric.NewCounterWithOptions(
			"buildbucket/v2/builds/completed",
			opt,
			"Build completion, including success, failure and cancellation",
			nil,
			generateBaseFields(pb.CustomMetricBase_CUSTOM_METRIC_BASE_COMPLETED)...,
		),
		BuildDurationCycle: metric.NewCumulativeDistributionWithOptions(
			"buildbucket/v2/builds/cycle_durations",
			opt,
			"Duration between build creation and completion",
			&types.MetricMetadata{Units: types.Seconds},
			bucketer,
			generateBaseFields(pb.CustomMetricBase_CUSTOM_METRIC_BASE_CYCLE_DURATIONS)...,
		),
		BuildDurationRun: metric.NewCumulativeDistributionWithOptions(
			"buildbucket/v2/builds/run_durations",
			opt,
			"Duration between build start and completion",
			&types.MetricMetadata{Units: types.Seconds},
			bucketer,
			generateBaseFields(pb.CustomMetricBase_CUSTOM_METRIC_BASE_RUN_DURATIONS)...,
		),
		BuildDurationScheduling: metric.NewCumulativeDistributionWithOptions(
			"buildbucket/v2/builds/scheduling_durations",
			opt,
			"Duration between build creation and start",
			&types.MetricMetadata{Units: types.Seconds},
			bucketer,
			generateBaseFields(pb.CustomMetricBase_CUSTOM_METRIC_BASE_SCHEDULING_DURATIONS)...,
		),
		BuilderPresence: metric.NewBoolWithOptions(
			"buildbucket/v2/builder/presence",
			opt,
			"A constant, always-true metric that indicates the presence of LUCI Builder",
			nil,
		),
		ConsecutiveFailureCount: metric.NewIntWithOptions(
			"buildbucket/v2/builds/consecutive_failure_count",
			opt,
			"Number of consecutive non-successful build terminations since the last successful build.",
			nil,
			generateBaseFields(pb.CustomMetricBase_CUSTOM_METRIC_BASE_CONSECUTIVE_FAILURE_COUNT)...,
		),
		MaxAgeScheduled: metric.NewFloatWithOptions(
			"buildbucket/v2/builds/max_age_scheduled",
			opt,
			"Age of the oldest SCHEDULED build",
			&types.MetricMetadata{Units: types.Seconds},
		),
	}
)

var (

	// V1 is a collection of metric objects for V1 metrics.
	// Note: when adding new metrics here, please also update bbInternalMetrics
	// in config/config.go.
	V1 = struct {
		BuildCount              metric.Int
		BuildCountCreated       metric.Counter
		BuildCountStarted       metric.Counter
		BuildCountCompleted     metric.Counter
		BuildDurationCycle      metric.CumulativeDistribution
		BuildDurationRun        metric.CumulativeDistribution
		BuildDurationScheduling metric.CumulativeDistribution
		ExpiredLeaseReset       metric.Counter
		MaxAgeScheduled         metric.Float
	}{
		BuildCount: metric.NewInt(
			"buildbucket/builds/count",
			"Number of pending/running prod builds", nil,
			bFields("status")...,
		),
		BuildCountCreated: metric.NewCounter(
			"buildbucket/builds/created",
			"Build creation", nil,
			bFields("user_agent")...,
		),
		BuildCountStarted: metric.NewCounter(
			"buildbucket/builds/started",
			"Build start", nil,
			bFields("canary")...,
		),
		BuildCountCompleted: metric.NewCounter(
			"buildbucket/builds/completed",
			"Build completion, including success, failure and cancellation", nil,
			bFields("result", "failure_reason", "cancelation_reason", "canary")...,
		),
		BuildDurationCycle: newbuildDurationMetric(
			"buildbucket/builds/cycle_durations",
			"Duration between build creation and completion",
		),
		BuildDurationRun: newbuildDurationMetric(
			"buildbucket/builds/run_durations",
			"Duration between build start and completion",
		),
		BuildDurationScheduling: newbuildDurationMetric(
			"buildbucket/builds/scheduling_durations",
			"Duration between build creation and start",
		),
		ExpiredLeaseReset: metric.NewCounter(
			"buildbucket/builds/lease_expired",
			"Build lease expirations", nil,
			bFields("status")...,
		),
		MaxAgeScheduled: metric.NewFloat(
			"buildbucket/builds/max_age_scheduled",
			"Age of the oldest SCHEDULED build",
			&types.MetricMetadata{Units: types.Seconds},
			bFields("must_be_never_leased")...,
		),
	}
)

Functions

func BuildCompleted

func BuildCompleted(ctx context.Context, b *model.Build)

BuildCompleted updates metrics for a build completion event.

func BuildCreated

func BuildCreated(ctx context.Context, b *model.Build)

BuildCreated updates metrics for a build creation event.

func BuildStarted

func BuildStarted(ctx context.Context, b *model.Build)

BuildStarted updates metrics for a build start event.

func ExpiredLeaseReset

func ExpiredLeaseReset(ctx context.Context, b *model.Build)

ExpiredLeaseReset updates metrics for an expired lease reset.

func GetBaseFieldMap

func GetBaseFieldMap(bp *pb.Build, base pb.CustomMetricBase) (map[string]string, error)

GetBaseFieldMap returns the common default fields and their values of metrics with the provided base.

func GetCommonBaseFields

func GetCommonBaseFields(base pb.CustomMetricBase) ([]string, error)

GetCommonBaseFields returns the common default fields of metrics with the provided base.

func GetCustomMetricsData

func GetCustomMetricsData(ctx context.Context, base pb.CustomMetricBase, name string, fvs []any) (any, error)

func IsBuilderMetric

func IsBuilderMetric(base pb.CustomMetricBase) bool

IsBuilderMetric returns whether the provided base is for a builder metric.

func ReportBuilderMetrics

func ReportBuilderMetrics(ctx context.Context) error

ReportBuilderMetrics computes and reports Builder metrics.

func ValidateExtraFieldsWithBase

func ValidateExtraFieldsWithBase(base pb.CustomMetricBase, extraFields []string) error

ValidateExtraFieldsWithBase performs metric base related validations on extraFields.

func WithBuilder

func WithBuilder(ctx context.Context, project, bucket, builder string) context.Context

WithBuilder returns a context for a Builder target with the given info.

WithServiceInfo must be called once before this function. Otherwise, this panics.

func WithCustomMetrics

func WithCustomMetrics(ctx context.Context, globalCfg *pb.SettingsCfg) (context.Context, error)

WithCustomMetrics creates a CustomMetrics with dedicated tsmon.State to register custom metrics from service config, and store it in context.

This function should only be called at server start up.

func WithServiceInfo

func WithServiceInfo(ctx context.Context, service, job, instance string) context.Context

WithServiceInfo sets the service info to be set in the Builder target.

Call this in the initialization of a server process.

Types

type CustomMetric

type CustomMetric interface {
	// contains filtered or unexported methods
}

CustomMetric is an interface to report custom metrics.

type CustomMetrics

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

CustomMetrics holds the custom metrics and a dedicated tsmon state to report metrics to.

func GetCustomMetrics

func GetCustomMetrics(ctx context.Context) *CustomMetrics

GetCustomMetrics returns the CustomMetrics intalled in the current context. Panic if not found in the context.

func (*CustomMetrics) Flush

func (cms *CustomMetrics) Flush(ctx context.Context, globalCfg *pb.SettingsCfg, mon monitor.Monitor) error

Flush flushes all stored metrics. But before flush, it also checks if there's any change in service config that requires to update cms.metrics and recreate cms.state. If yes, it'll reset cms.state - so the upcoming reports can be buffered, then perform the updates. After cms.metrics are updated, it then adds all the buffered reports back to the new cms.state.

Called by a backendground job periodically. Must not be called concurrently.

func (*CustomMetrics) Report

func (cms *CustomMetrics) Report(ctx context.Context, rs ...*Report) bool

Report tries to report one or more metric. If it couldn't do the report directly (e.g. a metric state recreation is happening), it will save the reports to a buffer. Returns a bool to indicate if it's a direct report or not (mostly for testing).

type Report

type Report struct {
	Base     pb.CustomMetricBase
	Name     string
	FieldMap map[string]string
	Value    any
}